From 2926c8bbd11536bf5937b93def69f9bd49907819 Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Mon, 29 Sep 2025 12:30:02 -0400 Subject: [PATCH] OSDOCS 15329 Image Volume Source for AI Workloads in OpenShift - GA 4.20 --- _topic_maps/_topic_map.yml | 2 + modules/nodes-pods-image-volume-about.adoc | 22 ++++++ modules/nodes-pods-image-volume-adding.adoc | 83 +++++++++++++++++++++ nodes/pods/nodes-pods-image-volume.adoc | 19 +++++ 4 files changed, 126 insertions(+) create mode 100644 modules/nodes-pods-image-volume-about.adoc create mode 100644 modules/nodes-pods-image-volume-adding.adoc create mode 100644 nodes/pods/nodes-pods-image-volume.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index f335f0a614..1a7da6b6cf 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -2650,6 +2650,8 @@ Topics: File: nodes-pods-short-term-auth - Name: Creating and using config maps File: nodes-pods-configmaps + - Name: Mounting an OCI image into a pod + File: nodes-pods-image-volume - Name: Using Device Manager to make devices available to nodes File: nodes-pods-plugins Distros: openshift-enterprise,openshift-origin diff --git a/modules/nodes-pods-image-volume-about.adoc b/modules/nodes-pods-image-volume-about.adoc new file mode 100644 index 0000000000..56a06be843 --- /dev/null +++ b/modules/nodes-pods-image-volume-about.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * nodes/pods/nodes-pods-image-volume.adoc + +:_mod-docs-content-type: CONCEPT +[id="nodes-pods-image-volume-about_{context}"] += Understanding image volumes + +You can you use an _image volume_ to mount an Open Container Initiative (OCI)-compliant container image or artifact directly into a pod, making the files within the image accessible to the containers without the need to include them in the base image. This means you can host the data in an OCI-compliant registry. + +By using an image volume in a pod, you can take advantage of the OCI image and distribution specification standards to accomplish several tasks including the following use cases: + +//Use cases copied from the enhancement doc: https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/4639-oci-volume-source +* You can share configuration files among multiple containers in a pod without needing to include the file in the base image, which minimizes security risks and image size. + +* In an artificial intelligence environment, you can use image volumes to mount large language model weights or machine learning model weights in a pod alongside a model-server. You can efficiently serve model weights this way without including them in the model-server container image. Therefore, you can separate the model specifications and content from the executables that process them. + +* You can package and distribute binary artifacts and mount them directly into your pods, allowing you to streamline your CI/CD pipeline. This allows you to maintain a small set of base images by attaching the CI/CD artifacts to the image volumes instead. + +* You can use a public image for a malware scanner and mount it in a volume of private malware signatures, so that you can load those signatures without incorporating the image into a base image, which might not be allowed by the copyright on the public image. + +To mount an image volume, include a path to the image or artifact in your pod spec with an optional pull policy as described in _Adding an image volume to a pod_. diff --git a/modules/nodes-pods-image-volume-adding.adoc b/modules/nodes-pods-image-volume-adding.adoc new file mode 100644 index 0000000000..bf4c4a60e1 --- /dev/null +++ b/modules/nodes-pods-image-volume-adding.adoc @@ -0,0 +1,83 @@ +// Module included in the following assemblies: +// +// * nodes/pods/nodes-pods-image-volume.adoc + +:_mod-docs-content-type: PROCEDURE +[id="nodes-pods-image-volume-adding_{context}"] += Adding an image volume to a pod + +To mount an Open Container Initiative (OCI)-compliant container image or artifact, use the `volume` parameter to include a path to the image or artifact in your pod spec with an optional pull policy. You can create the pod directly or use a controlling object, such as a deployment or replica set. + +.Procedure + +. Create a YAML file similar to the following. ++ +[source,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: <1> + reference: quay.io/crio/artifact:v2 <2> + pullPolicy: Always <3> +---- +<1> Specifies an OCI container image or artifact that is available on the host machine. +<2> Specifies the path to the image or artifact. +<3> Specifies a pull policy, one of the following options: ++ +-- +* If `Always`, the kubelet always attempts to pull the image. If the pull fails, the kubelet sets the pod to `Failed`. +* If `Never`, the kubelet never pulls the image and only uses a local image or artifact. The pod becomes `Failed` if any layers of the image are not present locally, or if the manifest for that image is not already cached. +* If `IfNotPresent` the kubelet pulls the image if it not present. The pod becomes `Failed` if the image is not present and the pull fails. This is the default. +-- +// Pull policy details from upstream: https://kubernetes.io/docs/concepts/storage/volumes/#image + +. Create the pod by running the following command: ++ +[source,terminal] +---- +$ oc create -f .yaml +---- + +.Verification + +* Examine the pod to view detailed information about the image pull and mount by using a command similar to the following: ++ +[source,terminal] +---- +$ oc describe pod +---- ++ +.Example output +[source,yaml] +---- +Name: image-volume +Namespace: default +# ... +Volumes: + volume: <1> + Type: Image (a container image or OCI artifact) + Reference: quay.io/crio/artifact:v2 + PullPolicy: IfNotPresent +# ... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- +# ... + Normal Pulling 46s kubelet Pulling image "quay.io/crio/artifact:v2" + Normal Pulled 44s kubelet Successfully pulled image "quay.io/crio/artifact:v2" in 2.261s (2.261s including waiting). Image size: 6707 bytes. <2> +# ... +---- +<1> Indicates that the image volume was mounted to the pod. +<2> Indicates that the image was successfully pulled. diff --git a/nodes/pods/nodes-pods-image-volume.adoc b/nodes/pods/nodes-pods-image-volume.adoc new file mode 100644 index 0000000000..b83f61da0c --- /dev/null +++ b/nodes/pods/nodes-pods-image-volume.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: ASSEMBLY +:context: nodes-pods-node-selectors +[id="nodes-pods-image-volume"] += Mounting an OCI image into a pod +include::_attributes/common-attributes.adoc[] + +toc::[] + + +You can mount an Open Container Initiative (OCI)-compliant container image or artifact directly into a pod, making the files within the image accessible to the containers without the need to include them in the base image, which allows you to host the data in OCI-compliant registries. + +// The following include statements pull in the module files that comprise +// the assembly. Include any combination of concept, procedure, or reference +// modules required to cover the user story. You can also include other +// assemblies. + +include::modules/nodes-pods-image-volume-about.adoc[leveloffset=+1] + +include::modules/nodes-pods-image-volume-adding.adoc[leveloffset=+1]