OSDOCS-15215#Volume populators TP > GA

_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

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. 

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  - <<EOF
+apiVersion: hello.example.com/v1alpha1
+kind: Hello
+metadata:
+  name: example-hello
+spec:
+  fileName: example.txt
+  fileContents: Hello, world!
+EOF
+----
++
+The CR serves as the data source to populate the PVC that you create later in this procedure.
+
+. Create a PVC that references the Hello CR by using the following example file:
++
+.Example PVC YAML file
+[source,yaml]
+----
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: example-pvc
+spec:
+  accessModes:
+  - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Mi
+  dataSourceRef: <1>
+    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        <unset>                 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!
+----

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]

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

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[]
+include::modules/persistent-storage-csi-mysql-example.adoc[leveloffset=+1]