Kubernetes Object Lifecycle Model

Kubernetes Object Lifecycle Model is the sequence of states every API object passes through from initial creation to final removal, encompassing not just the simple existence-or-absence of the object but the intermediate states — pending finalizers, graceful termination, and the propagation of a deletion request across dependent objects — that give Kubernetes deletion a controlled, observable process rather than an instantaneous, unrecoverable event. This model matters because many objects represent real, running infrastructure or workloads, and an object's removal from the API often needs to be coordinated with cleanup work that takes real time to complete correctly.

Creation

From Request to Persisted Object

An object's life begins when a create request successfully passes through the full admission pipeline — authentication, authorization, mutating and validating admission, schema validation — and is persisted to etcd, at which point the API server assigns it a metadata.uid and initial resourceVersion, and any watchers immediately receive an ADDED event.

Immediate Post-Creation State

Newly created objects typically begin in a state their type's controllers recognize as needing initial reconciliation — a newly created Pod has no container status yet, a newly created PersistentVolumeClaim is unbound — and it is the responsibility of the relevant controller, observing the ADDED event, to begin driving that object toward its next meaningful state.

Update

Continuous Reconciliation Against a Changing Spec

Throughout an object's active life, its spec may be updated repeatedly by users or controllers, each successful update producing a new resourceVersion and a corresponding MODIFIED watch event, and it is this continuous stream of updates that the reconciliation loop pattern is built to respond to, treating every update as a fresh opportunity to re-evaluate whether current state still matches desired state.

Status Updates as Part of the Same Lifecycle

Status updates, though conceptually distinct from spec updates, use the same underlying update mechanism and produce the same kind of MODIFIED events, meaning from a pure lifecycle perspective, an object's active life consists of an ongoing interleaving of spec changes from clients and status changes from controllers, both visible through the same watch stream.

Deletion Initiation

The deletionTimestamp Marker

Deleting an object with finalizers does not remove it immediately; instead, the API server sets metadata.deletionTimestamp to the current time and leaves the object present but now understood by convention to be terminating, allowing controllers watching for this marker to begin whatever graceful shutdown behavior the object's type requires.

Immediate Deletion When No Finalizers Apply

Objects with no finalizers set are removed from etcd immediately upon a delete request, generating a DELETED watch event directly, without ever passing through an intermediate terminating state, which is the common case for simple objects with no cleanup dependencies.

Graceful Termination

Pods as the Canonical Example

Pod deletion illustrates graceful termination concretely: upon receiving a delete request, the kubelet begins the container termination sequence (PreStop hooks, then SIGTERM, then a grace period, then SIGKILL if needed) while the Pod object itself remains visible with a deletionTimestamp set, only actually disappearing from the API once the kubelet has finished tearing down containers and removed whatever finalizers it or other controllers had attached.

Finalizer-Gated Cleanup for Other Types

The same pattern applies broadly: a PersistentVolume with a finalizer tied to CSI driver cleanup remains present until the driver confirms the underlying storage has been properly detached and released, ensuring the API object's disappearance never outpaces the real-world cleanup it represents.

Cascading Deletion Through Ownership

Propagation Policies

When an owning object is deleted, the garbage collector controller applies the deletion's propagation policy to determine what happens to dependents: Foreground blocks the owner's actual removal until all dependents are deleted first, Background deletes the owner immediately while dependents are cleaned up asynchronously afterward, and Orphan removes the owner reference from dependents, leaving them behind as independent objects.

Final Removal

An object's lifecycle concludes only once every finalizer has been cleared and, if it was a dependent awaiting cascading deletion under a Foreground policy, once that deletion has actually been permitted to proceed; at that point the API server removes it from etcd permanently, and its UID becomes historical, never to be reassigned to any future object even if a new object later reuses the same name.