4.3 Kubernetes Node API Relationship
Understanding how Kubernetes nodes interact with the API server and the role of API relationships in managing containerized workloads.
Kubernetes Node API Relationship is the specific pattern by which a physical or virtual machine and its corresponding Node API object stay synchronized with one another, describing the one-directional flow of truth from the actual machine to its API representation, and the consequences that follow when that representation falls out of sync with reality.
The Machine as Source of Truth, the Object as Reflection
Status Flows One Way
The relationship between a node and its Node object is architected so that truth flows from the physical or virtual machine outward into the API object, never the reverse; the kubelet reports what is actually happening on the machine, and the Node object is updated to reflect that reporting, rather than the object dictating the machine's actual state.
The Object Cannot Compel the Machine to Match It
Unlike a Pod's spec, which a controller actively works to make the running system match, a Node object's status fields are purely descriptive; no component is architected to force a machine's actual capacity or health to conform to whatever the Node object currently states.
Maintaining Synchronization Through Heartbeats
Continuous Reaffirmation, Not a One-Time Snapshot
This relationship depends on the kubelet continuously reaffirming that its machine is still present and healthy, through periodic heartbeat updates to the Node object; without this ongoing reaffirmation, the API's representation of the node would become an increasingly stale, and eventually misleading, snapshot of a machine that may no longer be in the same state.
Divergence as an Expected, Bounded Possibility
Because updates are periodic rather than instantaneous, some divergence between the machine's true current state and its Node object is always expected; the relationship is architected to tolerate this bounded staleness rather than assuming perfect real-time synchronization.
Consequences When the Relationship Breaks Down
Object Persists Even If the Machine Is Gone
If a machine is powered off, disconnected, or destroyed without a graceful removal process, its Node object does not disappear automatically; the relationship's one-directional nature means the object can continue to exist, now representing a machine that no longer exists at all, until the control plane's node controller marks it unhealthy and eventually removes it after a timeout.
Scheduling Risk During Divergence
During the window before this divergence is detected, the scheduler may still consider the stale Node object a valid placement target, illustrating why the timeliness of heartbeat-based synchronization directly affects the correctness of scheduling decisions elsewhere in the cluster.
Why This Relationship Is Deliberately Asymmetric
Machines Cannot Be Commanded Into Existence
This asymmetry exists because a Node object cannot be used to conjure a machine into existence or force a nonexistent machine's resources into being; the relationship necessarily flows from physical or virtual reality toward its API representation, never the other way around.