IPAM — how the CNI assigns Pod IPs deterministically

IPAM is the IP Address Management plugin the CNI invokes to allocate and reclaim Pod IPs. The CNI specification does not define an IPAM model; it delegates the decision to a separate plugin category. The choice of IPAM determines where the IP space is owned, how the IP is reclaimed, and how the cluster handles exhaustion. This lesson walks the IPAM contract, the standard strategies, and the operational discipline of sizing the pool.

What IPAM does

The IPAM plugin answers one question: what IP does this Pod get? The plugin receives the same JSON envelope as the CNI plugin, with the ipam.type field selected:

{
  "ipam": {
    "type": "calico-ipam",
    "assign_ipv4": "true",
    "ipv4_pools": ["10.244.0.0/16"]
  }
}

The IPAM plugin returns the IP, the gateway, and the routes. The CNI plugin (Calico, Cilium, Flannel) takes that IP and configures the network namespace.

sequenceDiagram
    autonumber
    participant K as kubelet
    participant CNI as CNI plugin
    participant I as IPAM plugin
    participant S as IPAM store
    K->>CNI: ADD
    CNI->>I: request IP
    I->>S: reserve IP
    S-->>I: IP
    I-->>CNI: IP, gateway, routes
    CNI->>CNI: configure veth, namespace
    CNI-->>K: result

The separation between CNI and IPAM is deliberate. The CNI knows about network namespaces and veth pairs; the IPAM knows about the IP pool and the rules for allocation. A single IPAM can serve any CNI; a single CNI can use any IPAM.

Host-local IPAM

The simplest IPAM is host-local, which is the default shipped with the CNI plugins tarball. Each node is assigned a CIDR (e.g., 10.244.1.0/24) and the IPAM assigns IPs from that CIDR. There is no centralised state.

{
  "ipam": {
    "type": "host-local",
    "ranges": [
      [{ "subnet": "10.244.1.0/24" }]
    ]
  }
}

The size of the CIDR is the maximum number of Pods a node can host. A /24 gives 254 addresses per node. A busy production node routinely needs /23 or /22.

Calico IPAM

Calico supports several IPAM modes. The default is Calico IPAM, which is a custom store that allocates IPs from a cluster-wide pool. The store is held in Felix’s datastore (typically etcd for self-hosted, Kubernetes API for in-cluster). The cluster operator defines IP pools:

apiVersion: projectcalico.org/v3
kind: IPPool
metadata:
  name: default-pool
spec:
  cidr: 10.244.0.0/16
  ipipMode: Never
  vxlanMode: Never
  natOutgoing: true
  blockSize: 26

The blockSize is the unit of allocation: each node gets a /26 block (64 IPs) carved from the cluster pool. The block is released when the node leaves the cluster, reclaimed when the IPAM is garbage-collected.

The advantage over host-local is that the cluster controls the IP space; the operator can read the allocation from the API. The disadvantage is that the IPAM relies on a datastore and adds a read-modify-write on every Pod creation.

Cilium IPAM

Cilium uses a routed IPAM model. Each node is assigned a CIDR; the IPs are routed natively inside the cluster (no overlay, no IPIP, no VXLAN). The IPAM is integrated with Cilium’s agent and uses the Kubernetes API as the datastore. The CIDR is configurable via Cilium’s ipv4PodCIDRList and a per-node mask.

CiliumClusterwideIPPool is the operator’s API for allocating IPs across nodes. Production-grade deployments use a single cluster-wide pool with a block size that matches the node’s maximum Pod count.

Other IPAM strategies

The CNI supports other IPAM strategies:

• DHCP: the IPAM delegates to a DHCP server. Used in legacy networks where the cluster runs alongside an existing DHCP infrastructure.
• Whereabouts: a CNI plugin that provides a cluster-wide IPAM without a datastore. Uses annotations to track allocations.
• Kube-Router: experimental IPAM that integrates with Kube-Router.

The production rule is to use the IPAM that the distribution ships with: Calico IPAM for Calico, Cilium IPAM for Cilium, host-local for Flannel.

Sizing the IPAM pool

The IPAM pool must be sized for the cluster’s maximum Pod count. The formula:

required IPs = (max Pods per node) x (number of nodes)

A 200-node cluster with a maximum of 110 Pods per node (the Kubernetes default) needs 22,000 IPs. A /16 (65,536 IPs) gives 3x headroom; a /17 (32,768) gives 1.5x.

The audit must compare the pool size against the expected Pod count. An exhaustion event is a cluster affecting outage: every node’s IPAM is full; new Pods stay pending.

flowchart LR
    A[Cluster CIDR 10.244.0.0/16] --> B[Per-node block /26]
    B --> C[Node 1: 64 IPs]
    B --> D[Node 2: 64 IPs]
    B --> E[Node 3: 64 IPs]
    C --> F[Pod 1: 10.244.0.5]
    C --> G[Pod 2: 10.244.0.6]

The failure modes

The IPAM failure modes:

• Pool exhaustion: the cluster cannot allocate more IPs. Pods stay pending. The fix is to add a second pool or to delete unused Pods.
• Block leak: Calico’s blockSize-based allocation can leak blocks if the node dies before releasing them. The fix is to run the IPAM garbage collector.
• CIDR overlap: two nodes hand out the same IP. The fix is to reconfigure the per-node CIDR and to restart the affected Pods.
• IPAM store outage: the IPAM cannot read or write to its datastore. Pods stay pending. The fix is to restore the datastore.

The operational discipline

The IPAM’s operational discipline:

• Size the pool for the cluster’s maximum Pod count. Use the formula above.
• Audit the pool’s utilisation. A growing utilisation is the leading indicator of exhaustion.
• Run the IPAM garbage collector. Calico’s garbage collector reclaims blocks from dead nodes.
• Test the IPAM in staging. Pool exhaustion is a cluster-wide outage; staging catches the failure.
• Monitor the IPAM’s metrics. Cilium and Calico expose IPAM metrics; alert on utilisation.
• Document the IPAM choice. The IPAM is the cluster’s IP space; the documentation is the reference.

Quiz

Production discipline

• IPAM is a separate plugin. The CNI handles veth pair creation; the IPAM handles IP allocation.
• Host-local IPAM is per-node. It is simple but requires manual CIDR coordination across nodes.
• Calico IPAM is cluster-wide. It uses a datastore and supports block-based allocation.
• Cilium IPAM is routed. It uses a cluster-wide pool with no overlay.
• Size the pool for the maximum Pod count. The formula is (max Pods per node) x (number of nodes).
• Audit the pool’s utilisation. A growing utilisation is the leading indicator of exhaustion.
• Run the IPAM garbage collector. Blocks leaked from dead nodes must be reclaimed.
• Test the IPAM in staging. Pool exhaustion is a cluster-wide outage.
• Document the IPAM choice. The IPAM is the cluster’s IP space; the documentation is the reference.