Add ImageVolume documentation

Add a basic task how to use image volumes in pods.

Signed-off-by: Sascha Grunert <[email protected]>

Author: saschagrunert

content/en/docs/concepts/storage/volumes.md

@@ -543,6 +543,68 @@ spec:
       type: FileOrCreate
 ```
 
+### image
+
+{{< feature-state feature_gate_name="ImageVolume" >}}
+
+An `image` volume source represents an OCI object (a container image or
+artifact) pulled and mounted on the kubelet's host machine.
+
+One example to use the `image` volume source is:
+
+{{% code_sample file="pods/image-volumes.yaml" %}}
+
+The volume is resolved at pod startup depending on which `pullPolicy` value is
+provided:
+
+- `Always`: the kubelet always attempts to pull the reference. Container
+  creation will fail if the pull fails.
+- `Never`: the kubelet never pulls the reference and only uses a local image or
+  artifact. Container creation will fail if the reference isn't present.
+- `IfNotPresent`: the kubelet pulls if the reference isn't already present on
+  disk. Container creation will fail if the reference isn't present and the pull
+  fails.
+
+The volume gets re-resolved if the pod gets deleted and recreated, which means
+that new remote content will become available on pod recreation. A failure to
+resolve or pull the image during pod startup will block containers from starting
+and may add significant latency. Failures will be retried using normal volume
+backoff and will be reported on the pod reason and message.
+
+The types of objects that may be mounted by this volume are defined by the
+container runtime implementation on a host machine and at minimum must include
+all valid types supported by the container image field. The OCI object gets
+mounted in a single directory (`spec.containers[*].volumeMounts.mountPath`) by
+merging the manifest layers in the same way as for container images. The volume
+will be mounted read-only (`ro`) and non-executable files (`noexec`).
+
+Beside that:
+- Sub path mounts for containers are not supported
+  (`spec.containers[*].volumeMounts.subpath`).
+- The field `spec.securityContext.fsGroupChangePolicy` has no effect on this
+  volume type.
+- The [`AlwaysPullImages` Admission Controller](/docs/reference/access-authn-authz/admission-controllers/#alwayspullimages)
+  does also work for this volume source like for container images.
+
+The following fields are available for the `image` type:
+
+- `reference`: Image or artifact reference to be used.
+    Behaves in the same way as `pod.spec.containers[*].image`.
+    Pull secrets will be assembled in the same way as for the container image by
+    looking up node credentials, service account image pull secrets, and pod
+    spec image pull secrets. This field is optional to allow higher level config
+    management to default or override container images in workload controllers
+    like Deployments and StatefulSets.
+
+    [More info about container images](/docs/concepts/containers/images)
+
+-  `pullPolicy`: Policy for pulling OCI objects. Possible values are: `Always`,
+   `Never` or `IfNotPresent`. Defaults to `Always` if `:latest` tag is
+   specified, or `IfNotPresent` otherwise.
+
+See the [_Use an Image Volume With a Pod_](/docs/tasks/configure-pod-container/image-volumes)
+example for more details on how to use the volume source.
+
 ### iscsi
 
 An `iscsi` volume allows an existing iSCSI (SCSI over IP) volume to be mounted

content/en/docs/reference/command-line-tools-reference/feature-gates/image-volume.md

@@ -0,0 +1,13 @@
+---
+title: ImageVolume
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.31"
+---
+Enable the `ImageVolumeSource` API to use `pod.spec.volumes[*].image`.

content/en/docs/tasks/configure-pod-container/image-volumes.md

@@ -0,0 +1,75 @@
+---
+title: Use an Image Volume With a Pod
+reviewers:
+content_type: task
+weight: 210
+min-kubernetes-server-version: v1.31
+---
+
+<!-- overview -->
+
+{{< feature-state feature_gate_name="ImageVolume" >}}
+
+This page shows how to configure a pod using image volumes. This allows you to
+mount content from OCI registries inside containers.
+
+## {{% heading "prerequisites" %}}
+
+{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
+
+{{% thirdparty-content single="true" %}}
+
+- The node OS needs to be Linux
+- 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](/docs/reference/command-line-tools-reference/feature-gates/)
+
+<!-- steps -->
+
+## Run a Pod that uses an image volume {#create-pod}
+
+An image volume for a pod is enabled setting the `volumes.[*].image` field of `.spec`
+to a valid reference and consuming it in the `volumeMounts` of the container. For example:
+
+{{% code_sample file="pods/image-volumes.yaml" %}}
+
+1. Create the pod on your cluster:
+
+   ```shell
+   kubectl apply -f https://k8s.io/examples/pods/image-volumes.yaml
+   ```
+
+1. Attach to the container:
+
+   ```shell
+   kubectl attach -it image-volume bash
+   ```
+
+Run this command:
+
+```shell
+cat /volume/dir/file
+```
+
+The output is similar to:
+
+```shell
+1
+```
+
+Also run:
+
+```shell
+cat /volume/file
+```
+
+The output is similar to:
+
+```shell
+2
+```
+
+## Further reading
+
+- [`image` volumes](/docs/concepts/storage/volumes/#image)

content/en/examples/pods/image-volumes.yaml

@@ -0,0 +1,17 @@
+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