Kubernetes Node Agent Architecture

Kubernetes Node Agent Architecture is the internal design of the software agents running on every node, the kubelet and kube-proxy, tracing their individual internal loops and how those loops interact with the API server, the container runtime, and the local operating system to keep a node's actual state synchronized with what the control plane has assigned to it. Both agents share the general shape of a control loop, but each is architected around a distinct internal model suited to its specific responsibility, container lifecycle for the kubelet, packet forwarding rules for kube-proxy.

kubelet Internal Architecture

The Pod Worker Model

Internally, the kubelet formally maintains a separate, per-Pod worker goroutine for every Pod assigned to its node, each independently responsible for driving that one Pod's containers toward the state described in its PodSpec, an architecture chosen so that a slow or stuck operation on one Pod does not block reconciliation of any other Pod on the same node.

Sources of Truth: API, Static, and Manifest

A kubelet formally assembles its view of Pods it should run from multiple configured sources, most commonly the API server for ordinary Pods, but also static Pod manifests read directly from a local directory, used for bootstrapping control plane components before the API server itself is available to serve them.

ls /etc/kubernetes/manifests/
cat /etc/kubernetes/manifests/kube-apiserver.yaml

Pod Lifecycle Event Generator (PLEG)

The kubelet formally runs a Pod Lifecycle Event Generator that periodically polls the container runtime for the actual state of containers, comparing it against the kubelet's last known state and generating internal events for any detected changes, the mechanism that decouples the kubelet's reconciliation cadence from directly polling the runtime on every single operation.

Probe Manager

A dedicated probe manager component formally tracks and schedules liveness, readiness, and startup probes independently for every container across every Pod worker, feeding probe results back into each Pod worker's own state rather than being embedded directly inside the pod worker loop itself.

kube-proxy Internal Architecture

Watch-Driven Rule Synchronization

kube-proxy formally watches Service and EndpointSlice objects through the same informer pattern used by controllers, maintaining a local, in-memory model of the cluster's Service topology and periodically synchronizing that model into the node's actual packet-forwarding configuration.

iptables Mode Internals

In iptables mode, kube-proxy formally generates a structured chain of iptables rules per Service, using probabilistic rule matching to distribute connections across backend endpoints, and rewrites the complete rule set on each synchronization cycle rather than performing incremental, per-change updates, a design that trades some update latency for implementation simplicity.

iptables -t nat -L KUBE-SVC-XXXX -n

IPVS Mode Internals

In IPVS mode, kube-proxy formally programs the Linux kernel's IP Virtual Server subsystem directly, maintaining a virtual server entry per Service and real server entries per endpoint, an architecture offering more efficient lookup and load-balancing algorithms than iptables' linear rule matching, particularly as Service count grows large.

ipvsadm -L -n

Shared Architectural Properties

Local Autonomy

Both agents formally operate with local autonomy: neither kubelet nor kube-proxy coordinates directly with any instance of itself on another node, each independently reconciling only its own node's state from the same shared cluster-wide API objects, an architecture that allows the aggregate behavior of many nodes to remain correct without any inter-node communication protocol.

Resilience to Restart

Because both agents formally reconstruct their internal state entirely from the API server (and, for the kubelet, the local container runtime) on startup, restarting either agent process causes no loss of correctness; the agent simply re-observes current state and resumes reconciling from wherever it left off.

systemctl restart kubelet
systemctl status kube-proxy

Why Node Agents Are Architected This Way

Structuring both agents as independent, per-node control loops with no cross-node coordination requirement is what formally allows the cluster's data plane to scale by simply adding nodes: each new node's agents observe the same API server and begin reconciling their own local state without requiring any change to, or coordination with, the agents already running elsewhere.