cf-container-orchestrator

A generic Cloudflare Containers operator with fleet management, restart policies, and crash loop protection. Built with Effect-TS.

Features

• Min Replica Set Management: Define containers that should always be running, with automatic reconciliation
• Restart Policies: Configure when containers should restart (always, on_failure, never)
• Crash Loop Protection: Automatically detect and prevent crash loops
• Lifecycle Events: Containers report start/stop/error events to the operator

Installation

pnpm add @jonbeckman/cf-container-orchestrator

Use Case

I built this for my own use case of running a replication set of services, each with their own configuration and lifecycle management requirements.

In practice, that means:

• High Availability: Enforcing a "min replica set" of services that must always be running (with automatic restarts and crash-loop protection).
• Dynamic Configuration: Injecting specific secrets and configuration into each container instance at runtime.
• Lifecycle Management: Starting, stopping, and restarting containers as needed. I wrapped this into an API to call remotely.

For a complete guide on how to integrate and use the library, check out the Example Guide.

API Reference

ManagedContainer

Base class for containers managed by the operator.

Properties

| Property | Type | Description | | ------------- | -------- | --------------------------------------------- | | defaultPort | number | Port the container listens on | | sleepAfter | string | Duration before container sleep (e.g., "30m") |

Methods

| Method | Description | | ----------------------------- | ---------------------------------------- | | getManagedContainerConfig() | Override to configure container behavior | | onContainerStart() | Called when container starts | | onContainerStop(params) | Called when container stops | | onContainerError(error) | Called when container errors | | getManagedState() | Get extended state with uptime info |

createContainerOperator

Factory function to create an operator class.

Options

| Option | Type | Default | Description | | ---------------------- | --------------------------------------- | ------------------ | -------------------------------------- | | minReplicaSet | ContainerSpec[] | [] | Containers to auto-manage | | envVarsBuilder | (spec, env) => Record<string, string> | Required | Builds env vars for containers | | containerNameEnvKey | string | "CONTAINER_NAME" | Env var key for container name | | reconcileIntervalMs | number | 60000 | Reconciliation interval (0 to disable) | | allowAdHocContainers | boolean | true | Allow non-min replica set containers |

Operator Methods

| Method | Description | | -------------------------------- | ------------------------------- | | startContainer(config, force?) | Start a container | | stopContainer(name) | Stop a container | | getContainerInfo(name) | Get info for a container | | listContainers() | List all containers | | removeContainer(name) | Remove a stopped container | | clearCrashHistory(name) | Clear crash history | | reconcile() | Manually trigger reconciliation |

Restart Policies

defaultRestartPolicy()

Restarts on failure with crash loop protection:

• Restart when: on_failure
• Crash window: 10 minutes
• Allowed crashes: 3

alwaysRestartPolicy()

Always restart, with crash loop protection.

neverRestartPolicy()

Never restart automatically.

Custom Policy

const customPolicy: RestartPolicy = {
  when: "on_failure",
  crash: {
    windowMs: 5 * 60 * 1000, // 5 minutes
    allowedCrashes: 5,
  },
}

Error Handling

The package exports typed errors for handling specific failure cases:

import {
  ContainerNotFoundError,
  CrashLoopDetectedError,
  ContainerNotStoppedError,
  MinReplicaSetContainerError,
} from "@jonbeckman/cf-container-orchestrator"

// Errors have static factory methods
const error = ContainerNotFoundError.of("my-container")
console.log(error.message) // "Container not found: my-container"

Roadmap

• [ ] Built-in API
• [ ] Built-in UI
• [ ] Add configuration for individual container
  • [ ] health check
  • [ ] region placement
  • [ ] compute resources
• [ ] Support custom rollout strategies
  • Currently not possible as Cloudflare controls the rollout via the API, not via Container or Durable Object SDK
• [ ] Typed exits codes

Development

First, install the dependencies:

pnpm install

Local CI/CD

First, install the act CLI.

Then, run the CI/CD workflow locally:

unset GITHUB_TOKEN && act -j ci -s GITHUB_TOKEN="$(gh auth token)" --container-architecture linux/amd64

License

MIT