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 at or later than 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:

pods/image-volumes.yaml

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

Create the pod on your cluster:

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

Attach to the container:
```
kubectl attach -it image-volume bash
```
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
```

Use an Image Volume With a Pod

Before you begin

Run a Pod that uses an image volume

Further reading

Feedback