Use an Image Volume With a Pod

FEATURE STATE: Kubernetes v1.31 [alpha]

This page shows how to configure a pod using image volumes. This allows you to mount content from OCI registries inside containers.

Before you begin

You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. It is recommended to run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:

Your Kubernetes server must be version v1.31. To check the version, enter kubectl version.

  • The container runtime needs to support the image volumes feature
  • You need to exec commands in the host
  • You need to be able to exec into pods
  • You need to enable the ImageVolume feature gate

Run a Pod that uses an image volume

An image volume for a pod is enabled by setting the volumes.[*].image field of .spec to a valid reference and consuming it in the volumeMounts of the container. For example:

  1. pods/image-volumes.yaml
  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4.   name: image-volume
  5. spec:
  6.   containers:
  7.   - name: shell
  8.     command: ["sleep", "infinity"]
  9.     image: debian
  10.     volumeMounts:
  11.     - name: volume
  12.       mountPath: /volume
  13.   volumes:
  14.   - name: volume
  15.     image:
  16.       reference: quay.io/crio/artifact:v1
  17.       pullPolicy: IfNotPresent

  1. Create the pod on your cluster:

    1. kubectl apply -f https://k8s.io/examples/pods/image-volumes.yaml

  2. Attach to the container:

    1. kubectl attach -it image-volume bash

  3. Check the content of a file in the volume:

    1. cat /volume/dir/file

    The output is similar to:

    1. 1

    You can also check another file in a different path:

    1. cat /volume/file

    The output is similar to:

    1. 2

Further reading