Skip to content

Commit d078b42

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #28870 from shannonxtreme/gc-docs
Create garbage collection docs
2 parents 85868d8 + b1573ad commit d078b42

File tree

10 files changed

+726
-284
lines changed

10 files changed

+726
-284
lines changed

‎content/en/docs/concepts/architecture/garbage-collection.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
title: Garbage Collection
3+
content_type: concept
4+
weight: 50
5+
---
6+
7+
<!-- overview -->
8+
{{<glossary_definition term_id="garbage-collection" length="short">}} This
9+
allows the clean up of resources like the following:
10+
11+
* [Failed pods](/docs/concepts/workloads/pods/pod-lifecycle/#pod-garbage-collection)
12+
* [Completed Jobs](/docs/concepts/workloads/controllers/ttlafterfinished/)
13+
* [Objects without owner references](#owners-dependents)
14+
* [Unused containers and container images](#containers-images)
15+
* [Dynamically provisioned PersistentVolumes with a StorageClass reclaim policy of Delete](/docs/concepts/storage/persistent-volumes/#delete)
16+
* [Stale or expired CertificateSigningRequests (CSRs)](/reference/access-authn-authz/certificate-signing-requests/#request-signing-process)
17+
* {{<glossary_tooltip text="Nodes" term_id="node">}} deleted in the following scenarios:
18+
* On a cloud when the cluster uses a [cloud controller manager](/docs/concepts/architecture/cloud-controller/)
19+
* On-premises when the cluster uses an addon similar to a cloud controller
20+
manager
21+
* [Node Lease objects](/docs/concepts/architecture/nodes/#heartbeats)
22+
23+
## Owners and dependents {#owners-dependents}
24+
25+
Many objects in Kubernetes link to each other through [*owner references*](/docs/concepts/overview/working-with-objects/owners-dependents/).
26+
Owner references tell the control plane which objects are dependent on others.
27+
Kubernetes uses owner references to give the control plane, and other API
28+
clients, the opportunity to clean up related resources before deleting an
29+
object. In most cases, Kubernetes manages owner references automatically.
30+
31+
Ownership is different from the [labels and selectors](/docs/concepts/overview/working-with-objects/labels/)
32+
mechanism that some resources also use. For example, consider a
33+
{{<glossary_tooltip text="Service" term_id="service">}} that creates
34+
`EndpointSlice` objects. The Service uses *labels* to allow the control plane to
35+
determine which `EndpointSlice` objects are used for that Service. In addition
36+
to the labels, each `EndpointSlice` that is managed on behalf of a Service has
37+
an owner reference. Owner references help different parts of Kubernetes avoid
38+
interfering with objects they don’t control.
39+
40+
## Cascading deletion {#cascading-deletion}
41+
42+
Kubernetes checks for and deletes objects that no longer have owner
43+
references, like the pods left behind when you delete a ReplicaSet. When you
44+
delete an object, you can control whether Kubernetes deletes the object's
45+
dependents automatically, in a process called *cascading deletion*. There are
46+
two types of cascading deletion, as follows:
47+
48+
* Foreground cascading deletion
49+
* Background cascading deletion
50+
51+
You can also control how and when garbage collection deletes resources that have
52+
owner references using Kubernetes {{<glossary_tooltip text="finalizers" term_id="finalizer">}}.
53+
54+
### Foreground cascading deletion {#foreground-deletion}
55+
56+
In foreground cascading deletion, the owner object you're deleting first enters
57+
a *deletion in progress* state. In this state, the following happens to the
58+
owner object:
59+
60+
* The Kubernetes API server sets the object's `metadata.deletionTimestamp`
61+
field to the time the object was marked for deletion.
62+
* The Kubernetes API server also sets the `metadata.finalizers` field to
63+
`foregroundDeletion`.
64+
* The object remains visible through the Kubernetes API until the deletion
65+
process is complete.
66+
67+
After the owner object enters the deletion in progress state, the controller
68+
deletes the dependents. After deleting all the dependent objects, the controller
69+
deletes the owner object. At this point, the object is no longer visible in the
70+
Kubernetes API.
71+
72+
During foreground cascading deletion, the only dependents that block owner
73+
deletion are those that have the `ownerReference.blockOwnerDeletion=true` field.
74+
See [Use foreground cascading deletion](/docs/tasks/administer-cluster/use-cascading-deletion/#use-foreground-cascading-deletion)
75+
to learn more.
76+
77+
### Background cascading deletion {#background-deletion}
78+
79+
In background cascading deletion, the Kubernetes API server deletes the owner
80+
object immediately and the controller cleans up the dependent objects in
81+
the background. By default, Kubernetes uses background cascading deletion unless
82+
you manually use foreground deletion or choose to orphan the dependent objects.
83+
84+
See [Use background cascading deletion](/docs/tasks/administer-cluster/use-cascading-deletion/#use-background-cascading-deletion)
85+
to learn more.
86+
87+
### Orphaned dependents
88+
89+
When Kubernetes deletes an owner object, the dependents left behind are called
90+
*orphan* objects. By default, Kubernetes deletes dependent objects. To learn how
91+
to override this behaviour, see [Delete owner objects and orphan dependents](/docs/tasks/administer-cluster/use-cascading-deletion/#set-orphan-deletion-policy).
92+
93+
## Garbage collection of unused containers and images {#containers-images}
94+
95+
The {{<glossary_tooltip text="kubelet" term_id="kubelet">}} performs garbage
96+
collection on unused images every five minutes and on unused containers every
97+
minute. You should avoid using external garbage collection tools, as these can
98+
break the kubelet behavior and remove containers that should exist.
99+
100+
To configure options for unused container and image garbage collection, tune the
101+
kubelet using a [configuration file](/docs/tasks/administer-cluster/kubelet-config-file/)
102+
and change the parameters related to garbage collection using the
103+
[`KubeletConfiguration`](/docs/reference/config-api/kubelet-config.v1beta1/#kubelet-config-k8s-io-v1beta1-KubeletConfiguration)
104+
resource type.
105+
106+
### Container image lifecycle
107+
108+
Kubernetes manages the lifecycle of all images through its *image manager*,
109+
which is part of the kubelet, with the cooperation of cadvisor. The kubelet
110+
considers the following disk usage limits when making garbage collection
111+
decisions:
112+
113+
* `HighThresholdPercent`
114+
* `LowThresholdPercent`
115+
116+
Disk usage above the configured `HighThresholdPercent` value triggers garbage
117+
collection, which deletes images in order based on the last time they were used,
118+
starting with the oldest first. The kubelet deletes images
119+
until disk usage reaches the `LowThresholdPercent` value.
120+
121+
### Container image garbage collection {#container-image-garbage-collection}
122+
123+
The kubelet garbage collects unused containers based on the following variables,
124+
which you can define:
125+
126+
* `MinAge`: the minimum age at which the kubelet can garbage collect a
127+
container. Disable by setting to `0`.
128+
* `MaxPerPodContainer`: the maximum number of dead containers each Pod pair
129+
can have. Disable by setting to less than `0`.
130+
* `MaxContainers`: the maximum number of dead containers the cluster can have.
131+
Disable by setting to less than `0`.
132+
133+
In addition to these variables, the kubelet garbage collects unidentified and
134+
deleted containers, typically starting with the oldest first.
135+
136+
`MaxPerPodContainer` and `MaxContainer` may potentially conflict with each other
137+
in situations where retaining the maximum number of containers per Pod
138+
(`MaxPerPodContainer`) would go outside the allowable total of global dead
139+
containers (`MaxContainers`). In this situation, the kubelet adjusts
140+
`MaxPodPerContainer` to address the conflict. A worst-case scenario would be to
141+
downgrade `MaxPerPodContainer` to `1` and evict the oldest containers.
142+
Additionally, containers owned by pods that have been deleted are removed once
143+
they are older than `MinAge`.
144+
145+
{{<note>}}
146+
The kubelet only garbage collects the containers it manages.
147+
{{</note>}}
148+
149+
## Configuring garbage collection {#configuring-gc}
150+
151+
You can tune garbage collection of resources by configuring options specific to
152+
the controllers managing those resources. The following pages show you how to
153+
configure garbage collection:
154+
155+
* [Configuring cascading deletion of Kubernetes objects](/docs/tasks/administer-cluster/use-cascading-deletion/)
156+
* [Configuring cleanup of finished Jobs](/docs/concepts/workloads/controllers/ttlafterfinished/)
157+
158+
<!-- * [Configuring unused container and image garbage collection](/docs/tasks/administer-cluster/reconfigure-kubelet/) -->
159+
160+
## {{% heading "whatsnext" %}}
161+
162+
* Learn more about [ownership of Kubernetes objects](/docs/concepts/overview/working-with-objects/owners-dependents/).
163+
* Learn more about Kubernetes [finalizers](/docs/concepts/overview/working-with-objects/finalizers/).
164+
* Learn about the [TTL controller](/docs/concepts/workloads/controllers/ttlafterfinished/) (beta) that cleans up finished Jobs.

‎content/en/docs/concepts/cluster-administration/kubelet-garbage-collection.md

Lines changed: 0 additions & 98 deletions
This file was deleted.

‎content/en/docs/concepts/containers/images.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -330,4 +330,5 @@ Kubelet will merge any `imagePullSecrets` into a single virtual `.docker/config.
330330

331331
## {{% heading "whatsnext" %}}
332332

333-
* Read the [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/master/manifest.md)
333+
* Read the [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/master/manifest.md).
334+
* Learn about [container image garbage collection](/docs/concepts/architecture/garbage-collection/#container-image-garbage-collection).

‎content/en/docs/concepts/overview/working-with-objects/finalizers.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Finalizers
3+
content_type: concept
4+
weight: 60
5+
---
6+
7+
<!-- overview -->
8+
9+
{{<glossary_definition term_id="finalizer" length="long">}}
10+
11+
You can use finalizers to control {{<glossary_tooltip text="garbage collection" term_id="garbage-collection">}}
12+
of resources by alerting {{<glossary_tooltip text="controllers" term_id="controller">}} to perform specific cleanup tasks before
13+
deleting the target resource.
14+
15+
Finalizers don't usually specify the code to execute. Instead, they are
16+
typically lists of keys on a specific resource similar to annotations.
17+
Kubernetes specifies some finalizers automatically, but you can also specify
18+
your own.
19+
20+
## How finalizers work
21+
22+
When you create a resource using a manifest file, you can specify finalizers in
23+
the `metadata.finalizers` field. When you attempt to delete the resource, the
24+
controller that manages it notices the values in the `finalizers` field and does
25+
the following:
26+
27+
* Modifies the object to add a `metadata.deletionTimestamp` field with the
28+
time you started the deletion.
29+
* Marks the object as read-only until its `metadata.finalizers` field is empty.
30+
31+
The controller then attempts to satisfy the requirements of the finalizers
32+
specified for that resource. Each time a finalizer condition is satisfied, the
33+
controller removes that key from the resource's `finalizers` field. When the
34+
field is empty, garbage collection continues. You can also use finalizers to
35+
prevent deletion of unmanaged resources.
36+
37+
A common example of a finalizer is `kubernetes.io/pv-protection`, which prevents
38+
accidental deletion of `PersistentVolume` objects. When a `PersistentVolume`
39+
object is in use by a Pod, Kubernetes adds the `pv-protection` finalizer. If you
40+
try to delete the `PersistentVolume`, it enters a `Terminating` status, but the
41+
controller can't delete it because the finalizer exists. When the Pod stops
42+
using the `PersistentVolume`, Kubernetes clears the `pv-protection` finalizer,
43+
and the controller deletes the volume.
44+
45+
## Owner references, labels, and finalizers {#owners-labels-finalizers}
46+
47+
Like {{<glossary_tooltip text="labels" term_id="label">}}, [owner references](/concepts/overview/working-with-objects/owners-dependents/)
48+
describe the relationships between objects in Kubernetes, but are used for a
49+
different purpose. When a
50+
{{<glossary_tooltip text="controllers" term_id="controller">}} manages objects
51+
like Pods, it uses labels to track changes to groups of related objects. For
52+
example, when a {{<glossary_tooltip text="Job" term_id="job">}} creates one or
53+
more Pods, the Job controller applies labels to those pods and tracks changes to
54+
any Pods in the cluster with the same label.
55+
56+
The Job controller also adds *owner references* to those Pods, pointing at the
57+
Job that created the Pods. If you delete the Job while these Pods are running,
58+
Kubernetes uses the owner references (not labels) to determine which Pods in the
59+
cluster need cleanup.
60+
61+
Kubernetes also processes finalizers when it identifies owner references on a
62+
resource targeted for deletion.
63+
64+
In some situations, finalizers can block the deletion of dependent objects,
65+
which can cause the targeted owner object to remain in a read-only state for
66+
longer than expected without being fully deleted. In these situations, you
67+
should check finalizers and owner references on the target owner and dependent
68+
objects to troubleshoot the cause.
69+
70+
{{<note>}}
71+
In cases where objects are stuck in a deleting state, try to avoid manually
72+
removing finalizers to allow deletion to continue. Finalizers are usually added
73+
to resources for a reason, so forcefully removing them can lead to issues in
74+
your cluster.
75+
{{</note>}}
76+
77+
## {{% heading "whatsnext" %}}
78+
79+
* Read [Using Finalizers to Control Deletion](/blog/2021/05/14/using-finalizers-to-control-deletion/)
80+
on the Kubernetes blog.

0 commit comments

Comments
 (0)