celld-operator

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

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.

IntegrationWhat it enablesWhen 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: trueIngressReady: False (GatewayAPIUnavailable); hostnames are not routed
Istio (ambient mode recommended)An AuthorizationPolicy on the internal listener; mTLS for the peer networkMeshPolicyReady: False (IstioUnavailable); NetworkPolicy alone guards :8081
KEDA v2.12.0+ + Prometheus scraping the operatorCustom-metrics autoscaling. Needed only by WorkerApps with spec.autoscaling.enabled; the operator waits for KEDA's Paused=True acknowledgement before every rolloutAutoscalingReady: False (KEDAUnavailable); spec.autoscaling has no effect
An ingress controller (ingress-nginx, Traefik, a cloud controller)ingressMode: ingressIngressReady stays Unknown: the Ingress exists and nothing serves it
cert-managerclusterIssuer: per-app TLS on emitted IngressesThe 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:

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.

Edit this page on GitHubUpdated 2026-10-18