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.