From f51fa8a0ac5f952bd5b0ea5f237a94ffa7c56b89 Mon Sep 17 00:00:00 2001 From: Lisa Pettyjohn Date: Tue, 8 Jul 2025 12:08:17 -0400 Subject: [PATCH] OSDOCS-15215#Volume populators TP > GA --- _topic_maps/_topic_map.yml | 2 + ...age-csi-vol-populator-procedure-admin.adoc | 75 ++++++++++ ...t-storage-csi-vol-populator-procedure.adoc | 139 ++++++++++++++++++ .../persistent-storage-csi-vol-populator.adoc | 17 ++- ...persistent-storage-csi-vol-populators.adoc | 24 +++ .../persistent-storage-csi.adoc | 9 +- 6 files changed, 252 insertions(+), 14 deletions(-) create mode 100644 modules/persistent-storage-csi-vol-populator-procedure-admin.adoc create mode 100644 modules/persistent-storage-csi-vol-populator-procedure.adoc create mode 100644 storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index bc25dc0fe383..707c36bd220a 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1832,6 +1832,8 @@ Topics: File: persistent-storage-csi-group-snapshots - Name: CSI volume cloning File: persistent-storage-csi-cloning + - Name: Volume populators + File: persistent-storage-csi-vol-populators - Name: Managing the default storage class File: persistent-storage-csi-sc-manage - Name: CSI automatic migration diff --git a/modules/persistent-storage-csi-vol-populator-procedure-admin.adoc b/modules/persistent-storage-csi-vol-populator-procedure-admin.adoc new file mode 100644 index 000000000000..3d1db399557c --- /dev/null +++ b/modules/persistent-storage-csi-vol-populator-procedure-admin.adoc @@ -0,0 +1,75 @@ +// Module included in the following assemblies: +// +// * storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc + +:_mod-docs-content-type: PROCEDURE +[id="persistent-storage-csi-vol-populator-procedure-admin_{context}"] += Creating CRDs for volume populators + +The following procedure explains how to create an example "hello, world" customer resource definition (CRD) for a volume populator. + +Users can then create instances of this CRD to populate persistent volume claims (PVCs). + +.Prerequisites + +* Access to the {product-title} web console. + +* Access to the cluster with cluster-admin privileges. + +.Procedure + +To create a CRD for a volume populator: + +. Create a CRD volume populator using the following example YAML file: ++ +.Example CRD volume populator YAML file +[source,yaml] +---- +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: hellos.hello.example.com +spec: + group: hello.example.com + names: + kind: Hello + listKind: HelloList + plural: hellos + singular: hello + scope: Namespaced + versions: + - name: v1alpha1 + schema: + openAPIV3Schema: + description: Hello is a specification for a Hello resource + properties: + apiVersion: + description: 'APIVersion defines the versioned schema of this representation + of an object. Servers should convert recognized schemas to the latest + internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources' + type: string + kind: + description: 'Kind is a string value representing the REST resource this + object represents. Servers may infer this from the endpoint the client + submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds' + type: string + spec: + description: HelloSpec is the spec for a Hello resource + properties: + fileContents: + type: string + fileName: + type: string + required: + - fileContents + - fileName + type: object + required: + - spec + type: object + served: true + storage: true +---- + +.Next steps +You can now create CR instances of this CRD to populate PVCs. \ No newline at end of file diff --git a/modules/persistent-storage-csi-vol-populator-procedure.adoc b/modules/persistent-storage-csi-vol-populator-procedure.adoc new file mode 100644 index 000000000000..cbd82757ab1c --- /dev/null +++ b/modules/persistent-storage-csi-vol-populator-procedure.adoc @@ -0,0 +1,139 @@ +// Module included in the following assemblies: +// +// * storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc + +:_mod-docs-content-type: PROCEDURE +[id="persistent-storage-csi-vol-populator-procedure_{context}"] += Creating pre-populated volumes using volume populators + +The following procedure explains how to use a custom data source, using the example 'hello, world' Custom Resource Definition (CRD) created previously, to create a pre-populated persistent volume claim (PVC)." + +.Prerequisites + +* You are logged in to a running {product-title} cluster. + +* A custom resource definition (CRD) for volume populators has already been created. + +.Procedure + +To create a pre-populated volume using a volume populator: + +. Create an instance of the "Hello" custom resource (CR) with the text "Hello, World!" by running the following command: ++ +[source,terminal] +---- +oc apply -f - < + apiGroup: hello.example.com + kind: Hello + name: example-hello <2> + volumeMode: Filesystem +---- +<1> The `dataSourceRef` field specifies the data source for the PVC. +<2> The name of the CR that you are using as the data source. In this example, 'example-hello'. + +. Ensure that the PVC is created and in `Bound` status after a while by running the following command: ++ +[source,terminal] +---- +$ oc get pvc example-pvc <1> +---- +<1> In this example, the name of the PVC is `example-pvc`. ++ +.Example output +[source,terminal] +---- +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE +example-pvc Bound my-pv 10Mi ReadWriteOnce gp3-csi 14s +---- + +. Create a job that reads from the PVC to verify that the data source information was applied using the following example file: ++ +.Example job YAML file +[source,yaml] +---- +apiVersion: batch/v1 +kind: Job +metadata: + name: example-job +spec: + template: + spec: + containers: + - name: example-container + image: busybox:latest + command: + - cat + - /mnt/example.txt <1> + volumeMounts: + - name: vol + mountPath: /mnt + restartPolicy: Never + volumes: + - name: vol + persistentVolumeClaim: + claimName: example-pvc <2> +---- +<1> The location and name of the file with the "Hello, world!" text. +<2> The name of the PVC you created in Step 2. In this example, `example-pvc`. + +. Run the job by running the following command: ++ +[source,terminal] +---- +oc run example-job --image=busybox --command -- sleep 30 --restart=OnFailure +---- ++ +.Example output +[source,terminal] +---- +pod/example-job created +---- + +. Wait for the job to finish (including all of its dependencies) by running the following command: ++ +[source,terminal] +---- +oc wait --for=condition=Complete job/example-job +---- + +. Verify the contents collected by the job by running the following command: ++ +[source,terminal] +---- +oc logs job/example-job +---- ++ +.Expected output ++ +[source,terminal] +---- +Hello, world! +---- diff --git a/modules/persistent-storage-csi-vol-populator.adoc b/modules/persistent-storage-csi-vol-populator.adoc index 9a18114979a7..ef2d1a8de925 100644 --- a/modules/persistent-storage-csi-vol-populator.adoc +++ b/modules/persistent-storage-csi-vol-populator.adoc @@ -1,14 +1,19 @@ // Module included in the following assemblies: // -// * storage/container_storage_interface/persistent-storage-csi.adoc +// * storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc :_mod-docs-content-type: CONCEPT [id="persistent-storage-csi-vol-populator_{context}"] -= Volume populators += Volume populators overview -Volume populators use the `datasource` field in a persistent volume claim (PVC) spec to create pre-populated volumes. +The volume populators feature allows you to create pre-populated volumes. -Volume population is currently enabled, and supported as a Technology Preview feature. However, {product-title} does not ship with any volume populators. +In {product-title} 4.12 through 4.19, the `dataSource` field in a persistent volume claim (PVC) spec provided volume populator capability. However, it was limited to using only PVCs and snapshots as the data source for populating volumes. Starting with {product-title} 4.20, the `dataSourceRef` field is used instead. With `dataSourceRef`, you can use any appropriate custom resource (CR) as the data source to pre-populate a new volume. + +[NOTE] +==== +Volume populator functionality using the `dataSource` field is likely to be deprecated in future versions. If you have created any volume populators using this field, consider re-creating your volume populators to use the new `dataSourceRef` field to avoid future issues. +==== + +Volume population is enabled by default and {product-title} ships with the volume-data-source-validator controller installed. However, {product-title} does not ship with any volume populators. -:FeatureName: Volume populators -include::snippets/technology-preview.adoc[leveloffset=+1] diff --git a/storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc b/storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc new file mode 100644 index 000000000000..67574c62b4fc --- /dev/null +++ b/storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc @@ -0,0 +1,24 @@ +:_mod-docs-content-type: ASSEMBLY +[id="persistent-storage-csi-vol-populators"] += Volume populators +include::_attributes/common-attributes.adoc[] +:context: persistent-storage-csi-vol-populators + +toc::[] + +include::modules/persistent-storage-csi-vol-populator.adoc[leveloffset=+1] + +== Creating volume populators +To create and use volume populators: + +. Create a custom resource definition (CRD) for volume populators + +. Create a pre-populated volume using a volume populator + +include::modules/persistent-storage-csi-vol-populator-procedure-admin.adoc[leveloffset=+2] +For information about how to pre-populated volume using a volume populator, see xref:../../storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc#persistent-storage-csi-vol-populator-procedure_persistent-storage-csi-vol-populators[Creating pre-populated volumes with volume populators]. + +include::modules/persistent-storage-csi-vol-populator-procedure.adoc[leveloffset=+2] + + +// TP features should be excluded from OSD and ROSA. When this feature is GA, it can be included in the OSD/ROSA docs, but with a warning that it is available as of version 4.x diff --git a/storage/container_storage_interface/persistent-storage-csi.adoc b/storage/container_storage_interface/persistent-storage-csi.adoc index 0fc3e9a59149..cd8323d1ca1d 100644 --- a/storage/container_storage_interface/persistent-storage-csi.adoc +++ b/storage/container_storage_interface/persistent-storage-csi.adoc @@ -32,11 +32,4 @@ endif::openshift-rosa,openshift-rosa-hcp[] include::modules/persistent-storage-csi-dynamic-provisioning.adoc[leveloffset=+1] -include::modules/persistent-storage-csi-mysql-example.adoc[leveloffset=+1] - -// TP features should be excluded from OSD and ROSA. When this feature is GA, it can be included in the OSD/ROSA docs, but with a warning that it is available as of version 4.x. -ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] -include::modules/persistent-storage-csi-vol-populator.adoc[leveloffset=+1] - -For more information about volume populators, see link:https://kubernetes.io/blog/2022/05/16/volume-populators-beta/[Kubernetes volume populators]. -endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[] \ No newline at end of file +include::modules/persistent-storage-csi-mysql-example.adoc[leveloffset=+1] \ No newline at end of file