From a12454f2dc41ce3507c473f4082b4c16c61c2efa Mon Sep 17 00:00:00 2001 From: Sascha Grunert Date: Mon, 24 Jun 2024 10:58:13 +0200 Subject: [PATCH] Add ImageVolume documentation Add a basic task how to use image volumes in pods. Signed-off-by: Sascha Grunert --- content/en/docs/concepts/storage/volumes.md | 65 +++++++++++++++++ .../feature-gates/image-volume.md | 14 ++++ .../configure-pod-container/image-volumes.md | 72 +++++++++++++++++++ content/en/examples/pods/image-volumes.yaml | 17 +++++ 4 files changed, 168 insertions(+) create mode 100644 content/en/docs/reference/command-line-tools-reference/feature-gates/image-volume.md create mode 100644 content/en/docs/tasks/configure-pod-container/image-volumes.md create mode 100644 content/en/examples/pods/image-volumes.yaml diff --git a/content/en/docs/concepts/storage/volumes.md b/content/en/docs/concepts/storage/volumes.md index 2abda30150..be8cbc6439 100644 --- a/content/en/docs/concepts/storage/volumes.md +++ b/content/en/docs/concepts/storage/volumes.md @@ -534,6 +534,71 @@ spec: type: FileOrCreate ``` +### image + +{{< feature-state feature_gate_name="ImageVolume" >}} + +An `image` volume source represents an OCI object (a container image or +artifact) which is available 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. If the pull fails, the kubelet sets the Pod to `Failed`. + +`Never` +: the kubelet never pulls the reference and only uses a local image or artifact. The Pod becomes `Failed` if any layers of the image aren't already present locally, or if the manifest for that image isn't already cached. + +`IfNotPresent` +: the kubelet pulls if the reference isn't already present on disk. The Pod becomes `Failed` 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 +will be mounted read-only. On Linux, the container runtime typically also mounts the +volume with file execution blocked (`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` +: Artifact reference to be used. For example, you could specify +`registry.k8s.io/conformance:v{{< skew currentPatchVersion >}}` to load the +files from the Kubernetes conformance test image. 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 diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/image-volume.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/image-volume.md new file mode 100644 index 0000000000..cb92837bde --- /dev/null +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates/image-volume.md @@ -0,0 +1,14 @@ +--- +title: ImageVolume +content_type: feature_gate +_build: + list: never + render: false + +stages: + - stage: alpha + defaultValue: false + fromVersion: "1.31" +--- +Allow using the [`image`](/docs/concepts/storage/volumes/) volume source in a Pod. +This volume source lets you mount a container image as a read-only volume. diff --git a/content/en/docs/tasks/configure-pod-container/image-volumes.md b/content/en/docs/tasks/configure-pod-container/image-volumes.md new file mode 100644 index 0000000000..08da62beaf --- /dev/null +++ b/content/en/docs/tasks/configure-pod-container/image-volumes.md @@ -0,0 +1,72 @@ +--- +title: Use an Image Volume With a Pod +reviewers: +content_type: task +weight: 210 +min-kubernetes-server-version: v1.31 +--- + + + +{{< 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 >}} + +- 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/) + + + +## 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) diff --git a/content/en/examples/pods/image-volumes.yaml b/content/en/examples/pods/image-volumes.yaml new file mode 100644 index 0000000000..3a3cc79a4a --- /dev/null +++ b/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