Kubernetes Network and Cluster Inventory Documentation

Kubernetes clusters are the most dynamic layer of most networks, and they are also the layer teams document least. Nodes appear and disappear with autoscaling, deployments roll out several times a week, every pod receives an IP address that lives for hours, and services are created and deleted faster than anyone updates a spreadsheet. Ask most platform teams what their cluster inventory looks like and they will open a terminal and run kubectl, which is not a record of the cluster, it is a live view of it. The moment something breaks, that view dies with the very cluster you need to understand.

This guide is about the maintained record that sits outside the cluster, and Obelinf is built to hold it: which nodes exist, which workloads run, which network ranges the cluster draws from, and which load balancer IPs and DNS names it exposes to the rest of your infrastructure. The sections below cover what to record for every cluster, why live kubectl output is not documentation, and where Kubernetes networking meets your broader IPAM and VLAN records.

At a Glance: How Teams Keep Cluster Records

What Cluster Inventory Documentation Covers

The record splits into three tiers with very different lifecycles. The cluster record itself holds the name, the version line, the distribution, and where the control plane runs, whether that is managed or self run. The node records hold everything a server inventory should: hostname, role, control plane or worker, Kubernetes version, container runtime, operating system, internal IP, labels, taints, and allocatable CPU and memory. The workload records hold the objects you actually manage, deployments, stateful sets, daemon sets, with their replica counts and images, rather than individual pods, which are replaced on a scale of minutes.

Services and ingress deserve their own attention because they are the seam between the cluster and the network. For every service, record the name, namespace, type, allocated ClusterIP, the port mapping, the node port when there is one, and the selector that ties it to its pods. For ingress, record the hostname, the paths, the backend service, and the TLS certificate. This is the layer that answers the question “what does this cluster expose”, and it is the layer most teams can only answer by typing kubectl get svc and reading from memory.

The Network Layer Deserves Its Own Record

Every cluster draws addresses from three internal ranges plus whatever external IPs its services consume. The pod CIDR is where the container network allocates pod addresses, typically a /24 per node from a larger pool chosen by your CNI plugin. The service CIDR is where ClusterIP addresses come from, with a default of 10.96.0.0/12. The node IPs are the real addresses your routers see, allocated from the same IP space as every other server. On top of those sit the externally visible addresses: load balancer IPs from a provider pool or a MetalLB range, node ports from the 30000 to 32767 window, and the DNS names that point at them.

These ranges are exactly the kind of information that belongs in your IP address management records, because other systems depend on them. Firewall rules reference node CIDRs and node ports. VPN tunnels route to cluster services through node IPs. A second cluster or a legacy application must avoid overlapping ranges. And when a team migrates a CNI plugin or reconfigures the service CIDR, every one of those dependencies changes at once. Teams that keep the ranges only in cluster configuration discover the problem when a firewall rule silently stops matching.

Why Live Cluster State Is Not Documentation

kubectl get nodes shows you the cluster as it is right now, which is genuinely useful and genuinely insufficient. A live query has no history: it cannot tell you what the cluster looked like before the autoscaler removed four nodes, what changed in last month’s upgrade, or which load balancer IPs were released when a service was deleted. Capacity planning, audits, and post incident reviews all need the before, and live state only has the now.

There is a second, more uncomfortable failure mode. When a cluster is unhealthy, the API server is often the first component to go unreachable, which means the tool you used to answer “what is running here” is exactly the tool that dies with the cluster. The documentation that matters in an incident is the record that exists independently of the system it describes. That is why a maintained inventory lives outside the cluster, in the same place your IPAM records live, so the on call engineer has the node list, the CIDRs, and the service map even when every control plane is dark.

What to Record for Every Cluster

The node table is the foundation. For each node, record the hostname, the role, the Kubernetes version, the container runtime, the operating system image, the internal IP, the labels and taints, and the allocatable CPU and memory. If nodes are physical, link the record to the server record with its rack position and serial number; if they are virtual machines, link to the hypervisor record. The version fields are the ones teams regret skipping, because upgrade planning without a per node version history is guesswork.

The service table records name, namespace, type, ClusterIP, ports, node port, load balancer IP, and selector for every service in every namespace. The workload table records deployments, stateful sets, and daemon sets with replica counts and images. The network table records the pod CIDR, the service CIDR, the node subnets, the node port range, and every load balancer IP, each tied to the cluster that owns it. The policy table records network policies by name and scope, and whether each namespace defaults to deny. Five tables, one per cluster, and most of them can be generated once and then kept honest by a regular sync.

Where the Cluster Meets the Rest of Your Network

The split in the diagram above is the most useful mental model for cluster networking: a small set of addresses is visible to the network, and everything else is internal. Node IPs come from your real IP space and often share VLANs with other servers. Load balancer IPs and ingress DNS names are external resources that need records, reservations, and lifecycle management. Node ports are an open path through your firewall on a well known range. These are the addresses your IPAM, firewall rules, monitoring, and topology all need to know about.

Everything else, pod IPs, ClusterIPs, and service DNS, lives inside the cluster and needs no IPAM record at all, which is why vlan and subnet management and network topology stop at the node boundary. But that boundary is exactly where teams get into trouble: a cluster’s pod CIDR can silently overlap a VPN range, two clusters can reuse the same service CIDR while their external footprints collide, and a load balancer IP can be handed back to a pool while a firewall rule still references it. The way to catch these problems is one record that shows the cluster’s external footprint alongside everything else, which is what makes the cluster documentation problem really a network documentation problem.

Keeping Cluster Records Current

A cluster inventory decays fast, so the process matters more than the format. Start with a baseline: generate the node, service, and workload tables from the live cluster, then move the stable parts into the source of truth. After that, run a reconciliation on a cadence, weekly for the node table and at every release for the service and ingress records, and update the IPAM records whenever the load balancer footprint changes. Treat the inventory as part of the change process rather than a separate chore, which is the difference between a record that helps and a record that quietly lies.

Version upgrades deserve explicit entries, including the before and after versions and any range or policy changes made during the upgrade. The changelog is what turns the inventory from a snapshot into evidence for audits and incident reviews. When you run several clusters across regions or providers, the same discipline scales: one record per cluster, all of them visible in the same system, with multi site networks to keep the relationships straight.

An Inventory Home Beyond kubectl

Obelinf gives cluster records a home outside the cluster. Device inventory holds every node with its role, version, IP, and rack position, linked to the rest of your hardware records. The IPAM tracks node IPs, pod and service CIDRs as documented reservations, and every load balancer and ingress IP as a real address record with an owner. VLAN and subnet management keeps the segments the cluster rides on, topology shows what each cluster connects to, and the changelog preserves every change for audits and post incident reviews. The record your platform team keeps in kubectl and the record your network team keeps in Obelinf stop being two versions of the truth. Sign up at obelinf.com and give your clusters an inventory that survives them.