4.15 Kubernetes Node Status Reporting

Kubernetes Node Status Reporting is the process by which the kubelet gathers a comprehensive snapshot of its node's state and publishes it back to the API server as the node object's status subresource, covering everything from addressing and system information to capacity figures and condition data, and doing so through a communication pattern designed to minimize unnecessary API server load at cluster scale.

Contents of the Node Status Object

Addresses

The status includes a list of node addresses, typically an internal IP used for cluster-internal traffic and, where applicable, an external IP and a hostname, which are consumed by components such as the scheduler, kubelet-to-kubelet communication paths, and monitoring tooling that need to reach the node directly.

Node Info

A nested nodeInfo structure reports details such as the kernel version, operating system image, container runtime version, kubelet version, and kube-proxy version running on the node, information that is useful for compatibility checks and for operators auditing fleet-wide software versions.

Capacity, Allocatable, and Images

As previously established for resource accounting, the status also carries capacity and allocatable resource figures, along with a list of container images already cached on the node and their reported sizes, which the scheduler can use as a soft signal favoring nodes that already have a required image.

Conditions

The conditions array, covering Ready, MemoryPressure, DiskPressure, PIDPressure, and related types, is embedded directly within the status object, giving a single object that combines both raw descriptive data and evaluated health signals.

The Reporting Pipeline

Status Generation Inside the kubelet

The kubelet's node status update loop gathers data from multiple internal sources, cAdvisor for resource usage, the container runtime for version and image information, and its own condition evaluators, assembling them into a complete status object before submitting it to the API server.

Patch Versus Full Update

Rather than always submitting a complete replacement of the node object, the kubelet computes a patch representing only the fields that have changed since the last successful update, reducing the size of API requests and the load placed on the API server and etcd, particularly important in clusters with thousands of nodes reporting simultaneously.

Update Frequency Configuration

The frequency of full status updates is controlled by a configurable interval, balancing timeliness of health information against API server load; this interval is deliberately longer than the separate, lightweight heartbeat mechanism used purely to indicate the kubelet process is alive.

Decoupling Heartbeats from Full Status

The Node Lease Object

To avoid the cost of updating the entire node status object at high frequency just to signal liveness, Kubernetes introduced a separate Lease object, stored in the kube-node-lease namespace, that the kubelet renews at a fast, configurable interval, serving as the primary liveness signal consumed by the node controller.

Why the Split Matters at Scale

Before the lease mechanism existed, frequent liveness signaling required updating the full node object repeatedly, which scaled poorly as cluster size grew. Splitting cheap, frequent liveness renewal from expensive, infrequent full status updates significantly reduced control plane overhead in large clusters.

Node Controller Consumption of Leases

The node lifecycle controller primarily watches Lease renewal timestamps to detect node unresponsiveness, only falling back to inspecting the node's own condition timestamps when leases are unavailable or when deeper diagnostic detail about the reported reason for unhealthiness is needed.

Handling Reporting Failures

Retry and Backoff

If a status update to the API server fails, due to transient network issues or API server unavailability, the kubelet retries with backoff, continuing to serve pods locally in the meantime, since a failed status report does not by itself interrupt the kubelet's core responsibility of running already-admitted pods.

Stale Status Implications

If a node's status or lease goes unrenewed for longer than a configured grace period, the node controller marks the node as unreachable in its internal tracking, which can eventually lead to the node's conditions being marked Unknown and to pod eviction being triggered, even though the node's actual workloads may still be running correctly, since the control plane has simply lost visibility into the node's true state.

Consumers of Node Status

Scheduler Filtering

The scheduler reads node status, particularly capacity, allocatable resources, conditions, and taints derived from conditions, when filtering candidate nodes for new pods, making accurate and current status data essential for correct scheduling outcomes.

Cluster-Level Tooling

Autoscalers, dashboards, and command-line tools such as kubectl get nodes and kubectl describe node all render their output directly from the node status object, making it the primary interface through which operators and automated systems alike understand the state of the cluster's compute fleet.