Cilium operator

Active contributors: aanm, christarazi, sayboras, giorio94, joamaki

Purpose

The Cilium operator (cilium-operator) is a leader-elected Deployment that runs once per cluster (often as multiple replicas with active/standby leader election). It owns cluster-wide responsibilities the per-node agent cannot do efficiently from each node: pod CIDR allocation, identity garbage collection, CiliumEndpointSlice batching, and CRD schema upgrades.

There are cloud-flavoured builds:

• cilium-operator-generic — vanilla / on-prem Kubernetes.
• cilium-operator-aws — adds AWS ENI IPAM (pkg/aws/).
• cilium-operator-azure — adds Azure IPAM (pkg/azure/).
• cilium-operator-alibabacloud — adds Alibaba ENI IPAM (pkg/alibabacloud/).

The same operator/main.go produces all variants via build tags and Hive cells included only on certain platforms.

Directory layout

operator/
├── main.go                # ~10 lines: build a Hive and run it
├── cmd/                   # cobra root + cells.go for the operator
├── pkg/                   # operator-specific helpers
├── identitygc/            # identity garbage collection cell
├── endpointgc/            # CiliumEndpoint GC cell
├── endpointslicegc/       # CES GC cell
├── policyderivative/      # CCNP -> NetworkPolicy translation cell
├── unmanagedpods/         # pods not managed by Cilium reporter
├── doublewrite/           # double-write CES migration helper
├── auth/                  # mutual auth identity helpers
├── api/                   # REST API for the operator
├── k8s/                   # k8s startup helpers
├── metrics/               # operator-specific metrics
├── option/                # operator config struct
└── watchers/              # k8s watchers consumed by operator cells

Key abstractions

Type	File	Role
cmd.Operator	operator/cmd/cells.go	The cell graph for the operator.
IdentityGC	operator/identitygc/	Periodically scans Cilium identities and deletes ones with no live endpoints.
EndpointGC	operator/endpointgc/	Removes stale CiliumEndpoint and CiliumEndpointSlice resources.
CESController	operator/pkg/ciliumendpointslice/	Batches CiliumEndpoint updates into CiliumEndpointSlice resources to scale large clusters.
IPAM allocator	pkg/ipam/, pkg/aws/eni/, pkg/azure/ipam/, pkg/alibabacloud/ipam/	Allocates pod CIDRs / ENIs at the cluster level.
policyderivative	operator/policyderivative/	Derives Kubernetes NetworkPolicy from CiliumNetworkPolicy for backwards compatibility.

How it works

The operator participates in three responsibilities:

1. IPAM at scale. For cloud-IPAM modes, the operator handles ENI/IP allocation calls so that nodes don't need cloud credentials. The agent then claims an IP from the allocations the operator publishes via CiliumNode CRDs.
2. CRD lifecycle. The operator installs and upgrades CRD schemas in pkg/k8s/apis/cilium.io/client/crds/ on startup.
3. Garbage collection. Identities, CiliumEndpoints, CES, derived NetworkPolicies, and unmanaged-pod warnings are reconciled centrally rather than from each node.

graph LR
    APIServer[kube-apiserver]
    Operator[cilium-operator<br/>leader]
    Agent[cilium-agent on each node]

    APIServer -->|watch nodes| Operator
    APIServer -->|watch identities, endpoints| Operator
    Operator -->|allocate pod CIDR| APIServer
    Operator -->|GC identities| APIServer
    Operator -->|create CES| APIServer
    Agent -->|watch CES| APIServer
    Agent -->|claim IP| APIServer

Integration points

• CRDs: the operator is the canonical owner of CiliumIdentity, CiliumEndpoint, and CiliumEndpointSlice lifecycles.
• Cloud SDKs: AWS / Azure / Alibaba SDKs are imported only by the corresponding build of the operator.
• Helm: values under install/kubernetes/cilium/values.yaml configure the operator (replica count, leader election, IPAM mode).
• Mutual auth: operator/auth/ helps coordinate the SPIFFE identity issuer used by the agent's auth feature.

Entry points for modification

• New cluster-wide controllers go under operator/<name>/ as a Hive cell.
• New IPAM modes fit under pkg/ipam/<mode>/ with operator-side allocators in matching subdirectories.
• New CRDs go through pkg/k8s/apis/cilium.io/v2/ and are wired into operator GC if their lifecycle is shared.

Key source files

File	Purpose
operator/main.go	Entry point.
operator/cmd/cells.go	Operator cell graph.
operator/pkg/ciliumendpointslice/	CES controller.
operator/identitygc/	Identity garbage collector.
operator/endpointgc/	Endpoint garbage collector.
operator/policyderivative/	CCNP-to-NetworkPolicy translator.

See packages/k8s.md for the CRD types and watcher framework, and features/cluster-mesh.md for the operator's role in multi-cluster.