Skip to content

8.10 IPAM in Weave CNI

Abstract

IPAM (IP Address Management) is responsible for assigning IP addresses to Pods and managing Pod subnets in Kubernetes networking.

In Kubernetes, the CNI plugin is responsible for Pod IP assignment. With Weave or other CNI plugins, IPAM ensures Pods receive unique IPs and that node-level Pod networks do not overlap.

In production, IPAM must be planned carefully to avoid duplicate IPs, CIDR overlap, routing issues, and cluster-wide networking failures.

What is IPAM?

IPAM stands for IP Address Management.

In Kubernetes, IPAM answers:

  • Which subnet does each node use for Pods?
  • Which IP address does each Pod receive?
  • Who prevents duplicate Pod IPs?
  • Where is Pod IP allocation information stored?
  • How are Pod IP routes configured?

Note

This topic is about Pod IP management, not node IP management. Node IPs are usually managed by cloud networking, DHCP, static configuration, or external enterprise IPAM systems.

Who Handles Pod IP Assignment?

Kubernetes itself does not directly assign Pod IPs.

The responsibility belongs to the CNI plugin.

Kubernetes
   ↓
Container Runtime
   ↓
CNI Plugin
   ↓
IPAM Plugin
   ↓
Pod IP Assigned

Success

CNI defines the standard, but the selected CNI plugin or IPAM plugin performs the actual IP allocation.

IPAM in CNI

CNI configuration has an ipam section.

Example:

{
  "cniVersion": "0.2.0",
  "name": "mynet",
  "type": "bridge",
  "bridge": "cni0",
  "isGateway": true,
  "ipMasq": true,
  "ipam": {
    "type": "host-local",
    "subnet": "10.244.0.0/16",
    "routes": [
      {
        "dst": "0.0.0.0/0"
      }
    ]
  }
}

Tip

The ipam section tells CNI how Pod IP addresses should be allocated.

CNI IPAM Fields

Field Purpose
type IPAM plugin type
subnet IP range used for Pod addresses
routes Routes configured inside the Pod namespace

Common IPAM plugin types:

IPAM Plugin Description
host-local Allocates IPs locally on each node
dhcp Uses an external DHCP server
CNI-specific IPAM Managed by the chosen CNI provider

host-local IPAM

The host-local IPAM plugin manages IP addresses locally on each node.

Example:

"ipam": {
  "type": "host-local",
  "subnet": "10.244.0.0/16"
}

What it does:

  • tracks allocated Pod IPs locally
  • prevents duplicate IPs on the same node
  • assigns IPs from the configured subnet
  • releases IPs when Pods are deleted

Note

host-local is simple and useful for learning, but production behavior depends on the full CNI solution and cluster design.

DHCP IPAM

The dhcp IPAM plugin gets Pod IPs from a DHCP server.

Example:

"ipam": {
  "type": "dhcp"
}

Use case:

  • centralized IP assignment
  • integration with existing network infrastructure
  • external IP lease management

Warning

DHCP-based Pod IPAM requires reliable DHCP availability. If DHCP fails, new Pods may not receive IP addresses.

Weave IPAM Concept

With Weave Net, IP allocation is handled by the Weave networking layer.

Weave peers run across all nodes and coordinate Pod network information.

Each node gets a Pod subnet, and Pods receive IPs from that node's Pod range.

Example layout:

Node Node IP Pod CIDR Gateway
Node 1 192.168.1.11 10.244.1.0/24 10.244.1.1
Node 2 192.168.1.12 10.244.2.0/24 10.244.2.1
Node 3 192.168.1.13 10.244.3.0/24 10.244.3.1

Example

A Pod on Node 1 may receive 10.244.1.2, while a Pod on Node 2 may receive 10.244.2.2.

Pod IP Example

Example Pod IPs:

Node 1:
  Pod 1: 10.244.1.2
  Pod 2: 10.244.1.3

Node 2:
  Pod 1: 10.244.2.2

Node 3:
  Pod 1: 10.244.3.2

Traffic between Pods is handled by the CNI plugin and node networking.

Note

Pod IPs must be unique across the entire Kubernetes cluster.

How IPAM Prevents Duplicate IPs

IPAM must track used addresses.

For simple local IPAM, this can be done using local state files.

For more advanced CNI plugins, the plugin may coordinate allocation across nodes.

The main goal is:

No two active Pods should receive the same IP address.

Danger

