pkg/ipam

Active contributors: aanm, gandro, christarazi, joestringer, MrFreezeex

Purpose

pkg/ipam/ is the pod-IP allocation library. It abstracts over many backends — Kubernetes pod CIDR, Cilium-managed cluster pools, AWS / Azure / Alibaba ENIs, multi-pool, CRD — and presents a uniform interface to the rest of the agent.

For the user-visible feature description see features/networking-and-routing.md. This page documents the implementation.

Layout

pkg/ipam/
├── allocator.go            # the IPAM Allocator interface
├── manager.go              # multi-IP-family allocator manager
├── cells.go                # Hive wiring
├── crd.go                  # crd-based allocator
├── clusterpool/            # cluster-pool mode
├── multipool/              # multi-pool mode
├── pool/                   # pool-level allocator helpers
├── service/                # node-level service IP allocator
├── allocator/              # generic prefix-based allocator
├── nodeipam/               # node IP allocator (host IP and tunnel IPs)
├── stats/                  # IPAM stats
├── types/                  # shared types
├── option/                 # config struct
├── metrics/                # prom metrics
├── nullipam/               # null implementation for tests / CNI-only
├── staticip/               # static IP assignment helper
└── doc.go

pkg/aws/eni/                # AWS ENI allocator
pkg/azure/ipam/             # Azure IPAM allocator
pkg/alibabacloud/ipam/      # Alibaba ENI allocator
operator/pkg/ipam/          # operator-side cloud IPAM

Allocator interface

type Allocator interface {
    Allocate(owner string) (*AllocationResult, error)
    Release(ip net.IP) error
    Dump() (map[string]string, string)
    RestoreFinished()
}

The agent owns one allocator per IP family per pool. manager.go multiplexes them. The CNI plugin requests an allocation; the allocator returns a free IP plus gateway/MTU metadata.

Cluster pool

In clusterpool mode the operator allocates a per-node CIDR slice from a cluster-wide pool and writes it into CiliumNode.spec.ipam. The agent then runs an in-memory allocator over its slice.

graph LR
    User[Operator]
    Op[cilium-operator]
    CN[CiliumNode CRD]
    Agent[agent]
    Pod[New pod]

    User --> Op
    Op -->|allocate /24 etc.| CN
    CN --> Agent
    Pod --> Agent
    Agent --> Pod

Multi-pool

multipool lets different namespaces draw IPs from different pools. Pools are defined by CiliumPodIPPool CRDs and selected by namespace annotations. Useful for compliance and routing-domain segmentation.

Cloud modes

For AWS / Azure / Alibaba the operator handles the cloud API calls (allocate ENI, attach IP) so each node does not need cloud credentials. The agent receives allocations via CiliumNode.spec.ipam and consumes them locally.

Restore semantics

After an agent restart, IPAM consults disk-restored endpoints (pkg/endpoint/restore.go) to re-mark IPs as in-use before serving any new allocation. Otherwise the allocator might hand out an IP that an existing pod still holds.

Integration points

• CNI plugin triggers Allocate/Release via the agent REST API.
• CiliumNode CRD is the boundary between operator-side allocation and per-node allocation.
• Datapath uses the allocated IP to set up the veth and routing table.
• Metrics under pkg/ipam/metrics/ expose pool utilisation, allocation latency, and ENI counts.

Entry points for modification

• New IPAM backend: implement Allocator, register a Hive cell that constructs it, wire it from pkg/ipam/cells.go.
• New pool semantic: extend pkg/ipam/multipool/.
• Cloud-side changes: under the appropriate pkg/<cloud>/ and operator/pkg/<cloud>/ if applicable.

Key source files

File	Purpose
pkg/ipam/allocator.go	Allocator interface.
pkg/ipam/manager.go	Multi-allocator coordinator.
pkg/ipam/clusterpool/	Cluster-pool mode.
pkg/ipam/multipool/	Multi-pool mode.
pkg/aws/eni/eni.go	AWS ENI.
pkg/azure/ipam/azure.go	Azure IPAM.
pkg/alibabacloud/ipam/alibaba_cloud.go	Alibaba ENI.
pkg/k8s/apis/cilium.io/v2/types_node.go	CiliumNode (where allocations land).
pkg/k8s/apis/cilium.io/v2alpha1/types_pod_ip_pool.go	CiliumPodIPPool CRD.