How Kubernetes Manages Container Images on Nodes

This article explains how Kubernetes manages container images on a node.

Pull Image

The Kubelet communicates with the CRI component (e.g., containerd or cri‑o ) via gRPC. When a new Pod is created, the Kubelet calls the ImageService.PullImage method; the CRI component then downloads the image to the node. The organization and lifecycle of the image on disk are handled by the CRI component, and the exact behavior varies between different CRI implementations.

For containerd , the default configuration file is /etc/containerd/config.toml , where the root=/var/lib/containerd/ setting defines the storage root directory.

For cri‑o , the storage configuration resides in /etc/containers/storage.conf . The root=/var/lib/containers/storage option sets the storage path, and an additional imagestore option can specify a separate image storage location.

Image GC

The Kubelet uses a garbage‑collection (GC) strategy to delete unused images. Relevant configuration options include:

imageMinimumGCAge : default 2 minutes, the minimum time an image must exist before it can be removed.

imageMaximumGCAge : default 0 (disabled), the maximum allowed age of an image; if an image has not been used for longer than this value, it will be removed (feature introduced in v1.30).

imageGCHighThresholdPercent : default 85, the disk usage percentage at which image GC is triggered.

imageGCLowThresholdPercent : default 80, the disk usage percentage at which GC stops deleting images.

The Kubelet runs the GC loop every 5 minutes, performing the following steps:

imagesInEvictionOrder : the Kubelet sends three gRPC requests ( ImageService.ListImages , RuntimeService.ListPodSandbox , RuntimeService.ListContainers ) to the CRI to obtain usage information for all images on the node and sorts them by last‑used time.

freeOldImages : if the time since an image was last used exceeds imageMaximumGCAge , the Kubelet calls ImageService.RemoveImage to delete the image.

ImageFsStats : the Kubelet requests ImageService.ImageFsInfo (via cri‑o’s cAdvisor integration) to get current disk usage statistics.

freeSpace : when disk usage reaches or exceeds imageGCHighThresholdPercent , images are deleted one by one starting with the oldest until usage falls below imageGCLowThresholdPercent , at which point deletion stops.

Summary

On a node, images are managed by CRI components such as containerd and cri‑o . The Kubelet triggers image garbage collection every 5 minutes. If imageMaximumGCAge is set, images older than this age are removed regardless of disk usage; otherwise, deletion follows the high‑ and low‑threshold watermarks defined by imageGCHighThresholdPercent and imageGCLowThresholdPercent . The actual removal is performed by the CRI component, while the Kubelet only initiates the gRPC calls.

References:

https://kubernetes.io/docs/concepts/architecture/garbage-collection

https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/

https://github.com/containerd/containerd/blob/main/docs/ops.md

https://github.com/cri-o/cri-o/blob/main/docs/crio.conf.5.md

https://github.com/kubernetes/kubernetes/blob/master/pkg/kubelet/images/image_gc_manager.go