Kubernetes Image Runtime Handling

Kubernetes Image Runtime Handling is the set of responsibilities the container runtime and its ImageService fulfill in locating, retrieving, storing, and managing the container images that back every container a node runs, operating as a distinct concern from container lifecycle execution even though both are driven by the kubelet through the Container Runtime Interface. Because a container cannot start without its image being present on the node in a usable form, image handling sits directly on the critical path of Pod startup, and its behavior around caching, pulling, authentication, and garbage collection has a direct effect on Pod startup latency, node disk pressure, and registry load across a cluster.

The ImageService Within CRI

Separation from RuntimeService

The Container Runtime Interface splits responsibilities into a RuntimeService, which manages Pods and containers, and an ImageService, which manages images independently of any particular container. This separation exists because image lifecycle is not naturally tied to a single container's lifecycle: an image may be pulled once and reused by many containers across many Pods, and it may need to be removed for disk pressure reasons even while unrelated to any specific container event.

Core ImageService Methods

The ImageService exposes methods including PullImage, ListImages, ImageStatus, and RemoveImage, all of which the kubelet invokes as needed rather than the ImageService acting independently; the kubelet remains the orchestrator that decides when a pull, listing, or removal should occur.

The Image Pull Path

imagePullPolicy Evaluation

Before pulling, the kubelet evaluates the container's imagePullPolicy — Always, IfNotPresent, or Never — against whether a matching image already exists in local storage as reported by ImageStatus, and only proceeds to invoke PullImage when the policy and local state together require it, which is what allows most container restarts to avoid a network round trip entirely.

Credential Resolution

When a pull is required and the target registry requires authentication, the kubelet resolves credentials from multiple possible sources — imagePullSecrets referenced in the Pod spec, secrets attached to the Pod's service account, or node-level credential providers configured through the kubelet's credential provider plugin mechanism — and passes the resolved authentication material to the runtime as part of the PullImage request.

Pull Serialization and Concurrency

The kubelet limits how many image pulls can occur in parallel on a node through configuration such as serializeImagePulls and maxParallelImagePulls, since unconstrained concurrent pulls can saturate a node's network bandwidth or overwhelm a registry, particularly during coordinated rollouts that start many Pods referencing the same image across the cluster simultaneously.

Local Image Storage

Layered Image Storage

Runtimes store images using content-addressable, layered storage, where each layer is stored once and shared across every image that references it; this is what allows a node to hold many images built from a common base without duplicating that base layer's storage cost for each one.

Image Status and Digest Pinning

ImageStatus reports details such as the image's ID, size, and the repo digests associated with it, and the kubelet can use digest information to pin exactly which content it expects to run, which matters for reproducibility since a mutable tag such as latest can point to different content over time even though the tag string itself does not change.

Garbage Collection of Images

Disk-Pressure-Driven Reclamation

The kubelet's image garbage collector monitors disk usage on the node and, when usage crosses a configured high threshold, invokes RemoveImage against unused images — those not currently referenced by any running or recently used container — continuing removal until usage falls back below a configured low threshold.

Age and Reference Tracking

To decide which images are eligible for removal, the runtime and kubelet track when an image was last used, and images that have not backed a running container recently are prioritized for garbage collection ahead of images in active use, reducing the risk that a frequently used image is evicted only to require an immediate re-pull.

Failure Modes in Image Handling

ImagePullBackOff

When a pull fails — due to an invalid reference, missing credentials, network unavailability, or registry-side errors — the kubelet does not retry immediately and indefinitely; it applies an exponential backoff and surfaces the failure through the container's status as ImagePullBackOff, along with an event describing the underlying error, which is typically the first place operators look when a Pod is stuck outside of a Running state.

Registry Rate Limiting

Because many nodes may pull the same image concurrently, particularly from public registries, image runtime handling is a common point where registry-side rate limiting manifests operationally, which is one of the reasons clusters commonly deploy pull-through caching registries or mirror configurations local to the cluster's network.