docs.yml

site/content/en/main/user-guide/actions/_index.md

@@ -10,7 +10,7 @@ An action is a discrete set of behaviors defined in a single function that acts
 
 For example, an action could be responsible for adding a specific label to a Kubernetes resource, or for modifying a specific field in a resource's metadata. Actions can be grouped together within a Capability to provide a more comprehensive set of operations that can be performed on Kubernetes resources.
 
-Actions are `Mutate()`, `Validate()`, `Watch()`, or `Reconcile()`. Both Mutate and Validate actions run during the admission controller lifecycle, while Watch and Reconcile actions run in a separate controller that tracks changes to resources, including existing resources.
+Actions are `Mutate()`, `Validate()`, `Watch()`, `Reconcile()`, and `Finalize()`. Both Mutate and Validate actions run during the admission controller lifecycle, while Watch and Reconcile actions run in a separate controller that tracks changes to resources, including existing resource; the Finalize action spans both the admission & afterward.
 
 Let's look at some example actions that are included in the `HelloPepr` capability that is created for you when you [`npx pepr init`](./pepr-cli#pepr-init):
 

site/content/en/main/user-guide/actions/finalize.md

@@ -0,0 +1,15 @@
+---
+title: Finalize
+weight: 50
+---
+
+
+A specialized combination of Pepr's [Mutate](../mutate/) & [Watch](../watch/) functionalities that allow a module author to run logic while Kubernetes is [Finalizing](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) a resource (i.e. cleaning up related resources _after_ a deleteion request has been accepted).
+
+This method will:
+
+1. Inject a finalizer into the `metadata.finalizers` field of the requested resource during the mutation phase of the admission.
+
+1. Watch appropriate resource lifecycle events & invoke the given callback.
+
+1. Remove the injected finalizer from the `metadata.finalizers` field of the requested resource.