4.18 Kubernetes Static Pod Runtime

Kubernetes Static Pod Runtime is the execution model in which the kubelet manages a pod's entire lifecycle directly from manifest files located on the node's local filesystem, rather than from pod definitions retrieved through the API server, making static pods independent of API server availability and tightly bound to the specific node the kubelet is running on.

What Makes a Pod Static

Node-Local Manifest Source

Static pods are defined by placing a pod manifest file, typically in YAML format, into a directory the kubelet is configured to watch, commonly /etc/kubernetes/manifests. The kubelet monitors this directory directly on the local filesystem rather than through any API server watch mechanism.

No Controller Ownership

Unlike ordinary pods, which are usually created and managed by controllers such as Deployments or DaemonSets through the API server, static pods have no such owning controller; the kubelet itself is entirely responsible for their creation, restart, and lifecycle management based solely on the presence and content of the manifest file.

Node Binding by Construction

Because a static pod's manifest lives on a specific node's filesystem, that pod can only ever run on that node. There is no scheduling decision involved, since the kubelet reads the manifest locally rather than receiving a pod assignment from the scheduler.

The Manifest Watching Mechanism

File-Based Source

The kubelet's static pod manager watches the configured manifest directory using filesystem notifications, detecting when manifest files are added, modified, or removed, and reacting by creating, updating, or deleting the corresponding pod on the node.

URL-Based Source

In addition to a local directory, the kubelet can be configured to periodically fetch static pod manifests from a URL, polling at a configured interval, which is less commonly used than the directory-based approach but supported for environments needing centrally distributed static pod definitions.

Manifest Change Reconciliation

When a static pod's manifest file changes, the kubelet detects the difference and applies it by terminating the existing pod and starting a new one with the updated specification, since static pods do not support the same in-place update reconciliation used for API-server-managed pods.

Mirror Pod Representation

Why Mirror Pods Exist

Because static pods bypass the API server entirely for their definition, Kubernetes tooling such as kubectl would have no visibility into them without an additional mechanism. To solve this, the kubelet creates a read-only mirror pod object in the API server for every static pod it is running.

Mirror Pod Characteristics

A mirror pod carries an annotation identifying it as a mirror of a static pod and reflects the static pod's actual running status, but it cannot be modified or deleted through the API server in the normal way; deleting the mirror pod does not delete the underlying static pod, since the kubelet will simply recreate the mirror pod to match the still-present static pod on disk.

Status Synchronization

The kubelet keeps the mirror pod's status synchronized with the actual static pod's runtime state, using the same status reporting pipeline used for ordinary pods, so that mirror pods appear in kubectl get pods output with accurate phase and container status information.

Typical Use Cases

Bootstrapping Control Plane Components

Static pods are commonly used to run the core control plane components, the API server, controller manager, and scheduler, on control plane nodes, since these components cannot depend on the API server being available yet when the very first API server instance itself needs to be started.

Node-Critical Infrastructure

Some cluster distributions also use static pods for node-critical infrastructure that must remain running even if connectivity to the API server is temporarily lost, since static pod management does not depend on that connectivity once the manifest is already present on disk.

Lifecycle Independent of API Server

Resilience to Control Plane Outages

Because the kubelet reads static pod manifests locally, a static pod continues running, and can even be restarted by the kubelet after a crash, entirely independent of whether the API server is reachable, which is precisely why control plane components benefit from this model.

Kubelet Restart Behavior

If the kubelet itself restarts, it re-scans the manifest directory on startup and reconciles the static pods it finds there against what it observes running in the container runtime, recreating any static pods that are missing and adopting any that are already running and match the current manifest.

Constraints and Limitations

No Access to Most API-Server Managed Objects

Static pod manifests cannot reference objects that would normally require API server resolution, such as ServiceAccounts, ConfigMaps, or Secrets, since the kubelet processes the manifest without that broader cluster context available at pod creation time.

Namespace Restriction

Mirror pods created for static pods are always placed in a predetermined namespace, and their name is automatically suffixed with the node's hostname, avoiding naming collisions between static pods with the same manifest name running on different nodes.