Create garbage collection docs

2021-07-08 21:41:31 +00:00
parent 5288513b58
commit b1573ad314
10 changed files with 726 additions and 284 deletions
@@ -0,0 +1,80 @@
+---
+title: Finalizers
+content_type: concept
+weight: 60
+---
+
+<!-- overview -->
+
+{{<glossary_definition term_id="finalizer" length="long">}}
+
+You can use finalizers to control {{<glossary_tooltip text="garbage collection" term_id="garbage-collection">}}
+of resources by alerting {{<glossary_tooltip text="controllers" term_id="controller">}} to perform specific cleanup tasks before
+deleting the target resource. 
+
+Finalizers don't usually specify the code to execute. Instead, they are
+typically lists of keys on a specific resource similar to annotations.
+Kubernetes specifies some finalizers automatically, but you can also specify
+your own.
+
+## How finalizers work
+
+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: 
+
+  * 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.
+
+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.
+
+A common example of a finalizer is `kubernetes.io/pv-protection`, which prevents
+accidental deletion of `PersistentVolume` objects. When a `PersistentVolume`
+object is in use by a Pod, Kubernetes adds the `pv-protection` finalizer. If you
+try to delete the `PersistentVolume`, it enters a `Terminating` status, but the
+controller can't delete it because the finalizer exists. When the Pod stops
+using the `PersistentVolume`, Kubernetes clears the `pv-protection` finalizer,
+and the controller deletes the volume.
+
+## Owner references, labels, and finalizers {#owners-labels-finalizers}
+
+Like {{<glossary_tooltip text="labels" term_id="label">}}, [owner references](/concepts/overview/working-with-objects/owners-dependents/)
+describe the relationships between objects in Kubernetes, but are used for a
+different purpose. When a
+{{<glossary_tooltip text="controllers" term_id="controller">}} manages objects
+like Pods, it uses labels to track changes to groups of related objects. For
+example, when a {{<glossary_tooltip text="Job" term_id="job">}} creates one or
+more Pods, the Job controller applies labels to those pods and tracks changes to
+any Pods in the cluster with the same label.
+
+The Job controller also adds *owner references* to those Pods, pointing at the
+Job that created the Pods. If you delete the Job while these Pods are running,
+Kubernetes uses the owner references (not labels) to determine which Pods in the
+cluster need cleanup.
+
+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
+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. 
+
+{{<note>}}
+In cases where objects are stuck in a deleting state, try to 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. 
+{{</note>}}
+
+## {{% heading "whatsnext" %}}
+
+* Read [Using Finalizers to Control Deletion](/blog/2021/05/14/using-finalizers-to-control-deletion/)
+  on the Kubernetes blog.
@@ -0,0 +1,71 @@
+---
+title: Owners and Dependents
+content_type: concept
+weight: 60
+---
+
+<!-- overview -->
+
+In Kubernetes, some objects are *owners* of other objects. For example, a
+{{<glossary_tooltip text="ReplicaSet" term_id="replica-set">}} is the owner of a set of Pods. These owned objects are *dependents*
+of their owner. 
+
+Ownership is different from the [labels and selectors](/docs/concepts/overview/working-with-objects/labels/)
+mechanism that some resources also use. For example, consider a Service that 
+creates `EndpointSlice` objects. The Service uses labels to allow the control plane to
+determine which `EndpointSlice` objects are used for that Service. In addition
+to the labels, each `EndpointSlice` that is managed on behalf of a Service has
+an owner reference. Owner references help different parts of Kubernetes avoid
+interfering with objects they don’t control. 
+
+## Owner references in object specifications
+
+Dependent objects have a `metadata.ownerReferences` field that references their
+owner object. A valid owner reference consists of the object name and a UID
+within the same namespace as the dependent object. Kubernetes sets the value of
+this field automatically for objects that are dependents of other objects like
+ReplicaSets, DaemonSets, Deployments, Jobs and CronJobs, and ReplicationControllers.
+You can also configure these relationships manually by changing the value of
+this field. However, you usually don't need to and can allow Kubernetes to
+automatically manage the relationships.
+
+Dependent objects also have an `ownerReferences.blockOwnerDeletion` field that
+takes a boolean value and controls whether specific dependents can block garbage
+collection from deleting their owner object. Kubernetes automatically sets this
+field to `true` if a {{<glossary_tooltip text="controller" term_id="controller">}} 
+(for example, the Deployment controller) sets the value of the
+`metadata.ownerReferences` field. You can also set the value of the
+`blockOwnerDeletion` field manually to control which dependents block garbage
+collection.
+
+A Kubernetes admission controller controls user access to change this field for
+dependent resources, based on the delete permissions of the owner. This control
+prevents unauthorized users from delaying owner object deletion.
+
+## Ownership and finalizers
+
+When you tell Kubernetes to delete a resource, the API server allows the
+managing controller to process any [finalizer rules](/docs/concepts/overview/working-with-objects/finalizers/)
+for the resource. {{<glossary_tooltip text="Finalizers" term_id="finalizer">}}
+prevent accidental deletion of resources your cluster may still need to function
+correctly. For example, if you try to delete a `PersistentVolume` that is still
+in use by a Pod, the deletion does not happen immediately because the
+`PersistentVolume` has the `kubernetes.io/pv-protection` finalizer on it.
+Instead, the volume remains in the `Terminating` status until Kubernetes clears
+the finalizer, which only happens after the `PersistentVolume` is no longer
+bound to a Pod. 
+
+Kubernetes also adds finalizers to an owner resource when you use either
+[foreground or orphan cascading deletion](/docs/concepts/architecture/garbage-collection/#cascading-deletion).
+In foreground deletion, it adds the `foreground` finalizer so that the
+controller must delete dependent resources that also have
+`ownerReferences.blockOwnerDeletion=true` before it deletes the owner. If you
+specify an orphan deletion policy, Kubernetes adds the `orphan` finalizer so
+that the controller ignores dependent resources after it deletes the owner
+object. 
+
+## {{% heading "whatsnext" %}}
+
+* Learn more about [Kubernetes finalizers](/docs/concepts/overview/working-with-objects/finalizers/).
+* Learn about [garbage collection](/docs/concepts/architecture/garbage-collection).
+* Read the API reference for [object metadata](/docs/reference/kubernetes-api/common-definitions/object-meta/#System).