Installation
Install celld-operator with Helm (recommended) or kustomize. The operator runs in its own
namespace and reconciles WorkerApp resources cluster-wide by default, or in a
single namespace when you scope it.
Prerequisites
- Kubernetes 1.30 or newer and cluster-admin access to install CRDs.
1.30 is the version the operator is developed against; the chart sets no
kubeVersionfloor, so older clusters install without warning and are untested. - IPv4-capable pod networking. celld's listeners bind IPv4; IPv6-only clusters are not supported.
- A qualified object store. celld's ownership fencing requires atomically enforced conditional writes, exact ranged reads, and read-after-write consistency. Qualified: Amazon S3, Cloudflare R2, Google Cloud Storage, Tigris, and Azure Blob Storage. Not qualified: Backblaze B2, DigitalOcean Spaces, Hetzner Object Storage, MinIO community edition (it passes the storage test but is not qualified for production), and Azurite. See Object stores; every celld node also probes the store at startup and refuses to serve if the contract fails.
Optional integrations
None of these is required to start reconciling. Missing CRDs are reported as a condition on each affected WorkerApp; a missing controller behind an Ingress or a certificate is not detectable, so it shows up as a route nothing serves.
| Integration | What it enables | When absent |
|---|---|---|
| Gateway API CRDs + an implementation (Istio recommended) | Hostname ingress via one HTTPRoute per app on a shared Gateway. Standard-channel CRDs are enough; the optional drain-503 retry needs the experimental channel and operator.httpRouteRetries: true | IngressReady: False (GatewayAPIUnavailable); hostnames are not routed |
| Istio (ambient mode recommended) | An AuthorizationPolicy on the internal listener; mTLS for the peer network | MeshPolicyReady: False (IstioUnavailable); NetworkPolicy alone guards :8081 |
| KEDA v2.12.0+ + Prometheus scraping the operator | Custom-metrics autoscaling. Needed only by WorkerApps with spec.autoscaling.enabled; the operator waits for KEDA's Paused=True acknowledgement before every rollout | AutoscalingReady: False (KEDAUnavailable); spec.autoscaling has no effect |
| An ingress controller (ingress-nginx, Traefik, a cloud controller) | ingressMode: ingress | IngressReady stays Unknown: the Ingress exists and nothing serves it |
| cert-manager | clusterIssuer: per-app TLS on emitted Ingresses | The annotation is written and no certificate is issued |
Ambient mode, not sidecars. celld makes outbound peer and bucket calls during termination, and a sidecar that exits first would break the cell handoff. Ambient mode encrypts the peer network without putting a proxy in celld's drain path.
Install with Helm
The chart is published to GHCR as an OCI artifact on every release. Start with a values file: the operator refuses WorkerApps whose image, cloud identity, or bucket endpoint is not explicitly allowed, so set the allowlists for the fleets you plan to run.
# values.yaml
operator:
ingressMode: httproute # or virtualservice / ingress / none
gatewayName: edge
gatewayNamespace: infra
allowedImagePrefixes: ["ghcr.io/denoland/celld:"]
allowedIAMRoles: ["arn:aws:iam::123456789012:role/celld-chat"]
allowedAzureClientIDs: []
allowedBucketEndpoints: ["https://ACCOUNT.r2.cloudflarestorage.com"]
prometheus:
enable: true # ServiceMonitor, for autoscaling
$ helm install celld-operator oci://ghcr.io/ezgamehost/charts/celld-operator \
--namespace celld-operator-system --create-namespace -f values.yaml
Nearly every operator flag is a value under operator.*; the
operator configuration reference lists them
all. --operator-namespace follows the release namespace, and the manager's
own flags (leader election, probes) live under controllerManager.container.args.
The chart's default image tag is its appVersion, pinned at package time to
the operator build it was released with.
Namespace-scoped install
Set operator.watchNamespace to restrict the manager's cache, and the
chart's workload Role, to one namespace. With a shared Gateway in another namespace,
also grant the manager ServiceAccount get on that Gateway through a
Role and RoleBinding there; otherwise IngressReady stays
Unknown. Leave it empty for cluster-wide reconciliation.
Install with kustomize
From a clone of the repository:
$ make install # CRDs only
$ make docker-build docker-push IMG=<registry>/celld-operator:tag
$ make deploy IMG=<registry>/celld-operator:tag
Run locally during development
The operator can run outside the cluster against your current kubeconfig:
$ make run
Verify the installation
$ kubectl get pods -n celld-operator-system
NAME READY STATUS RESTARTS
celld-operator-controller-manager-7d9c6bf9c9-x2m4p 1/1 Running 0
$ kubectl get crd workerapps.celld-operator.io
NAME CREATED AT
workerapps.celld-operator.io 2026-10-18T00:00:00Z
Fleet NetworkPolicies admit the manager to each fleet's internal listener by its pod
labels, so keep control-plane: controller-manager and
app.kubernetes.io/name: celld-operator on the manager pods if you customize
the chart. With the operator running, continue to the
quick start.
Upgrading the operator
Upgrade with helm upgrade using the new chart version, and read the
production upgrade requirements
first. Recent releases intentionally reject configurations older ones accepted:
- fleet-durability WorkerApps without persistent storage need an explicit migration to a new WorkerApp;
- custom images, IAM roles, Azure identities, and non-AWS bucket endpoints need allowlist entries;
appVersion: autoneeds a dedicated read-onlydeployTrackingSecretRef;spec.varsis rejected for celld v0.5 and newer.
A WorkerApp that fails validation reports SpecValid: False with the reason
and phase Degraded; the operator leaves its existing fleet untouched.
Keep the operator current as you track celld releases: the operator encodes celld's
version boundaries, and its expectations of
celld's alpha /state API are pinned per release.