Kubernetes Static Pod Runtime

Kubernetes Static Pod Runtime is the mode of operation in which a kubelet manages a Pod directly from a locally supplied manifest, without that Pod ever being created or scheduled through the API server, giving certain workloads — most notably the control plane's own core components in many cluster setups — a way to run reliably even when the API server itself is unavailable or has not yet started. A static Pod is defined entirely on the node, bypasses the scheduler and API server as the source of its spec, and is supervised by the local kubelet's own lifecycle logic rather than by a controller running in the control plane.

How Static Pods Are Defined

Manifest-Based Configuration

The kubelet is configured with a static Pod path (or, less commonly, a static Pod URL) pointing to a directory of Pod manifest files in YAML or JSON; the kubelet watches this location and treats every valid manifest it finds there as a Pod it is responsible for running, independent of anything the API server knows about.

File Watching and Change Detection

The kubelet periodically scans the static Pod directory (and reacts to filesystem change events where supported) to detect manifests being added, modified, or removed, applying the same kind of reconciliation to these local changes that it applies to Pod updates arriving from the API server through its normal watch mechanism.

The Mirror Pod Mechanism

Why Mirror Pods Exist

Because static Pods are not created through the API server, they would otherwise be entirely invisible to kubectl and other components expecting Pods to be represented as API objects; to close this visibility gap, the kubelet creates a corresponding read-only "mirror Pod" object on the API server for every static Pod it is running.

Mirror Pod Behavior and Limits

A mirror Pod reflects the static Pod's actual status as observed by the kubelet, but it cannot be used to control the static Pod: deleting or attempting to modify the mirror Pod through the API server does not stop or change the underlying static Pod, since the kubelet continues to derive the Pod's true desired state from the local manifest file, not from the API server object. Deleting the local manifest file, or the kubelet detecting the mirror Pod was deleted and recreating it, is what actually governs the static Pod's lifecycle.

Identifying Static Pods via Mirror Pods

Mirror Pods carry an annotation identifying them as mirrors of a static Pod and pointing back to the source node, which is how operators and tooling can distinguish a static Pod's API representation from an ordinary, scheduler-managed Pod when inspecting cluster state.

Why Static Pods Matter for the Control Plane

Bootstrapping Without a Running API Server

In many self-hosted cluster architectures, the API server, scheduler, and controller manager are themselves run as static Pods on control plane nodes, which resolves an otherwise circular dependency: these components cannot be scheduled through the API server because the API server is one of the components not yet running, so the kubelet starts them directly from local manifests instead.

Resilience to Control Plane Outages

Because static Pod lifecycle is entirely local to the kubelet, a static Pod continues running, and will be restarted by the kubelet if it crashes, even during periods when the API server is completely unreachable, which is precisely the resilience property that makes static Pods suitable for hosting the control plane components the rest of the cluster depends on.

Operational Characteristics

restartPolicy and Standard Lifecycle Behavior

Static Pods go through the same SyncPod reconciliation, PodAdmitHandler admission checks, probe evaluation, and restart policy enforcement as any other Pod the kubelet manages, since from the kubelet's internal perspective a static Pod is simply a Pod whose source is the local file path rather than the API server's watch stream.

Updating a Static Pod

To change a running static Pod's configuration, an operator or provisioning tool edits the manifest file in the static Pod directory; the kubelet detects the change, and, because Pod specs are largely immutable once running, typically stops the existing Pod and starts a new one reflecting the updated manifest rather than attempting an in-place update of most fields.

Static Pods Cannot Reference Certain API Objects

Because static Pods are not processed through normal API server admission and defaulting, they cannot reference objects such as ConfigMaps, Secrets, or ServiceAccounts in the usual declarative way in all kubelet versions and configurations, which constrains static Pods to workloads that can be fully self-contained or that rely on statically provisioned files on the node itself.