Garbage Collection - Kubernetes
Garbage Collection - Kubernetes
Garbage Collection
Garbage collection is a collective term for the various mechanisms Kubernetes uses to clean
up cluster resources. This allows the clean up of resources like the following:
Terminated pods
Completed Jobs
Objects without owner references
Unused containers and container images
Dynamically provisioned PersistentVolumes with a StorageClass reclaim policy of Delete
Stale or expired CertificateSigningRequests (CSRs)
Nodes deleted in the following scenarios:
On a cloud when the cluster uses a cloud controller manager
On-premises when the cluster uses an addon similar to a cloud controller manager
Node Lease objects
Ownership is different from the labels and selectors 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.
Note:
Cross-namespace owner references are disallowed by design. Namespaced dependents
can specify cluster-scoped or namespaced owners. A namespaced owner must exist in
the same namespace as the dependent. If it does not, the owner reference is treated as
absent, and the dependent is subject to deletion once all owners are verified absent.
https://kubernetes.io/docs/concepts/architecture/garbage-collection/ 1/4
2/9/23, 10:28 AM Garbage Collection | Kubernetes
Cascading deletion
Kubernetes checks for and deletes objects that no longer have owner references, like the
pods left behind when you delete a ReplicaSet. When you delete an object, you can control
whether Kubernetes deletes the object's dependents automatically, in a process called
cascading deletion. There are two types of cascading deletion, as follows:
You can also control how and when garbage collection deletes resources that have owner
references using Kubernetes finalizers.
The Kubernetes API server sets the object's metadata.deletionTimestamp field to the time
the object was marked for deletion.
The Kubernetes API server also sets the metadata.finalizers field to
foregroundDeletion .
The object remains visible through the Kubernetes API until the deletion process is
complete.
After the owner object enters the deletion in progress state, the controller deletes the
dependents. After deleting all the dependent objects, the controller deletes the owner object.
At this point, the object is no longer visible in the Kubernetes API.
During foreground cascading deletion, the only dependents that block owner deletion are
those that have the ownerReference.blockOwnerDeletion=true field. See Use foreground
cascading deletion to learn more.
Orphaned dependents
When Kubernetes deletes an owner object, the dependents left behind are called orphan
objects. By default, Kubernetes deletes dependent objects. To learn how to override this
behaviour, see Delete owner objects and orphan dependents.
To configure options for unused container and image garbage collection, tune the kubelet
using a configuration file and change the parameters related to garbage collection using the
KubeletConfiguration resource type.
https://kubernetes.io/docs/concepts/architecture/garbage-collection/ 2/4
2/9/23, 10:28 AM Garbage Collection | Kubernetes
HighThresholdPercent
LowThresholdPercent
Disk usage above the configured HighThresholdPercent value triggers garbage collection,
which deletes images in order based on the last time they were used, starting with the oldest
first. The kubelet deletes images until disk usage reaches the LowThresholdPercent value.
MinAge : the minimum age at which the kubelet can garbage collect a container. Disable
by setting to 0 .
MaxPerPodContainer : the maximum number of dead containers each Pod can have.
Disable by setting to less than 0 .
MaxContainers : the maximum number of dead containers the cluster can have. Disable
by setting to less than 0 .
In addition to these variables, the kubelet garbage collects unidentified and deleted
containers, typically starting with the oldest first.
MaxPerPodContainer and MaxContainers may potentially conflict with each other in situations
where retaining the maximum number of containers per Pod ( MaxPerPodContainer ) would go
outside the allowable total of global dead containers ( MaxContainers ). In this situation, the
kubelet adjusts MaxPerPodContainer to address the conflict. A worst-case scenario would be to
downgrade MaxPerPodContainer to 1 and evict the oldest containers. Additionally, containers
owned by pods that have been deleted are removed once they are older than MinAge .
What's next
Learn more about ownership of Kubernetes objects.
Learn more about Kubernetes finalizers.
Learn about the TTL controller (beta) that cleans up finished Jobs.
Feedback
Was this page helpful?
Yes No
https://kubernetes.io/docs/concepts/architecture/garbage-collection/ 3/4
2/9/23, 10:28 AM Garbage Collection | Kubernetes
Last modified January 18, 2023 at 10:47 PM PST: Update garbage-collection.md (486815a6d6)
https://kubernetes.io/docs/concepts/architecture/garbage-collection/ 4/4