Kubernetes Integration

Overview

The Kubernetes integration discovers a cluster's topology and address usage and ingests it into NetBox via the Diode SDK. It connects to the cluster's API server with a service account token, reads the cluster's nodes, namespaces, services, and service CIDRs, and maps them to NetBox objects. Discovered data is staged as deviations in NetBox Assurance, where you review and apply changes before they are written to NetBox.

After a sync you can see which machines belong to which cluster, what address space each cluster has committed to pods and services, and which of your addresses front a Kubernetes service. Run the integration on a schedule to surface changes, such as new nodes, a node going offline, or new LoadBalancer addresses, as deviations in Assurance.

What Gets Synchronized

• Cluster - the cluster, as a NetBox cluster with the Kubernetes cluster type and cluster group
• Nodes - each node, as either a device or a virtual machine. You choose which with the NODE_OBJECT_TYPE setting
• Node roles - a role for each node, from its node-role.kubernetes.io/<role> label. Nodes with no role label get the Kubernetes Node role
• Node status - active or offline, from the node's Ready condition
• Node interfaces - one interface per node, named kubernetes, holding the node's addresses
• Node IP addresses - each node's InternalIP and ExternalIP addresses, assigned to the node's interface
• Pod and service blocks - each node's pod CIDR and the cluster's service CIDRs, as prefixes in a VRF created for the cluster
• LoadBalancer service addresses - the external IP address of each LoadBalancer service, with the service's namespace and name in custom fields

Key Features

• Nodes as devices or virtual machines - record bare-metal nodes as devices, or VM nodes as virtual machines so they sit alongside a hypervisor's inventory
• Rename-safe identity - the cluster is keyed on the kube-system namespace UID, and each node on its system UUID where the node reports a unique one. Changing CLUSTER_NAME or renaming a node therefore updates the existing NetBox record instead of creating a new one
• Node-to-host join keys - each node records its system UUID and provider ID in custom fields, for matching nodes to the hypervisor or cloud instance they run on
• Per-cluster VRF - pod and service blocks are placed in a VRF for each cluster, so clusters that use the same default ranges stay separate in NetBox
• Dual-stack support - IPv4 and IPv6 node addresses and pod CIDRs are both recorded
• Label-based node scope - restrict a sync to nodes matching a Kubernetes label selector, using the same syntax as kubectl get nodes -l
• Least-privilege access - needs only get and list on nodes, namespaces, services, and service CIDRs. It cannot read pods or secrets
• Proxy support - honors the HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables
• Bootstrap mode - creates custom fields, the cluster type and group, and (for devices) the manufacturer and device type in NetBox before the first full sync
• Operational drift detection - run on a schedule to surface cluster changes as deviations in NetBox Assurance

Integration Architecture

The Kubernetes integration is built on the NetBox Labs controller integrations framework:

• Standardized integration pattern - consistent approach across all controller integrations
• NetBox Assurance integration - uses NetBox Assurance for safe data ingestion and deviation management
• Agent based - runs as part of the NetBox Discovery agent ecosystem using the Orb Agent Pro image
• One-way sync - data flows from Kubernetes to NetBox only; nothing is written back to the cluster

Compatibility

Supported NetBox Versions

• NetBox Cloud and NetBox Enterprise with NetBox Assurance

Supported Kubernetes Distributions

• Upstream (vanilla) Kubernetes. OpenShift and other distributions are not supported in this release
• No minimum Kubernetes version is required
• Service blocks are read from the ServiceCIDR resource (networking.k8s.io/v1), which is available from Kubernetes 1.33. On a cluster that does not serve this resource, typically one older than 1.33, everything else is synced, but no service block is recorded

Before You Start

Two settings need to be decided before the first run, because they are hard to undo:

• NODE_OBJECT_TYPE decides whether nodes become devices or virtual machines. Changing it later leaves every record written under the previous type in NetBox, because the integration never deletes objects.
• SITE_NAME decides which site node devices are placed in. NetBox identifies a device by its name and site, so if this site already holds servers with the same names as your nodes, the integration updates those records instead of creating new ones.

See Choosing a node object type and site before you configure the agent.

Known Limitations

Nodes are not given a primary IP. LoadBalancer services that report a hostname rather than an IP address, as on Amazon EKS, are not recorded. The cluster-wide pod CIDR is not discoverable, so only each node's pod CIDR is recorded. See Known Limitations for the full list.