celld-operator

Quick start

From a standard Wrangler project to a converged, routed celld fleet. This walkthrough assumes the operator is installed and you have a qualified bucket (Cloudflare R2 in the examples).

Before you begin

You need the celld CLI on your workstation or CI runner to publish deployments; the operator never touches your build:

$ curl -fsSL https://celld.dev/install.sh | sh   # verifiable with gh attestation verify

Projects with Worker code also need esbuild on PATH; asset-only projects do not.

1. Deploy your Worker to the bucket

A standard Wrangler project: wrangler.jsonc (or .json; wrangler.toml is not accepted), module Workers, Durable Objects, and the bindings celld supports. Worker variables belong in the project's own vars: celld v0.5 and newer read them from the deployment, not from the cluster. Publish to the fleet's bucket prefix:

$ celld deploy . --bucket s3://platform-cells/apps/chat \
    --endpoint https://ACCOUNT.r2.cloudflarestorage.com --region auto
…
Current Version ID: a3f9c1d2e4b57081

celld validates the config with a strict top-level key allowlist: an unsupported key (routes, for example) stops the deploy with an error naming the key, so nothing fails silently at runtime. Run celld deploy . --dry-run in CI to catch this on pull requests.

2. Allow the fleet's endpoint and identity

The operator only accepts images, cloud identities, and bucket endpoints that an administrator has allowlisted. For this example, the R2 endpoint and the IAM role must appear in the operator's values:

operator:
  allowedImagePrefixes: ["ghcr.io/denoland/celld:"]   # the default
  allowedIAMRoles: ["arn:aws:iam::123456789012:role/celld-chat"]
  allowedBucketEndpoints: ["https://ACCOUNT.r2.cloudflarestorage.com"]

An AWS S3 bucket needs no endpoint entry. A WorkerApp that misses the allowlist reports SpecValid: False and the operator creates nothing for it.

3. Create the WorkerApp

apiVersion: celld-operator.io/v1alpha1
kind: WorkerApp
metadata:
  name: chat
  namespace: tenant-acme
spec:
  hostnames: ["chat.acme.example.com"]  # routed via the shared Gateway
  appVersion: a3f9c1d2e4b57081          # the Version ID celld deploy printed
  celld:
    image: ghcr.io/denoland/celld:v0.6.2
    updateStrategy: Rolling            # Recreate for non-rolling celld upgrades
  replicas: 3
  bucket:
    name: s3://platform-cells/apps/chat # bucket + per-app prefix; immutable
    endpoint: https://ACCOUNT.r2.cloudflarestorage.com
    region: auto
    credentialsFrom:
      iamRole: arn:aws:iam::123456789012:role/celld-chat  # IRSA; or secretRef
  resources:
    memoryGi: 8                        # ~1,000 resident cells per 8 GiB
    maxResidentCells: 1000
  durability: bucket                   # the default; fleet needs storage + 3 replicas
  websockets: true                     # long edge timeouts, slow scale-down
  telemetry:
    enabled: true                      # Parquet traces in the bucket by default
    retention: 30d
$ kubectl apply -f workerapp.yaml

The image tag must carry a numeric major.minor.patch version, even when digest-pinned: the operator reads it to decide which upgrades can roll. Autoscaling is off here; turn it on once KEDA is installed (see Autoscaling).

4. Watch it converge

$ kubectl get workerapps -n tenant-acme
NAME   PHASE   APP                READY   RESTORING   AGE
chat   Ready   a3f9c1d2e4b57081   3       0           2m

APP fills in only when every pod reports that it serves the expected deployment with nothing draining or swapping. If an optional integration is missing, the fleet keeps serving where it can and reports the gap as a condition:

$ kubectl describe workerapp chat -n tenant-acme
…
Conditions:
  Type                     Status   Reason
  SpecValid                True     Validated
  BucketCredentialsReady   True     Configured
  IngressReady             True     RouteObserved
  MeshPolicyReady          False    IstioUnavailable
  FleetStateReady          True     Observed
  Available               True     Ready
  Progressing              False    Ready
  Degraded                 False    Ready

Here Istio is absent, so the NetworkPolicy alone guards the internal listener; the fleet still serves. IngressReady is True only when the route is accepted, its backend resolves, and the Gateway reports itself programmed.

5. Send a request

$ curl https://chat.acme.example.com/rooms/lobby

No hostnames? Internal-only apps need no ingress at all: in-cluster consumers reach the fleet at chat-celld.tenant-acme.svc:8080.

6. Ship an update

$ celld deploy . --bucket s3://platform-cells/apps/chat …
Current Version ID: 7b21e0c4a9d3f508
$ kubectl patch workerapp chat -n tenant-acme --type merge \
    -p '{"spec":{"appVersion":"7b21e0c4a9d3f508"}}'

celld v0.4 and newer poll the bucket pointer every 30 seconds and adopt the new deployment in place, so the fleet starts serving it without a restart. Bumping appVersion keeps the resource in step: by default the operator also runs a conservative gated restart (one pod at a time, stepping only when the whole fleet reports restoring=0), or none at all with deploymentPolicy: InPlace. Prefer celld deploy to be the whole story? Set appVersion: auto with a read-only tracking credential. Both flows are covered in Deploying updates.

Edit this page on GitHubUpdated 2026-10-18