Kubernetes Cluster CIDR / Subnet Planner

Work out the per-node pod subnet size your cluster needs, whether your pod CIDR block is big enough for your node count, and exactly how many pod IPs you can address.

Every node in a Kubernetes cluster gets its own slice of the cluster’s pod CIDR, and every pod scheduled on that node draws its IP from that slice. The controller manager (or cloud provider’s IPAM) hands out one subnet per node, sized by --node-cidr-mask-size, and once a node’s slice is fully allocated no more pods can schedule there even if the node has plenty of CPU and memory left. Getting this sizing wrong is a genuinely common outage: a cluster that silently stops scheduling pods on otherwise healthy nodes almost always traces back to a pod CIDR that was too small for the node count, discovered only once real traffic showed up.

The sizing math is a straightforward capacity problem once you separate its two halves. First, how big does one node’s subnet need to be: it must hold at least as many addresses as the node’s max-pods setting, so the required subnet is the smallest power of two greater than or equal to that number — 110 max pods needs 128 addresses, which is a /25, not a /24, even though kubeadm’s actual default is the more generous /24. Second, how many of those per-node subnets fit inside the cluster CIDR: that is just the address-space ratio between the cluster block and the node block, e.g. a /16 cluster CIDR holds 256 /24 node subnets, or 512 /25 node subnets.

kubeadm’s own default of a /24 per node (256 addresses) with a 110 max-pods default is deliberately generous rather than the bare mathematical minimum — it leaves headroom for the loopback and any reserved addresses a particular CNI plugin sets aside, and it keeps the arithmetic simple. Cloud-managed clusters often expose this as a single dropdown (GKE’s \”maximum pods per node\”) that quietly picks the node subnet size for you using the same power-of-two logic this tool implements directly.

The failure mode to plan around is running out of node subnets, not running out of pod IPs within a node. A /16 pod CIDR with /24 nodes supports 256 nodes total — comfortably more than almost any cluster needs — but the same /16 with a smaller max-pods setting shrinking nodes to /25 or /26 supports 512 or 1,024 nodes, while a tighter cluster CIDR like /20 with /24 nodes tops out at just 16 nodes. Because the cluster CIDR is set once at cluster creation and resizing it later typically means rebuilding the cluster, it is worth sizing for growth up front rather than for the node count you have on day one.

One more gotcha worth knowing: subnetting math ultimately treats an IP address as a 32-bit number, and cluster CIDRs commonly start above 128.0.0.0 (the 172.16.0.0/12 private range, for instance) — large enough to come out negative under naive 32-bit signed-integer arithmetic in some languages and tools. It rarely bites Kubernetes itself, but it is a real source of bugs in home-grown IPAM scripts. This tool deliberately does all its address math with plain unsigned arithmetic to avoid that class of error.