5.18 Kubernetes Object Lifecycle Model

Kubernetes Object Lifecycle Model is the sequence of states an API object passes through from initial creation, through any number of updates, to eventual deletion, including the specific mechanics of graceful termination, finalizer-gated cleanup, and the resource-version-tracked history of changes that together define what it means for an object to exist, change, and cease to exist within the cluster.

Creation

Submission and Assignment of Identity

An object's lifecycle begins when a client submits a creation request; the API server validates and defaults the submitted manifest, then assigns system-managed identity fields, uid, initial resourceVersion, creationTimestamp, and generation, before persisting the object to etcd and returning the fully populated result.

Admission at Creation Time

Before persistence, the object passes through the full admission chain, mutating webhooks and built-in defaulting first, then validating webhooks and built-in validation, meaning the object that is actually created may differ from what was originally submitted if any mutating step altered it along the way.

Active Lifetime and Modification

Updates and Version Tracking

Throughout an object's active lifetime, it can be updated any number of times, with each successful modification incrementing its resourceVersion, and, for spec changes specifically, its generation, giving both a fine-grained change counter and a coarser signal of meaningful desired-state changes that controllers can key off of.

Concurrent Modification Handling

Because multiple clients can attempt to modify the same object concurrently, the lifecycle model incorporates optimistic concurrency control through resourceVersion checks on full updates, and field-level ownership tracking through server-side apply, both mechanisms existing specifically to keep the object's state coherent despite simultaneous writers.

Reconciliation as Ongoing Lifecycle Activity

For most resources, a substantial portion of an object's active lifetime consists not of direct client-initiated changes but of a controller continuously reconciling the object, observing its spec, taking action, and updating its status, meaning the lifecycle model includes long periods where the object itself is stable while the system around it continues actively working to keep it in the intended state.

Deletion Initiation

The deletionTimestamp

A delete request against an object without finalizers results in immediate removal, but if the object carries one or more finalizers, the API server instead sets a deletionTimestamp and leaves the object present, transitioning it into a terminating state rather than deleting it outright.

Graceful Deletion Options

Delete requests can specify a gracePeriodSeconds and a propagationPolicy, influencing how long dependent processes have to react before final removal and whether dependent objects, linked through owner references, are deleted immediately in the background or only after the parent's own removal completes in the foreground.

The Terminating State

Finalizer-Gated Persistence

While deletionTimestamp is set and finalizers remain, the object continues to exist and remains visible to clients, but is understood by convention to be in the process of being torn down; each controller responsible for a listed finalizer performs whatever cleanup it needs, then removes its entry from the finalizers list.

Completion of Deletion

Once the finalizers list becomes empty, the API server proceeds to permanently remove the object from etcd, at which point it is fully deleted and no longer retrievable by any client, marking the true end of the object's lifecycle rather than the earlier deletion request itself.

Lifecycle Visibility Through Watches

Observing Every Transition

Clients maintaining a watch on a resource observe the full lifecycle in real time: an ADDED event on creation, MODIFIED events for each subsequent change including the setting of deletionTimestamp, and a final DELETED event once the object is actually removed from storage, giving controllers everything needed to react appropriately at each stage.

Bookmarks and Resumption

Long-lived watches periodically receive BOOKMARK events carrying an updated resourceVersion without any actual object change, allowing a client to resume an interrupted watch from a recent point without needing to have captured every single prior event, a detail relevant to reliably tracking an object's lifecycle across connection interruptions.

Lifecycle Differences for Special Object Types

Immutable and Log-Like Objects

Some object types, such as Event, are effectively append-and-expire in nature rather than long-lived and mutable, automatically aging out of etcd after a retention period rather than following the same deliberate, finalizer-gated deletion path that most workload and configuration resources follow.