Use an Image Volume With a Pod

FEATURE STATE: Kubernetes v1.31 [alpha] (enabled by default: false)

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:

apiVersion: v1
kind: Pod
metadata:
  name: image-volume
spec:
  containers:
  - name: shell
    command: ["sleep", "infinity"]
    image: debian
    volumeMounts:
    - name: volume
      mountPath: /volume
  volumes:
  - name: volume
    image:
      reference: quay.io/crio/artifact:v1
      pullPolicy: IfNotPresent
  1. Create the pod on your cluster:

    kubectl apply -f https://k8s.io/examples/pods/image-volumes.yaml
    
  2. Attach to the container:

    kubectl attach -it image-volume bash
    
  3. Check the content of a file in the volume:

    cat /volume/dir/file
    

    The output is similar to:

    1
    

    You can also check another file in a different path:

    cat /volume/file
    

    The output is similar to:

    2
    

Further reading

Last modified August 22, 2024 at 6:04 PM PST: Revise step desc in image-volumes (65ce82dd0b)