API machinery
Owners, Finalizers and Garbage Collection
1.Owners and dependents
The garbage collector (GC) deletes a dependent once all its owners are gone. The link lives on the dependent. Deployment, ReplicaSet, StatefulSet, DaemonSet, Job and CronJob write it for you :
ownerReferences: # on the Pod - apiVersion: apps/v1 kind: ReplicaSet name: nginx-deployment-6b474476c4 uid: <owner uid> controller: true # at most one blockOwnerDeletion: true # default false
Arrows point from dependent to owner. Labels pick what a controller manages, owners pick what gets cleaned up.
2.Same namespace, or cluster-scoped
- A reference has no namespace field, so the owner must sit in the dependent's namespace, or be cluster-scoped.
- Owner in another namespace : the ref counts as absent, so the GC may delete your dependent.
- Cluster-scoped dependent with a namespaced owner : never collected (v1.20+). Both raise a Warning event,
OwnerRefInvalidNamespace.
3.Cascading deletion : three modes
Deleting an owner picks the order things disappear in. kubectl --cascade maps to DeleteOptions..
| Mode, kubectl flag | Owner gets | What happens |
|---|---|---|
| Background (default) --cascade=background | no finalizer | Owner goes at once. The GC deletes the dependents afterwards. Everyday deletes. |
| Foreground --cascade=foreground | foregroundDeletion | Owner stays (deletionTimestamp set) until the GC has deleted each dependent with blockOwnerDeletion=true. For teardown that must not lose the owner first. |
| Orphan --cascade=orphan | orphan | The GC strips the owner uid from each dependent, then the owner goes. Dependents keep running, so you can swap a controller without killing its Pods. |
A raw API DELETE of a batch/v1 Job defaults to orphan. orphanDependents is deprecated. blockOwnerDeletion only matters for foreground, and the plugin that polices it (OwnerReferencesPermissionEnforcement) is off by default in v1.37.
4.Other collectors
| Who, knob | What it collects |
|---|---|
Job TTL controllerttlSecondsAfterFinished (unset = keep) | A finished Job and its Pods, N seconds after it finishes (0 = at once). Stable v1.23 |
PodGC--terminated-pod-gc-threshold (12500) | Succeeded / Failed Pods above the count |
- Images, 5 min : disk over imageGCHighThresholdPercent (85), least recently used first, down to imageGCLowThresholdPercent (80). imageMinimumGCAge 2m, imageMaximumGCAge 0 (off).
- Containers, 1 min : MinAge 0, MaxPerPodContainer 1, MaxContainers -1 (flags deprecated).
5.Commands
| Command | What it does |
|---|---|
kubectl get pod <pod> -o jsonpath='{. | Lists the owners. "controller":true marks the controller |
kubectl delete deployment nginx-deployment --cascade=foreground | Owner stays (foregroundDeletion) until its ReplicaSet and Pods are gone |
kubectl patch job pi --type=merge -p '{"spec":{"ttlSecondsAfterFinished":600}}' | Makes a finished Job eligible for TTL cleanup |
1.Finalizers : deletion gates
A finalizer is a key in metadata.. While any key is left, the object stays.
- DELETE sets
deletionTimestampand returns 200 OK (202 only for the deprecatedorphanDependents=false). Terminating : keys can only be removed, no undelete. - Custom keys need a domain,
example.(CRs only warn). Bare :com/ cleanup kubernetes,orphan,foregroundDeletion. --force --grace-period=0skips graceful termination, not finalizers.
2.In your controller
- Add your key before making anything external.
- deletionTimestamp set ? Clean up (idempotent).
- Remove only your own key, then Update.
- Failed ? Return the error and retry. The key stays.
- RBAC : plain
updateon the kind.<kind>/only gates setting blockOwnerDeletion on children.finalizers
More : Controllers and Reconciliation, Operators.
- Namespace : an aggregated APIService is down (
NamespaceDeletionDiscoveryFailure), or CRs outlived their operator (NamespaceFinalizersRemaining). - PVC : a Pod still mounts it (pvc-protection).
- CR : its operator was uninstalled before it.
3.Built-in finalizers you will meet
| Key | On (added by) | Gone when |
|---|---|---|
| kubernetes.io/pvc-protection, kubernetes.io/pv-protection | PVC, PV (StorageObjectInUseProtection) | No Pod uses the PVC, the PV is unbound |
| kubernetes.io/pv-controller (in-tree), external-provisioner.volume.kubernetes.io/finalizer (CSI) | PV with reclaim Delete (v1.33) | Backend volume deleted |
| foregroundDeletion, orphan | Any owner (API server) | GC is done with the dependents |
kubernetes (in spec.finalizers) | Namespace, on create | All content gone, Pods first |
| batch.kubernetes.io/job-tracking | Job Pods (v1.26) | Job controller counted the Pod |
4.Stuck in Terminating ?
A finalizer is a promise that someone will clean up. Find the someone before you delete the promise.
5.Commands
| Command | What it does |
|---|---|
kubectl get pvc -n shop -o custom-columns=NAME:. | What is Terminating, and which key holds it |
kubectl get ns shop -o jsonpath='{range . | Why a namespace is stuck. On a DiscoveryFailure, fix the APIService that kubectl get apiservices shows as False |
kubectl describe pvc data-postgres-0 -n shop | Used By lists the Pods that keep pvc-protection in place |
kubectl patch widgets. | Last resort, drops ALL keys. Only if the controller is gone for good and you did its cleanup |