Kubernetes Pod Addressing Management

Kubernetes Pod Addressing Management is the set of mechanisms responsible for allocating, tracking, and reclaiming IP addresses assigned to Pods, ensuring that every running Pod has a unique, routable identity within the cluster's Pod network. It is primarily implemented through IPAM (IP Address Management) components embedded in CNI plugins, working in coordination with per-Node CIDR allocation performed by the Kubernetes control plane.

Address Allocation Hierarchy

Cluster-Wide Pod CIDR

The cluster administrator defines a broad Pod CIDR range (e.g., 10.244.0.0/16) at cluster creation time, typically via the --cluster-cidr flag on the kube-controller-manager. This range represents the entire address space available for Pod IPs across all Nodes.

Per-Node CIDR Subdivision

The node-ipam-controller (part of kube-controller-manager) carves the cluster CIDR into smaller, non-overlapping blocks — commonly /24 subnets — and assigns one block to each Node's spec.podCIDR field. This guarantees that IP allocation on any given Node never collides with allocation on another Node.

kubectl get nodes -o custom-columns=NAME:.metadata.name,PODCIDR:.spec.podCIDR

Per-Pod IP Assignment

When a Pod is scheduled onto a Node, the CNI plugin's local IPAM module allocates a single free IP address from that Node's CIDR block and binds it to the Pod's network namespace for the Pod's lifetime.

IPAM Implementation Strategies

Host-Local IPAM

The host-local IPAM plugin, bundled with many CNI reference implementations, maintains a simple on-disk lease file per Node, tracking which addresses in the local CIDR block are currently in use. It is lightweight but has no cluster-wide visibility.

{
  "ipam": {
    "type": "host-local",
    "subnet": "10.244.1.0/24",
    "dataDir": "/var/lib/cni/networks"
  }
}

Cluster-Aware IPAM (Calico, Cilium)

More advanced CNI plugins implement centralized or distributed IPAM that tracks allocations cluster-wide via a shared datastore (etcd, Kubernetes CRDs, or a key-value store), enabling features like dynamic block resizing, IP address reservation, and cross-Node address pool borrowing when a Node exhausts its local block.

Cloud-Native IPAM

Cloud-managed CNIs (AWS VPC CNI, Azure CNI, GKE VPC-native) delegate IPAM to the underlying cloud network fabric, assigning Pods real, routable addresses from the VPC/VNet subnet rather than a separate overlay range. This simplifies integration with cloud load balancers and security groups but ties Pod capacity to available VPC subnet addresses.

Address Lifecycle Management

Allocation on Pod Creation

During the ADD operation of the CNI plugin invocation, the IPAM module selects an available address, marks it as allocated in its tracking store, and returns it to the plugin for interface configuration.

Reclamation on Pod Deletion

During the DEL operation, the IPAM module releases the address back into the available pool for that Node's block, making it eligible for reuse by a subsequently scheduled Pod.

Handling Abnormal Termination

If a Node crashes or the kubelet is forcibly restarted without a clean CNI DEL call, IP leases can become orphaned. Reconciliation loops in modern CNI plugins periodically cross-reference the container runtime's list of running Pods against the IPAM lease store to detect and free stale allocations.

Scaling and Capacity Constraints

Pod Density per Node

The size of a Node's CIDR block directly bounds the maximum number of Pods that can run on it. A /24 block, for example, yields at most 254 usable Pod addresses, independent of how much CPU or memory the Node actually has available.

# Example kubelet configuration limiting pods per node
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
maxPods: 110

Resizing Cluster Address Space

Expanding a cluster's total Pod capacity — whether by adding Nodes or increasing pods-per-node — requires ensuring the cluster CIDR is large enough to allocate additional per-Node blocks; undersized cluster CIDRs are a common cause of Nodes failing to receive a podCIDR assignment once capacity is exhausted.

Multi-Cluster and Hybrid Considerations

When multiple clusters must interconnect (via VPC peering, service mesh federation, or multi-cluster networking), Pod address ranges across clusters must not overlap, requiring careful upfront CIDR planning at the organizational level.

Operational Diagnostics

Verifying Node CIDR Assignment

A Node stuck without a podCIDR typically indicates the controller manager's --allocate-node-cidrs flag is disabled or the cluster CIDR is exhausted; Pods will fail to schedule with networking errors until this is resolved.

Inspecting In-Use Addresses

# host-local IPAM lease inspection
ls /var/lib/cni/networks/<network-name>/

Detecting Address Exhaustion

Symptoms of Pod address exhaustion include Pods stuck in ContainerCreating with CNI errors referencing "no IP addresses available," which typically requires either increasing the per-Node block size or reducing pod density through better bin-packing and scheduling constraints.