Wiki · Concept · Last reviewed June 25, 2026

Kubernetes Image Volumes

Kubernetes Image Volumes mount content from OCI registries into containers as Pod volumes.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, OCI artifacts, model weights, supply chain, AI infrastructure

Definition

Kubernetes Image Volumes are a Pod volume type that mount content from an OCI registry into a container. Kubernetes documentation marks the feature as stable in v1.36 and enabled by default. The storage documentation defines an image volume source as an OCI object, either a container image or artifact, available on the kubelet host machine.

The practical meaning is that a workload can receive files through the same distribution ecosystem used for container images, without baking those files into the application image. That makes the feature especially relevant to AI infrastructure, where model weights, tokenizer files, policy bundles, malware signatures, evaluation fixtures, and agent tools may need their own versioning and review path.

How It Works

A Pod defines an image volume with .spec.volumes[*].image, usually including a reference and optional pullPolicy, then mounts it through .spec.containers[*].volumeMounts. The task guide shows this pattern with a volume whose image.reference points to an OCI object and whose container mounts it at a filesystem path.

The kubelet resolves the reference at Pod startup. Kubernetes documents the same three pull-policy values used by ordinary images: Always, Never, and IfNotPresent. If resolving or pulling the referenced object fails, the Pod can fail or containers can be blocked from starting, with failure information reported through Pod reason, message, and normal volume backoff.

The mounted object is read-only. The available object types depend on the container runtime implementation, but the minimum supported set must include valid types supported by the container image field. Kubernetes v1.33 added support for subPath and subPathExpr on image volumes, allowing a container to mount a specific subdirectory rather than the whole object.

Agent Context

Agent and model platforms often mix fast-moving runtimes with slower-moving artifacts. A serving image might contain the server, accelerator libraries, health checks, and observability hooks, while the model weights change on a different cadence. An agent tool image might be security-reviewed once, while its rules, fixtures, or templates change weekly. Image Volumes give those payloads a native Kubernetes attachment point.

The feature also reduces the pressure to build large, combined images. The Kubernetes v1.31 feature blog described AI and ML users mounting large language model weights or machine-learning model weights beside a model server, separating model content from the executables that process it. That separation is useful only if the artifact path is governed as carefully as the container path.

Governance Use

A governed Image Volume record should capture the workload, namespace, Pod template owner, OCI reference, digest if available, pull policy, registry, service account, image pull secrets, admission decision, signature or attestation checks, vulnerability status, artifact owner, review ticket, and rollback plan. Treat the mounted artifact as deployable code or deployable model state, not as harmless data.

Admission policy can require pinned references, approved registries, signature verification, SBOM or provenance evidence, and explicit labels for model, dataset, or tool artifacts. Observability should preserve pull failures, mount failures, Pod startup latency, and changes to artifact references between releases. The failure mode is not only downtime; it is also silent artifact drift.

Limits

Image Volumes are not persistent storage, mutable scratch space, or a replacement for access governance. They are resolved when the Pod starts and can be re-resolved when the Pod is deleted and recreated. That means a tag that moves can change what a recreated Pod sees unless policy pins or verifies the artifact.

They also do not remove the need for runtime support, registry authentication, supply-chain scanning, NetworkPolicy, resource planning, and incident review. A compromised registry, permissive pull secret, or mutable tag can turn a clean-looking Pod spec into an ambiguous deployment record.

Source Discipline

Claims about the API surface, pull policy, read-only behavior, subPath support, and failure behavior should cite Kubernetes storage and task documentation. Claims about feature history should cite the Kubernetes release blogs for v1.31 and v1.33. Claims about design intent should cite KEP-4639 in the Kubernetes enhancements repository.

Spiralist Reading

Spiralism reads Image Volumes as a reminder that the model is not only the server process.

The artifact mounted beside the container can steer what the system knows, says, detects, or refuses. If it arrives through the registry, it belongs in the record.

Sources

Return to Wiki