Kubernetes Control Plane Object Lifecycle

Kubernetes Control Plane Object Lifecycle is the precise sequence of internal control plane actions an object passes through from creation to final removal from etcd, tracing specifically how the garbage collector controller, finalizers, and cascading deletion logic interact to turn a single delete request into the coordinated removal of an entire tree of dependent objects, rather than the immediate erasure a simple API call might suggest.

Creation and Owner Graph Construction

Establishing Ownership at Creation Time

When a controller creates a dependent object, it formally sets that object's ownerReferences at creation time, immediately registering it within the cluster's owner-dependent graph; the garbage collector controller observes this graph continuously, watching every namespaced and cluster-scoped resource type for owner reference changes.

metadata:
  ownerReferences:
    - apiVersion: apps/v1
      kind: ReplicaSet
      name: codartium-api-7d9f8c
      uid: 91a2b3c4-5678-...
      controller: true
      blockOwnerDeletion: true

Deletion Request and the deletionTimestamp

Marking, Not Immediately Removing

A DELETE request against an object without finalizers and without dependents formally results in immediate removal from etcd; but where finalizers are present, the API server instead sets metadata.deletionTimestamp and leaves the object in etcd, formally transitioning it into a "terminating" state rather than deleting it outright.

kubectl get pod codartium-api-abc123 -o jsonpath='{.metadata.deletionTimestamp}'

Finalizer Processing

Controllers Racing to Clear Their Own Finalizer

Any controller that added a finalizer to an object is formally responsible for observing that object's deletionTimestamp becoming set, performing whatever cleanup its finalizer represents, external resource deprovisioning, dependent record removal, and then removing its own entry from the finalizers list once that cleanup completes.

metadata:
  finalizers:
    - codartium.io/cleanup-external-storage
  deletionTimestamp: "2024-05-12T09:20:00Z"

Actual Removal Only After Every Finalizer Clears

The object is formally removed from etcd only once its finalizers list becomes empty; a stuck finalizer, one whose owning controller has crashed or is failing its cleanup logic, formally leaves the object present but terminating indefinitely, a state directly observable and diagnosable through the object's own fields.

kubectl get pod codartium-api-abc123 -o jsonpath='{.metadata.finalizers}'

Cascading Deletion via the Garbage Collector

Propagation and Orphan Policies

Upon an owner object's deletion, the garbage collector controller formally applies one of three deletion propagation policies: Foreground, which blocks the owner's own final removal until every dependent is deleted first; Background, which deletes the owner immediately and removes dependents asynchronously afterward; and Orphan, which removes only the ownership link, leaving dependents behind as independent objects.

kubectl delete deployment codartium-api --cascade=foreground
kubectl delete deployment codartium-api --cascade=background
kubectl delete deployment codartium-api --cascade=orphan

blockOwnerDeletion as a Finer-Grained Control

A dependent's ownerReferences entry may formally set blockOwnerDeletion: true, which, combined with the Foreground policy, prevents the owner's own removal until that specific dependent's finalizers have also cleared, giving individual dependents a way to formally gate the completion of their owner's deletion beyond the garbage collector's default behavior.

Orphan Detection and Adoption

Handling Dangling Owner References

If an owner referenced in a dependent's ownerReferences no longer exists, the garbage collector controller formally treats the dependent as orphaned and, depending on configuration, deletes it or leaves it as an independent object, resolving inconsistencies that could otherwise arise from an owner having been removed through an unusual path, such as direct etcd manipulation in a non-production environment.

kubectl get pods -n codartium-team -o json | jq '.items[] | select(.metadata.ownerReferences != null)'

Why the Lifecycle Is Structured with This Many Stages

Introducing deliberate stages, marking via deletionTimestamp, finalizer-gated cleanup, propagation-policy-controlled cascading, rather than immediate, unconditional removal, is what allows controllers to guarantee that external side effects tied to an object's existence, provisioned cloud resources, registered external records, are properly cleaned up before that object's API record vanishes, preventing the platform's own bookkeeping from ever getting ahead of the real-world state it is responsible for representing.