diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 33ca5006dd6a..dcbeec6dfc21 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1837,6 +1837,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..06db2e3c511a --- /dev/null +++ b/modules/persistent-storage-csi-vol-populator-procedure-admin.adoc @@ -0,0 +1,190 @@ +// 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" custom 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 + +. Create a namespace for the logical grouping and operation of the populator, and related resources, using the following example YAML file: ++ +.Example namespace YAML file +[source,yaml] +---- +apiVersion: v1 +kind: Namespace +metadata: + name: hello +---- + +. Create a CRD for your data source using the following example YAML file: ++ +.Example CRD 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 +---- + +. Deploy the controller by creating a `ServiceAccount`, `ClusterRole`, `ClusterRoleBindering`, and `Deployment` to run the logic that implements the population: + +.. Create a service account for the populator using the following example YAML file: ++ +.Example service account YAML file +[source,yaml] +---- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: hello-account + namespace: hello <1> +---- +<1> Reference the namespace that you created earlier. + +.. Create a cluster role for the populator using the following example YAML file: ++ +.Example cluster role YAML file +[source,yaml] +---- +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: hello-role +rules: + - apiGroups: [hello.example.com] + resources: [hellos] + verbs: [get, list, watch] +---- + +.. Create a cluster role binding using the following example YAML file: ++ +.Example cluster role binding YAML file +[source,yaml] +---- +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: hello-binding <1> +subjects: + - kind: ServiceAccount + name: hello-account <2> + namespace: hello <3> +roleRef: + kind: ClusterRole + name: hello-role <4> + apiGroup: rbac.authorization.k8s.io +---- +<1> Role binding name. +<2> Reference the name of the service account that you created earlier. +<3> Reference the name of the namespace for the service account that you created earlier. +<4> Reference the cluster role you created earlier. + +.. Create a Deployment for the populator using the following example YAML file: ++ +.Example deployment YAML file +[source,yaml] +---- +kind: Deployment +apiVersion: apps/v1 +metadata: + name: hello-populator + namespace: hello <1> +spec: + selector: + matchLabels: + app: hello + template: + metadata: + labels: + app: hello + spec: + serviceAccount: hello-account <2> + containers: + - name: hello + image: registry.k8s.io/sig-storage/hello-populator:v1.0.1 + imagePullPolicy: IfNotPresent + args: + - --mode=controller + - --image-name=registry.k8s.io/sig-storage/hello-populator:v1.0.1 + - --http-endpoint=:8080 + ports: + - containerPort: 8080 + name: http-endpoint + protocol: TCP +---- +<1> Reference the namespace that you created earlier. +<2> Reference the service account that you created earlier. + +. Create a volume populator to register the `kind:Hello` resource as a valid data source for the volume using the following example YAML file: ++ +.Example volume populator YAML file +[source,yaml] +---- +kind: VolumePopulator +apiVersion: populator.storage.k8s.io/v1beta1 +metadata: + name: hello-populator <1> +sourceKind: + group: hello.example.com + kind: Hello +---- +<1> Volume populator name. ++ +PVCs that use an unregistered populator generate an event: "The datasource for this PVC does not match any registered VolumePopulator", indicating that the PVC might not be provisioned because you are using an unknown (unregistered) populator. + +.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..75a073cce836 --- /dev/null +++ b/modules/persistent-storage-csi-vol-populator-procedure.adoc @@ -0,0 +1,141 @@ +// 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 prepopulated volumes using volume populators + +The following procedure explains how to create a prepopulated persistent volume claim (PVC) using the example `hellos.hello.example.com` Custom Resource Definition (CRD) created previously. + +In this example, rather than using an actual data source, you are creating a file called "example.txt" that contains the string "Hello, world!" in the root directory of the volume. For a real-world implementation, you need to create your own volume populator. + +.Prerequisites + +* You are logged in to a running {product-title} cluster. + +* There is an existing custom resource definition (CRD) for volume populators. + +* {product-title} does not ship with any volume populators. You *must* create your own volume populator. + +.Procedure + +. Create a Custom Resource (CR) instance of the `Hello` CRD with the text "Hello, World!" passed in as `fileContents` parameter 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'. + +.Verification + +. After a few minutes, ensure that the PVC is created and in the `Bound` status by running the following command: ++ +[source,terminal] +---- +$ oc get pvc example-pvc -n hello <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`. + +. Start 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, and all of its dependencies, to finish by running the following command: ++ +[source,terminal] +---- +$ oc wait --for=condition=Complete pod/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-uninstall.adoc b/modules/persistent-storage-csi-vol-populator-uninstall.adoc new file mode 100644 index 000000000000..4f46d12c91cc --- /dev/null +++ b/modules/persistent-storage-csi-vol-populator-uninstall.adoc @@ -0,0 +1,26 @@ +// 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-uninstall_{context}"] += Uninstalling volume populators + +The following procedure explains how to uninstall volume populators. + +.Prerequisites + +* Access to the {product-title} web console. + +* Access to the cluster with cluster-admin privileges. + +.Procedure + +To uninstall volume populators, delete in reverse order all objects installed in the procedures under: + +. Section _Creating prepopulated volumes using volume populators_. + +. Section _Creating CRDs for volume populators_. ++ +Be sure to remove the `VolumePopulator` instance. + diff --git a/modules/persistent-storage-csi-vol-populator.adoc b/modules/persistent-storage-csi-vol-populator.adoc index 9a18114979a7..4375cc11293e 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. +In {product-title} versions 4.12 through 4.19, the `dataSource` field in a persistent volume claim (PVC) spec provides volume populator capability. However, it is limited to using only PVCs and snapshots as the data source for populating volumes. -Volume population is currently enabled, and supported as a Technology Preview feature. However, {product-title} does not ship with any volume populators. +Starting with {product-title} version 4.20, the `dataSourceRef` field is used instead. With the `dataSourceRef` field, you can use any appropriate custom resource (CR) as the data source to prepopulate 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 `dataSourceRef` field to avoid future issues. +==== + +Volume population is enabled by default and {product-title} includes the installed `volume-data-source-validator` controller. 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..85ba0ad41828 --- /dev/null +++ b/storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc @@ -0,0 +1,30 @@ +:_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::[] + +Volume Populators enable the automatic pre-loading of data into a volume during dynamic provisioning, instead of provisioning an empty volume. + +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 prepopulated volume using a volume populator. + +include::modules/persistent-storage-csi-vol-populator-procedure-admin.adoc[leveloffset=+2] + +For information about how to prepopulate volumes 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 prepoluated volumes with volume populators]. + +include::modules/persistent-storage-csi-vol-populator-procedure.adoc[leveloffset=+2] + +include::modules/persistent-storage-csi-vol-populator-uninstall.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 +//This features is GA in OCP 4.20 diff --git a/storage/container_storage_interface/persistent-storage-csi.adoc b/storage/container_storage_interface/persistent-storage-csi.adoc index 8f3a901331fd..21962195f61f 100644 --- a/storage/container_storage_interface/persistent-storage-csi.adoc +++ b/storage/container_storage_interface/persistent-storage-csi.adoc @@ -38,11 +38,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