Deployment

Cilium ships as a set of container images and a Helm chart. This page describes how the artifacts in this repo turn into a running cluster.

Artifacts produced from this repo

Image	Source
quay.io/cilium/cilium	Agent. Built from images/cilium/Dockerfile. Contains cilium-agent, cilium-dbg, cilium-health, bugtool, the BPF objects from bpf/, and the embedded clang/LLVM toolchain.
quay.io/cilium/operator-{generic,aws,azure,alibabacloud}	Operator. Built from images/operator/Dockerfile.
quay.io/cilium/hubble-relay	Relay. Built from images/hubble-relay/Dockerfile.
quay.io/cilium/clustermesh-apiserver	Cluster Mesh apiserver. From images/clustermesh-apiserver/Dockerfile.
quay.io/cilium/cilium-envoy	Distroless Envoy distribution. From images/cilium-envoy/.
quay.io/cilium/cilium-cli	The user-facing CLI image.
quay.io/cilium/standalone-dns-proxy	Optional standalone DNS proxy.

Makefile.docker orchestrates multi-arch builds for AMD64 and AArch64.

Helm chart

The chart lives at install/kubernetes/cilium/. It is the canonical install path:

• One DaemonSet for the agent.
• One Deployment for the operator (often two replicas, leader-elected).
• One Deployment for hubble-relay when Hubble is enabled.
• One Deployment for clustermesh-apiserver when Cluster Mesh is enabled.
• A handful of Services, ConfigMaps, RBAC, and CRDs.

Helm values are documented in Documentation/helm-values.rst (auto-generated, ~213 KB). CI keeps the rendered docs in sync via Documentation/check-helmvalues.sh.

Running install paths

1. cilium install — embeds the chart in the CLI binary; auto-detects the cluster (cloud, kubeproxy presence, kernel) and picks defaults. Best for getting started.
2. helm install directly — for production. Pin chart version, override values via values.yaml files.
3. cilium upgrade — drives a chart upgrade with the embedded version-aware defaults.
4. GitOps — the chart is also fine to drive from Argo CD / Flux. Each version of the chart pins the matching image tags.

Pre-flight

Many environments require a pre-flight phase to load CRDs and check kernel features. The cilium preflight command (in cilium-cli/) and the chart's preflight.enabled=true mode do this.

Upgrade strategy

The agent supports rolling upgrades:

• BPF maps survive across agent restarts because they are pinned to bpffs.
• Endpoint state is persisted to disk under /var/run/cilium/state/<id>/.
• A new agent regenerates each endpoint without dropping running connections.

Cross-minor upgrades may include CRD migrations; the operator handles those at startup. The Documentation/operations/upgrade/ tree describes per-version steps.

Environment expectations

• Kernel: ≥ 4.19 in theory, but recent features expect 5.4+ and many features (Maglev, sock LB, BGPv2, WireGuard offload) require even newer kernels. Documentation/operations/system_requirements.rst is authoritative.
• CPU/memory: the agent is heavy compared to a stock CNI — expect a few hundred MB of RAM per node depending on identity count. The operator memory grows with cluster size; CES batching helps.
• Storage: bpffs must be mounted; CNI conf directory writable; agent state directory writable.
• Networking: node-to-node IP connectivity (typical Kubernetes prerequisite). Tunnel mode adds VXLAN/Geneve UDP; native mode requires the underlay to route pod CIDRs.

Image signatures and SBOM

Cilium publishes:

• Cosign signatures for every image (verify with cosign verify quay.io/cilium/cilium:vX.Y.Z).
• SBOM in SPDX format embedded in each image since v1.13.0 (Documentation/configuration/sbom.rst).
• FOSSA license attributions.

Release process

• Cut from a stable branch (v1.NN) by maintainers.
• contrib/release/ holds the release scripts.
• Release notes are aggregated from PR labels via contrib/release/relnotes/.
• Container images are pushed to quay.io/cilium/.
• The Helm chart is published to https://helm.cilium.io/.

Test / staging deployment

For development:

• make -C cilium-cli kind creates a kind cluster preconfigured for Cilium.
• make kind-image && make kind-install builds local images and installs them.
• cilium connectivity test validates a deployment.

CI runs the full matrix (kernel × Kubernetes version × routing mode × IPAM mode × encryption) on every PR.

Key source files

File	Purpose
install/kubernetes/cilium/values.yaml	Helm values.
images/cilium/Dockerfile	Agent image.
images/operator/Dockerfile	Operator image.
Makefile.docker	Multi-arch image builds.
Makefile.kind	kind dev loop.
Documentation/helm-values.rst	Generated Helm reference.
contrib/release/	Release scripts.