8.24 Kubernetes Pod Replacement Semantics

Kubernetes Pod Replacement Semantics is the set of rules governing how Kubernetes treats Pods as immutable, disposable units whose failure or removal is handled by creating an entirely new Pod object rather than repairing or resurrecting the original. This principle underlies much of Kubernetes' resilience model, since controllers are designed around the assumption that individual Pods are ephemeral and that the desired state of a workload is maintained by replacing failed instances rather than restarting them in place at the API object level.

Pods Are Not Rescheduled, They Are Replaced

Immutable Pod Identity

Once a Pod is bound to a node, it remains bound to that node for its entire lifetime; Kubernetes does not move a running Pod object from one node to another. If a node fails or a Pod is evicted, the original Pod object is deleted, and if a controller manages it, an entirely new Pod object, with a new name and a new UID, is created to take its place, typically on a different node.

Implications for Stateful Assumptions

Because replacement creates a new Pod identity rather than resuming the old one, applications that rely on local node-specific state without externalizing it to a volume or an external store will lose that state upon replacement. This is a foundational reason why stateful workloads generally require persistent volumes decoupled from any specific Pod instance.

Restart Policy and Container-Level Restarts

restartPolicy Values

The Pod-level restartPolicy field, which accepts Always, OnFailure, or Never, governs whether individual containers within an existing Pod are restarted in place by the kubelet after they terminate. This is distinct from Pod replacement, since a container restart under restartPolicy keeps the same Pod object, the same Pod IP, and the same Pod UID, only replacing the container process itself.

When Restart Policy Does Not Apply

Restart policy only governs container-level restarts within an existing, still-scheduled Pod. It has no bearing on what happens when the Pod itself is deleted, evicted, or the node it resides on becomes unreachable, since those scenarios require an entirely new Pod object to be created by the owning controller rather than any in-place restart mechanism.

Controller-Driven Replacement

ReplicaSet and Deployment Replacement Behavior

A ReplicaSet continuously compares the number of Pods matching its selector against its desired replica count. When a Pod is deleted, evicted, or otherwise disappears, the ReplicaSet controller observes the discrepancy and creates a new Pod to restore the desired count, rather than attempting to recover the specific Pod that was lost.

StatefulSet Replacement and Identity Preservation

StatefulSets replace Pods following the same create-new-object principle, but preserve a stable, ordinal-based identity and stable network name across replacements, along with reattaching the same persistent volume claim to the newly created Pod, allowing stateful applications to recover their durable data even though the Pod object itself is entirely new.

Rolling Updates as Structured Replacement

Deployment Rolling Update Strategy

When a Deployment's Pod template is changed, Kubernetes does not modify existing Pods in place, since Pod specifications are largely immutable after creation for most fields. Instead, it creates a new ReplicaSet with the updated template and gradually scales it up while scaling down the old ReplicaSet, replacing Pods incrementally according to the configured maxSurge and maxUnavailable parameters.

Immutable Fields in the Pod Specification

Most fields within a running Pod's specification, including the container image list under certain fields and the set of volumes, cannot be modified after creation; attempting to change them requires deleting and recreating the Pod, reinforcing why higher-level controllers exist specifically to manage this replacement lifecycle on behalf of the user.

Graceful Termination Preceding Replacement

terminationGracePeriodSeconds

Before a Pod is fully removed to make way for its replacement, Kubernetes sends a termination signal to the container processes and waits up to the duration specified by terminationGracePeriodSeconds for the Pod to shut down cleanly, allowing in-flight requests to complete and connections to be drained before the underlying containers are forcibly killed.

Replacement Timing Relative to Termination

Depending on the controller and update strategy in use, a replacement Pod may be created before, during, or only after the old Pod has fully terminated, a timing distinction that directly affects whether brief overlap in capacity occurs during the transition or whether there is a temporary dip in available replicas.