Skip to content

Commit eb2e1ae

Browse files
saschagrunertsaschagrunert
committed
Add ImageVolume documentation
Add a basic task how to use image volumes in pods. Signed-off-by: Sascha Grunert <[email protected]>
1 parent 97ab108 commit eb2e1ae

File tree

4 files changed

+167
-0
lines changed

4 files changed

+167
-0
lines changed

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

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -543,6 +543,68 @@ spec:
543543
type: FileOrCreate
544544
```
545545

546+
### image
547+
548+
{{< feature-state feature_gate_name="ImageVolume" >}}
549+
550+
An `image` volume source represents an OCI object (a container image or
551+
artifact) pulled and mounted on the kubelet's host machine.
552+
553+
One example to use the `image` volume source is:
554+
555+
{{% code_sample file="pods/image-volumes.yaml" %}}
556+
557+
The volume is resolved at pod startup depending on which `pullPolicy` value is
558+
provided:
559+
560+
- `Always`: the kubelet always attempts to pull the reference. Container
561+
creation will fail if the pull fails.
562+
- `Never`: the kubelet never pulls the reference and only uses a local image or
563+
artifact. Container creation will fail if the reference isn't present.
564+
- `IfNotPresent`: the kubelet pulls if the reference isn't already present on
565+
disk. Container creation will fail if the reference isn't present and the pull
566+
fails.
567+
568+
The volume gets re-resolved if the pod gets deleted and recreated, which means
569+
that new remote content will become available on pod recreation. A failure to
570+
resolve or pull the image during pod startup will block containers from starting
571+
and may add significant latency. Failures will be retried using normal volume
572+
backoff and will be reported on the pod reason and message.
573+
574+
The types of objects that may be mounted by this volume are defined by the
575+
container runtime implementation on a host machine and at minimum must include
576+
all valid types supported by the container image field. The OCI object gets
577+
mounted in a single directory (`spec.containers[*].volumeMounts.mountPath`) by
578+
merging the manifest layers in the same way as for container images. The volume
579+
will be mounted read-only (`ro`) and non-executable files (`noexec`).
580+
581+
Beside that:
582+
- Sub path mounts for containers are not supported
583+
(`spec.containers[*].volumeMounts.subpath`).
584+
- The field `spec.securityContext.fsGroupChangePolicy` has no effect on this
585+
volume type.
586+
- The [`AlwaysPullImages` Admission Controller](/docs/reference/access-authn-authz/admission-controllers/#alwayspullimages)
587+
does also work for this volume source like for container images.
588+
589+
The following fields are available for the `image` type:
590+
591+
- `reference`: Image or artifact reference to be used.
592+
Behaves in the same way as `pod.spec.containers[*].image`.
593+
Pull secrets will be assembled in the same way as for the container image by
594+
looking up node credentials, service account image pull secrets, and pod
595+
spec image pull secrets. This field is optional to allow higher level config
596+
management to default or override container images in workload controllers
597+
like Deployments and StatefulSets.
598+
599+
[More info about container images](/docs/concepts/containers/images)
600+
601+
- `pullPolicy`: Policy for pulling OCI objects. Possible values are: `Always`,
602+
`Never` or `IfNotPresent`. Defaults to `Always` if `:latest` tag is
603+
specified, or `IfNotPresent` otherwise.
604+
605+
See the [_Use an Image Volume With a Pod_](/docs/tasks/configure-pod-container/image-volumes)
606+
example for more details on how to use the volume source.
607+
546608
### iscsi
547609

548610
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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: ImageVolume
3+
content_type: feature_gate
4+
_build:
5+
list: never
6+
render: false
7+
8+
stages:
9+
- stage: alpha
10+
defaultValue: false
11+
fromVersion: "1.31"
12+
---
13+
Enable the `ImageVolumeSource` API to use `pod.spec.volumes[*].image`.

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: Use an Image Volume With a Pod
3+
reviewers:
4+
content_type: task
5+
weight: 210
6+
min-kubernetes-server-version: v1.31
7+
---
8+
9+
<!-- overview -->
10+
11+
{{< feature-state feature_gate_name="ImageVolume" >}}
12+
13+
This page shows how to configure a pod using image volumes. This allows you to
14+
mount content from OCI registries inside containers.
15+
16+
## {{% heading "prerequisites" %}}
17+
18+
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
19+
20+
{{% thirdparty-content single="true" %}}
21+
22+
- The node OS needs to be Linux
23+
- The container runtime needs to support the image volumes feature
24+
- You need to exec commands in the host
25+
- You need to be able to exec into pods
26+
- You need to enable the `ImageVolume` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
27+
28+
<!-- steps -->
29+
30+
## Run a Pod that uses an image volume {#create-pod}
31+
32+
An image volume for a pod is enabled setting the `volumes.[*].image` field of `.spec`
33+
to a valid reference and consuming it in the `volumeMounts` of the container. For example:
34+
35+
{{% code_sample file="pods/image-volumes.yaml" %}}
36+
37+
1. Create the pod on your cluster:
38+
39+
```shell
40+
kubectl apply -f https://k8s.io/examples/pods/image-volumes.yaml
41+
```
42+
43+
1. Attach to the container:
44+
45+
```shell
46+
kubectl attach -it image-volume bash
47+
```
48+
49+
Run this command:
50+
51+
```shell
52+
cat /volume/dir/file
53+
```
54+
55+
The output is similar to:
56+
57+
```shell
58+
1
59+
```
60+
61+
Also run:
62+
63+
```shell
64+
cat /volume/file
65+
```
66+
67+
The output is similar to:
68+
69+
```shell
70+
2
71+
```
72+
73+
## Further reading
74+
75+
- [`image` volumes](/docs/concepts/storage/volumes/#image)

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
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

0 commit comments

Comments
 (0)