Skip to content

Commit 4399493

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 4399493

File tree

4 files changed

+153
-0
lines changed

4 files changed

+153
-0
lines changed

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

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -543,6 +543,53 @@ 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. The volume is
552+
resolved at pod startup depending on which PullPolicy value is provided:
553+
554+
- `Always`: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
555+
- `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.
556+
- `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.
557+
558+
The volume gets re-resolved if the pod gets deleted and recreated, which means
559+
that new remote content will become available on pod recreation. A failure to
560+
resolve or pull the image during pod startup will block containers from starting
561+
and may add significant latency. Failures will be retried using normal volume
562+
backoff and will be reported on the pod reason and message. The types of objects
563+
that may be mounted by this volume are defined by the container runtime
564+
implementation on a host machine and at minimum must include all valid types
565+
supported by the container image field. The OCI object gets mounted in a single
566+
directory (`spec.containers[*].volumeMounts.mountPath`) by merging the manifest
567+
layers in the same way as for container images. The volume will be mounted
568+
read-only (`ro`) and non-executable files (`noexec`). Sub path mounts for
569+
containers are not supported (`spec.containers[*].volumeMounts.subpath`). The
570+
field `spec.securityContext.fsGroupChangePolicy` has no effect on this volume
571+
type. The [`AlwaysPullImages` Admision Controller](/docs/reference/access-authn-authz/admission-controllers/#alwayspullimages)
572+
does also work for this volume source like for container images.
573+
574+
The following fields are available for the `ImageVolumeSource` type:
575+
576+
- `reference`: Image or artifact reference to be used.
577+
Behaves in the same way as `pod.spec.containers[*].image`.
578+
Pull secrets will be assembled in the same way as for the container image by
579+
looking up node credentials, SA image pull secrets, and pod spec image pull
580+
secrets. This field is optional to allow higher level config management to
581+
default or override container images in workload controllers like
582+
Deployments and StatefulSets.
583+
584+
[More info about container images](/docs/concepts/containers/images)
585+
586+
- `pullPolicy`: Policy for pulling OCI objects. Possible values are: `Always`,
587+
`Never` or `IfNotPresent`. Defaults to `Always` if `:latest` tag is
588+
specified, or `IfNotPresent` otherwise.
589+
590+
See the [Use an Image Volume With a Pod](docs/tasks/configure-pod-container/image-volumes)
591+
example for more details on how to use the volume source.
592+
546593
### iscsi
547594

548595
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 be able to use `pod.spec.volumes[*].image`

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

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
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+
The feature has been developed as part of [Kubernetes enhancement #4639](https://kep.k8s.io/4639).
17+
18+
## {{% heading "prerequisites" %}}
19+
20+
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
21+
22+
{{% thirdparty-content single="true" %}}
23+
24+
- The node OS needs to be Linux
25+
- The container runtime needs to support the image volumes feature.
26+
- You need to exec commands in the host
27+
- You need to be able to exec into pods
28+
- You need to enable the `ImageVolume` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
29+
30+
<!-- steps -->
31+
32+
## Run a Pod that uses an image volume {#create-pod}
33+
34+
An image volume for a pod is enabled setting the `volumes.[*].image` field of `.spec`
35+
to a valid reference and consuming it in the `volumeMounts` of the container. For example:
36+
37+
{{% code_sample file="pods/image-volumes.yaml" %}}
38+
39+
1. Create the pod on your cluster:
40+
41+
```shell
42+
kubectl apply -f https://k8s.io/examples/pods/image-volumes.yaml
43+
```
44+
45+
1. Attach to the container:
46+
47+
```shell
48+
kubectl attach -it image-volume bash
49+
```
50+
51+
Run this command:
52+
53+
```shell
54+
cat /volume/dir/file
55+
```
56+
57+
The output is similar to:
58+
59+
```shell
60+
1
61+
```
62+
63+
Also run:
64+
65+
```shell
66+
cat /volume/file
67+
```
68+
69+
The output is similar to:
70+
71+
```shell
72+
2
73+
```
74+
75+
## Further reading
76+
77+
- [`image` volumes](/docs/concepts/storage/volumes/#image)

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

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

0 commit comments

Comments
 (0)