This article explains how finalizers work in Kubernetes, how to use them effectively, examples of common finalizers, and how to add, list, and remove finalizers.

What is a Finalizer in Kubernetes?

A finalizer is essentially a pre-delete hook that Kubernetes applies to resources, ensuring they’re retained until certain conditions are met or actions are completed. Finalizers are implemented as entries within an object’s metadata and are represented as strings, typically following a format such as example.com/finalizer. When a resource has a finalizer attached, it is only marked for deletion, and the actual deletion process is deferred until the finalizer is removed. This allows Kubernetes to handle dependencies and clean up associated resources safely.

How to Use Finalizers in Kubernetes

Using finalizers in Kubernetes involves attaching the finalizer string to the object’s metadata. This is typically done when the object is created, but it can be added later. Once the finalizer is attached, it will prevent the object from being immediately deleted, allowing custom logic to execute first.

Example: Attaching a Finalizer to a Kubernetes Resource

Suppose you want to create a ConfigMap with a finalizer that ensures cleanup tasks are performed before it is deleted.


  apiVersion: v1
kind: ConfigMap
metadata:
  name: example-configmap
  finalizers:
    - example.com/finalizer
data:
  example.key: "example-value"


In this example, the finalizer example.com/finalizer is added to the ConfigMap’s metadata. When you attempt to delete this ConfigMap, it will enter a “deletion” phase but won’t be fully removed until the finalizer is removed. You can write custom cleanup logic in your application to detect when the resource is in this phase, perform the required tasks, and then remove the finalizer.

Examples of Common Finalizers in Kubernetes

Some commonly used finalizers in Kubernetes include:

  1. kubernetes.io/pv-protection: Used with Persistent Volume (PV) resources to prevent accidental deletion. When set, it keeps a PV in a protected state until it’s explicitly removed.
  2. foregroundDeletion: Ensures that all dependent resources are deleted before the resource itself is removed. This is commonly used in scenarios where you want to enforce cascading deletions, such as deleting a namespace with all resources within it.
  3. orphan: Preserves child resources when the parent is deleted. For instance, if you delete a resource with orphan finalizer, it will leave dependent resources (like Pods created by a Job) in place instead of deleting them.

These finalizers enable Kubernetes administrators to enforce policies and prevent unintended deletions or data loss.

How to Remove a Finalizer in Kubernetes

To remove a finalizer from a resource, you typically update the resource’s metadata to remove the finalizer entry. This action signals Kubernetes that the cleanup tasks are complete, allowing the resource to be fully deleted.

Steps to Remove a Finalizer:

Identify the Resource:
First, check the finalizers attached to the resource using kubectl get or kubectl describe.


  kubectl get configmap example-configmap -o yaml

Edit the Resource to Remove the Finalizer: Use kubectl edit to manually remove the finalizer entry from the resource’s metadata.


  kubectl edit configmap example-configmap Remove the finalizer entry under metadata.finalizers:yamlCopy codemetadata: finalizers: []

Save and Close: Once the finalizer is removed, save and close the editor. Kubernetes will then allow the resource to be deleted fully.

Alternatively, you can use kubectl patch to remove the finalizer:


  kubectl patch configmap example-configmap -p '{"metadata":{"finalizers":[]}}' --type=merge

This approach is quicker and useful in scripts or automation workflows.

Listing Finalizers in Kubernetes

To see the finalizers attached to a resource, you can use kubectl get or kubectl describe commands to inspect the resource’s metadata.

Example: Listing Finalizers on a ConfigMap


  kubectl get configmap example-configmap -o yaml







Output:






  apiVersion: v1
kind: ConfigMap
metadata:
  name: example-configmap
  finalizers:
    - example.com/finalizer
data:
  example.key: "example-value"







Alternatively, you can use kubectl describe for a more detailed view:






  kubectl describe configmap example-configmap







This output will show the finalizers attached to example-configmap, as well as other metadata about the object.





Practical Use Cases for Finalizers in Kubernetes





    

  1. Protecting Persistent Volumes: Finalizers like kubernetes.io/pv-protection are commonly used with Persistent Volumes to ensure that valuable data is not lost by accidental deletion.
    2. 




  2. Orphaning Child Resources: For resources that spawn child resources (like Jobs spawning Pods), finalizers can be used to ensure child resources are not deleted with the parent, which is useful for resource tracking or post-deletion analysis.
    3. 




  3. Custom Resource Cleanup: When working with Custom Resource Definitions (CRDs), you may have external resources, like cloud storage or databases, that need to be deleted when the CRD is deleted. Finalizers enable custom controllers to handle such cleanups by marking resources for deletion and ensuring they are cleaned up properly before deletion completes.
    4. 






Summary





Finalizers in Kubernetes provide a powerful way to control the deletion lifecycle of resources, allowing applications and administrators to perform necessary cleanup tasks before a resource is permanently removed. They can be added to Kubernetes resources for protecting data, managing dependencies, or implementing custom deletion workflows. While finalizers offer valuable functionality, they require careful management to avoid “stuck” resources that cannot be deleted if finalizers aren’t handled correctly.





Using finalizers can enhance resource reliability and safety, especially in multi-tenant environments or complex applications that rely on external resources or dependent objects. By understanding how to add, list, and remove finalizers, Kubernetes users can take full advantage of this feature for robust resource management.





References and Further Reading





    

  1. Kubernetes Official Documentation on Finalizers
    Detailed documentation on finalizers and their usage in Kubernetes.
    2. 




  2. Managing Deletion and Cleanup with Finalizers
    Kubernetes Blog: Using Finalizers for Resource Management – Insights and use cases for finalizers in resource lifecycle management.
    3. 




  3. Kubernetes Resource Management
    Persistent Volumes and Finalizers – Guidelines for using finalizers with PersistentVolumes and other resources.
    4. 




  4. Kubernetes GitHub Documentation on Foreground and Background Deletion
    Foreground Deletion Documentation – Explore how Kubernetes handles dependent resource deletion with foreground and background strategies, in relation to finalizers.
    5.