diff --git a/content/en/docs/concepts/overview/working-with-objects/finalizers.md b/content/en/docs/concepts/overview/working-with-objects/finalizers.md index fdec67b220..9241ae7e2a 100644 --- a/content/en/docs/concepts/overview/working-with-objects/finalizers.md +++ b/content/en/docs/concepts/overview/working-with-objects/finalizers.md @@ -21,18 +21,21 @@ your own. When you create a resource using a manifest file, you can specify finalizers in the `metadata.finalizers` field. When you attempt to delete the resource, the -controller that manages it notices the values in the `finalizers` field and does -the following: +API server handling the delete request notices the values in the `finalizers` field +and does the following: * Modifies the object to add a `metadata.deletionTimestamp` field with the time you started the deletion. - * Marks the object as read-only until its `metadata.finalizers` field is empty. + * Prevents the object from being removed until its `metadata.finalizers` field is empty. + * Returns a `202` status code (HTTP "Accepted") +The controller managing that finalizer notices the update to the object setting the +`metadata.deletionTimestamp`, indicating deletion of the object has been requested. The controller then attempts to satisfy the requirements of the finalizers specified for that resource. Each time a finalizer condition is satisfied, the controller removes that key from the resource's `finalizers` field. When the -field is empty, garbage collection continues. You can also use finalizers to -prevent deletion of unmanaged resources. +`finalizers` field is emptied, an object with a `deletionTimestamp` field set +is automatically deleted. You can also use finalizers to prevent deletion of unmanaged resources. A common example of a finalizer is `kubernetes.io/pv-protection`, which prevents accidental deletion of `PersistentVolume` objects. When a `PersistentVolume` @@ -63,16 +66,18 @@ Kubernetes also processes finalizers when it identifies owner references on a resource targeted for deletion. In some situations, finalizers can block the deletion of dependent objects, -which can cause the targeted owner object to remain in a read-only state for +which can cause the targeted owner object to remain for longer than expected without being fully deleted. In these situations, you should check finalizers and owner references on the target owner and dependent objects to troubleshoot the cause. {{}} -In cases where objects are stuck in a deleting state, try to avoid manually +In cases where objects are stuck in a deleting state, avoid manually removing finalizers to allow deletion to continue. Finalizers are usually added to resources for a reason, so forcefully removing them can lead to issues in -your cluster. +your cluster. This should only be done when the purpose of the finalizer is +understood and is accomplished in another way (for example, manually cleaning +up some dependent object). {{}} ## {{% heading "whatsnext" %}}