Duplicate Pod IPs can cause unpredictable routing, service failures, DNS issues, and application outages.

CNI Plugin and IPAM Plugin Relationship

A CNI plugin can delegate IP allocation to an IPAM plugin.

Example:

Bridge CNI Plugin
      ↓
Reads ipam.type
      ↓
Calls host-local IPAM
      ↓
Receives Pod IP
      ↓
Configures Pod interface

Tip

The CNI plugin handles the network interface setup, while the IPAM plugin handles address allocation.

Routes in IPAM

Example route configuration:

"routes": [
  {
    "dst": "0.0.0.0/0"
  }
]

This means:

Add a default route inside the Pod network namespace.

The Pod can then send traffic through its gateway.

Note

Routes are required so Pods know how to reach other networks.

Weave and Pod Routing

Inside a Pod, you can check routes:

kubectl exec <pod-name> -- ip route

Example:

default via 10.244.1.1 dev eth0

Meaning:

Send traffic through the Weave bridge gateway on this node.

Success

Correct Pod routes are required for traffic to reach other Pods and Services.

Production IPAM Planning

Before deploying Kubernetes networking, plan:

  • Pod CIDR range
  • Service CIDR range
  • Node CIDR range
  • cloud VPC/subnet CIDRs
  • VPN/on-prem network CIDRs
  • future cluster expansion

Warning

Pod CIDR, Service CIDR, node CIDR, VPN CIDR, and corporate network ranges must not overlap.

CIDR Planning Example

Good separation:

Network Example CIDR
Node network 192.168.1.0/24
Pod network 10.244.0.0/16
Service network 10.96.0.0/12

Tip

Choose CIDR ranges large enough for future node and Pod growth.

Production Best Practices

Recommended

  • Plan Pod CIDR before cluster creation
  • Avoid overlapping CIDRs
  • Use a reliable CNI plugin with stable IPAM
  • Monitor IP exhaustion
  • Validate Pod IP uniqueness
  • Confirm routes after CNI deployment
  • Document Pod CIDR and Service CIDR
  • Test cross-node Pod communication

Do's

  • Check Pod IPs using kubectl get pods -A -o wide
  • Verify Pod routes using ip route
  • Confirm every node has the expected Pod CIDR
  • Use maintained CNI plugins
  • Monitor IP allocation and exhaustion
  • Keep CNI and Kubernetes versions compatible

Don'ts

  • Don't use overlapping Pod and Service CIDRs
  • Don't manually assign Pod IPs in normal Kubernetes workloads
  • Don't mix IPAM mechanisms without understanding the design
  • Don't ignore duplicate IP symptoms
  • Don't change Pod CIDR casually after cluster creation
  • Don't deploy production clusters without IP range planning

Danger

Poor IPAM planning can require cluster rebuilds, especially when Pod CIDRs conflict with existing networks.

Troubleshooting IPAM

When Pod IP assignment fails, check:

  • Does the Pod have an IP?
  • Is the CNI plugin running?
  • Is the IPAM config valid?
  • Is the Pod CIDR exhausted?
  • Are CIDRs overlapping?
  • Are CNI config files present?
  • Are CNI binaries present?
  • Are node routes correct?
  • Are CNI logs showing allocation errors?

Useful Commands

Check Pods and IPs:

kubectl get pods -A -o wide

Check node Pod CIDRs:

kubectl get nodes -o wide

Check CNI configuration:

ls /etc/cni/net.d
cat /etc/cni/net.d/<config-file>

Check CNI binaries:

ls /opt/cni/bin

Check Pod route:

kubectl exec <pod-name> -- ip route

Check node routes:

ip route

Check interfaces:

ip addr
ip link

Weave Validation Commands

Check Weave Pods:

kubectl get pods -n kube-system -o wide

Check Weave logs:

kubectl logs <weave-pod-name> -n kube-system -c weave

Check cross-node Pod communication:

kubectl exec <pod-on-node1> -- ping <pod-ip-on-node3>

Tip

For Weave, always validate that Weave peers are running and that Pods across nodes can communicate.

Summary

Quote

  • IPAM manages Pod IP address allocation
  • Kubernetes delegates Pod IP assignment to CNI
  • CNI config uses the ipam section to define IPAM behavior
  • host-local manages IPs locally on a node
  • dhcp can use an external DHCP server
  • Weave coordinates Pod networking across nodes
  • Production clusters require careful CIDR planning and IPAM monitoring