Understanding Kubernetes deletion mechanics with finalizers and owner references

In a post on the Kubernetes Blog in May 2021, Aaron Alpar detailed the internal mechanics of object deletion within Kubernetes. The article clarifies why resources sometimes persist after a delete command is issued and explains the roles of finalizers and owner references in managing cluster state.

What happened

Kubernetes provides standard commands for creating, reading, updating, and deleting objects, but the deletion process is more complex than a simple removal from storage. When a user issues a kubectl delete command, the system does not always immediately remove the object from its registry, etcd. Instead, the operation may enter a pending state if specific conditions are met, such as the presence of finalizers or complex owner relationships.

The article demonstrates that while basic deletions work as expected for simple resources like ConfigMaps without extra metadata, adding finalizers changes the behavior significantly. A finalizer acts as a pre-delete hook, signaling to controllers that cleanup operations must occur before the resource is fully removed. If these hooks are not resolved, the object remains in a terminating state, visible via a deletion timestamp but still present in the cluster.

Furthermore, the relationship between resources, defined by owner references, dictates how groups of objects are deleted together. Deleting a parent object can trigger the deletion of its children, a process known as cascading. However, this behavior can be modified using propagation policies, allowing developers to orphan children or control the order of deletion. Understanding these mechanisms is critical for debugging stuck namespaces or lingering resources.

How it works

Finalizers are keys attached to a resource’s metadata that prevent immediate garbage collection. They function similarly to annotations but carry semantic weight for controllers. When a delete request is made for an object with finalizers, Kubernetes updates the object with a deletionTimestamp but blocks its removal from etcd. The object remains in this state until a controller removes the finalizer keys, signaling that cleanup is complete. If no controller manages the finalizer, it becomes a "dead" finalizer, requiring manual intervention via a patch command to remove the key and allow deletion to proceed.

Owner references establish parent-child relationships between resources within the same namespace. Each reference includes the name and unique identifier (UID) of the parent object. When a parent is deleted, Kubernetes checks these references to determine if children should also be removed. This cascading deletion is controlled by a propagation policy. The default policy, which changed to background in kubectl v1.20, allows the parent to be deleted first while children are removed asynchronously. Other options include foreground, where children are deleted before the parent, and orphan, which ignores owner references and leaves children intact.

Key details

• Finalizers are lists of keys on resources that signal pre-delete operations to controllers.
• Objects with finalizers are not immediately removed; they receive a deletionTimestamp and remain visible until finalizers are cleared.
• Owner references link resources via name and UID, enabling cascading deletions of child objects when a parent is removed.
• The default cascade behavior in kubectl v1.20 and later is background, whereas earlier versions defaulted to true.
• Propagation policies (Foreground, Background, Orphan) control the order of deletion and can only be set via direct API calls, not standard kubectl flags.
• Stuck namespaces can be forced to finalize by updating the finalize subresource via the API, though this risks leaving orphaned objects.

Why it matters

For engineers building and maintaining Kubernetes platforms, understanding deletion mechanics prevents confusion when resources do not disappear as expected. A common scenario involves a namespace that remains in a Terminating state because a custom resource or third-party controller has added a finalizer that is no longer being processed. Without knowing how to inspect and patch finalizers, operators may struggle to clean up clusters, leading to resource leaks and deployment failures.

Additionally, managing owner references correctly ensures that application teardowns are clean and predictable. If a developer deletes a Deployment without understanding cascading rules, they might inadvertently leave behind Pods or Services that consume resources. Conversely, knowing how to use the orphan policy allows for safe migration strategies where child resources need to survive the deletion of their original parent. This knowledge is essential for writing robust operators and automation scripts that interact with the Kubernetes API.

What you can do

• Inspect objects stuck in deletion by checking their YAML output for finalizers and deletionTimestamp fields.
• Remove dead finalizers manually using kubectl patch with a JSON operation to remove the specific finalizer key from the metadata.
• Use kubectl get with owner references to visualize dependencies between resources before performing bulk deletions.
• Test cascading behavior in a non-production environment by creating parent-child ConfigMaps and observing the effects of different delete commands.
• Utilize kubectl proxy to make direct API calls when you need to specify propagation policies like Foreground or Background.
• Exercise caution when forcing namespace finalization via the API, as it may leave orphaned resources that require manual cleanup.