Kubernetes Node API Relationship

Kubernetes Node API Relationship is the ongoing correspondence between a physical or virtual machine and its Node API object, covering not just their initial linkage at registration but how that linkage is maintained over the node's lifetime, what happens when the two fall out of sync, and the special, restricted way a node's own kubelet is permitted to interact with the API server on its own object's behalf.

The Synchronization Relationship

Kubelet as the Sole Writer of Its Own Node Status

A machine's kubelet is formally the only component that writes to its own Node object's status field under ordinary operation; other components, the scheduler, the controller manager, read Node status but do not modify it, keeping the relationship between machine and object one-directional for status purposes, machine to object, not object to machine.

Heartbeats as the Ongoing Proof of Correspondence

The kubelet formally maintains this correspondence through periodic heartbeats, either full status updates or lightweight Lease-object renewals, that serve as continuous proof to the rest of the cluster that the Node object still accurately represents a live, functioning machine.

kubectl -n kube-node-lease get lease worker-node-3

The Node Authorizer's Special Relationship

Scoping a kubelet's Permissions to Its Own Object

The built-in Node authorizer formally grants a kubelet's credentials permission to read and write only the specific Node object matching its own identity, along with Pods and related resources bound to that same node, an authorization relationship distinct from ordinary RBAC in that it is derived automatically from the kubelet's certificate identity rather than from an explicitly bound Role.

kubectl auth can-i update nodes/status --as system:node:worker-node-3

Divergence: Machine Present, Object Absent

A Machine Without a Corresponding Object

A running machine whose kubelet has not yet registered, or whose Node object was deleted while the kubelet continued running, formally has no representation in the cluster's API at all; the scheduler cannot place Pods on it, and it participates in no cluster-level accounting, despite being a physically functioning machine.

systemctl status kubelet
kubectl get node worker-node-3
# Error from server (NotFound): nodes "worker-node-3" not found

Automatic Recovery

If the kubelet on such a machine remains running with --register-node=true, it formally re-creates its Node object on its next registration attempt, restoring the correspondence without requiring the machine itself to be restarted.

Divergence: Object Present, Machine Absent

An Object Outliving Its Machine

A Node object formally persists in the API even after its corresponding machine is powered off, destroyed, or otherwise permanently gone, since etcd retains whatever was last written regardless of the machine's actual continued existence; the Node Controller's heartbeat monitoring is the mechanism that eventually detects and acts on this divergence.

Manual or Automated Cleanup

Because the Node Controller formally marks a heartbeat-missing node as NotReady and eventually evicts its Pods but does not by default delete the Node object itself, a permanently removed machine's Node object commonly requires explicit deletion, either manually or by cluster-lifecycle automation such as the Cluster Autoscaler, to fully remove the stale representation.

kubectl delete node worker-node-3

The Relationship During Cordoning and Draining

Preserving the Object While Suspending New Assignments

Cordoning a node formally modifies its Node object, setting spec.unschedulable: true, without affecting the underlying machine or its already-running Pods at all; the relationship between machine and object remains fully intact, only the scheduler's willingness to add new Pods to it changes.

kubectl cordon worker-node-3
kubectl get node worker-node-3 -o jsonpath='{.spec.unschedulable}'

Draining as a Distinct, Additional Step

Draining formally goes further, evicting already-running Pods from the node while leaving both the machine and its Node object entirely in place, meaning drain and cordon together affect only the machine's workload assignment, never the API relationship linking it to its Node object.

kubectl drain worker-node-3 --ignore-daemonsets --delete-emptydir-data

Why This Relationship Is Maintained This Way

Keeping the correspondence between machine and Node object continuously reaffirmed through kubelet-originated heartbeats, rather than assumed permanent once established, is what allows the cluster to detect and react correctly to the many ways a machine and its API representation can drift apart, unreachable but still running, deleted but still up, decommissioned but still present in etcd, treating each divergence as a distinct, individually observable and correctable condition rather than a single undifferentiated failure state.