8.7 Kubernetes Container Image Usage

Kubernetes Container Image Usage is the manifest-authoring practice of specifying and configuring which container image a given container runs, covering how image references are chosen and tagged, how private registry access is granted through imagePullSecrets, and how pull policy is selected to balance image freshness against startup latency and registry load.

Choosing an Image Reference

Registry, Repository, and Tag Components

An image reference such as registry.example.com/team/app:1.4.2 combines a registry hostname, a repository path, and a tag, with the registry portion optionally omitted to fall back to the container runtime's configured default registry, though explicitly specifying a registry avoids ambiguity across different clusters that might configure different defaults.

Tag Versus Digest References

A tag-based reference, such as :1.4.2, is mutable and can be repointed to different underlying image content by a later push to the same tag, while a digest-based reference, such as @sha256:abc123..., is immutable and always resolves to the exact same content, a distinction manifest authors weigh when deciding how much reproducibility a given deployment genuinely requires.

Tagging Strategy Considerations

Avoiding the latest Tag in Production

Using latest, or any similarly floating tag, means the actual code a manifest deploys can silently change between deployments without any corresponding manifest change, which undermines the reproducibility that declarative, version-controlled manifests are meant to provide, making explicit version tags or digests the generally preferred choice for production workloads.

Semantic Versioning Versus Build-Derived Tags

Some teams tag images with human-readable semantic versions, such as 1.4.2, while others tag with build-derived identifiers, such as a Git commit short hash or a CI build number, each approach offering different tradeoffs between human readability and precise, unambiguous traceability back to the exact source that produced the image.

Configuring Private Registry Access

The imagePullSecrets Field

A Pod's spec.imagePullSecrets references one or more Secret objects of type kubernetes.io/dockerconfigjson, containing registry credentials the kubelet passes to the container runtime when pulling images from a registry requiring authentication.

Attaching Pull Secrets via ServiceAccount

Rather than specifying imagePullSecrets on every individual Pod manifest, a ServiceAccount can carry its own imagePullSecrets, automatically applied to every Pod using that ServiceAccount, centralizing private registry credential configuration rather than duplicating it across many separate Pod specs.

Credential Provider Plugins in Cloud Environments

Some managed Kubernetes environments configure the kubelet with dynamic credential provider plugins that automatically obtain short-lived registry credentials for a cloud provider's own container registry, removing the need for manifests to reference any static imagePullSecrets at all when using that provider's registry.

Selecting an Appropriate imagePullPolicy

Matching Policy to Tagging Strategy

imagePullPolicy: IfNotPresent suits immutable, version-pinned tags or digests, since there is no benefit to re-pulling an image the node already has a correct, unchanging copy of, while imagePullPolicy: Always suits floating tags like latest, where the runtime must re-verify it has the current content on every container start.

Startup Latency Tradeoffs

Setting imagePullPolicy: Always on every container introduces a network round trip to the registry on every single Pod start, even when the image content has not changed, a latency cost worth weighing against the freshness guarantee it provides, particularly for workloads that restart or scale frequently.

Multi-Architecture Image Considerations

Manifest Lists for Heterogeneous Clusters

In clusters containing nodes of different CPU architectures, such as a mix of amd64 and arm64 nodes, referencing a multi-architecture manifest list image reference allows the same manifest to correctly resolve to the appropriate architecture-specific image variant on whichever node type a Pod happens to be scheduled onto, without needing separate manifests per architecture.

Practical Image Reference Hygiene

Keeping Image References Auditable

Because image references directly determine what code actually runs, keeping them explicit, version-pinned, and consistent across related manifests within an application makes it straightforward for anyone reviewing the manifest to understand exactly what will be deployed, reinforcing the broader authoring discipline of avoiding hidden or ambiguous configuration.