Skip to content

Commit 16b4d1c

Browse files
Lisa Pettyjohnopenshift-cherrypick-robot
Lisa Pettyjohn
authored and
openshift-cherrypick-robot
committed
OSDOCS-15215#Volume populators TP > GA
1 parent 51860c0 commit 16b4d1c

7 files changed

+401
-14
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1837,6 +1837,8 @@ Topics:
18371837
File: persistent-storage-csi-group-snapshots
18381838
- Name: CSI volume cloning
18391839
File: persistent-storage-csi-cloning
1840+
- Name: Volume populators
1841+
File: persistent-storage-csi-vol-populators
18401842
- Name: Managing the default storage class
18411843
File: persistent-storage-csi-sc-manage
18421844
- Name: CSI automatic migration

‎modules/persistent-storage-csi-vol-populator-procedure-admin.adoc‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="persistent-storage-csi-vol-populator-procedure-admin_{context}"]
7+
= Creating CRDs for volume populators
8+
9+
The following procedure explains how to create an example "hello, world" custom resource definition (CRD) for a volume populator.
10+
11+
Users can then create instances of this CRD to populate persistent volume claims (PVCs).
12+
13+
.Prerequisites
14+
15+
* Access to the {product-title} web console.
16+
17+
* Access to the cluster with cluster-admin privileges.
18+
19+
.Procedure
20+
21+
. Create a namespace for the logical grouping and operation of the populator, and related resources, using the following example YAML file:
22+
+
23+
.Example namespace YAML file
24+
[source,yaml]
25+
----
26+
apiVersion: v1
27+
kind: Namespace
28+
metadata:
29+
name: hello
30+
----
31+
32+
. Create a CRD for your data source using the following example YAML file:
33+
+
34+
.Example CRD YAML file
35+
[source,yaml]
36+
----
37+
apiVersion: apiextensions.k8s.io/v1
38+
kind: CustomResourceDefinition
39+
metadata:
40+
name: hellos.hello.example.com
41+
spec:
42+
group: hello.example.com
43+
names:
44+
kind: Hello
45+
listKind: HelloList
46+
plural: hellos
47+
singular: hello
48+
scope: Namespaced
49+
versions:
50+
- name: v1alpha1
51+
schema:
52+
openAPIV3Schema:
53+
description: Hello is a specification for a Hello resource
54+
properties:
55+
apiVersion:
56+
description: 'APIVersion defines the versioned schema of this representation
57+
of an object. Servers should convert recognized schemas to the latest
58+
internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
59+
type: string
60+
kind:
61+
description: 'Kind is a string value representing the REST resource this
62+
object represents. Servers may infer this from the endpoint the client
63+
submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
64+
type: string
65+
spec:
66+
description: HelloSpec is the spec for a Hello resource
67+
properties:
68+
fileContents:
69+
type: string
70+
fileName:
71+
type: string
72+
required:
73+
- fileContents
74+
- fileName
75+
type: object
76+
required:
77+
- spec
78+
type: object
79+
served: true
80+
storage: true
81+
----
82+
83+
. Deploy the controller by creating a `ServiceAccount`, `ClusterRole`, `ClusterRoleBindering`, and `Deployment` to run the logic that implements the population:
84+
85+
.. Create a service account for the populator using the following example YAML file:
86+
+
87+
.Example service account YAML file
88+
[source,yaml]
89+
----
90+
apiVersion: v1
91+
kind: ServiceAccount
92+
metadata:
93+
name: hello-account
94+
namespace: hello <1>
95+
----
96+
<1> Reference the namespace that you created earlier.
97+
98+
.. Create a cluster role for the populator using the following example YAML file:
99+
+
100+
.Example cluster role YAML file
101+
[source,yaml]
102+
----
103+
kind: ClusterRole
104+
apiVersion: rbac.authorization.k8s.io/v1
105+
metadata:
106+
name: hello-role
107+
rules:
108+
- apiGroups: [hello.example.com]
109+
resources: [hellos]
110+
verbs: [get, list, watch]
111+
----
112+
113+
.. Create a cluster role binding using the following example YAML file:
114+
+
115+
.Example cluster role binding YAML file
116+
[source,yaml]
117+
----
118+
kind: ClusterRoleBinding
119+
apiVersion: rbac.authorization.k8s.io/v1
120+
metadata:
121+
name: hello-binding <1>
122+
subjects:
123+
- kind: ServiceAccount
124+
name: hello-account <2>
125+
namespace: hello <3>
126+
roleRef:
127+
kind: ClusterRole
128+
name: hello-role <4>
129+
apiGroup: rbac.authorization.k8s.io
130+
----
131+
<1> Role binding name.
132+
<2> Reference the name of the service account that you created earlier.
133+
<3> Reference the name of the namespace for the service account that you created earlier.
134+
<4> Reference the cluster role you created earlier.
135+
136+
.. Create a Deployment for the populator using the following example YAML file:
137+
+
138+
.Example deployment YAML file
139+
[source,yaml]
140+
----
141+
kind: Deployment
142+
apiVersion: apps/v1
143+
metadata:
144+
name: hello-populator
145+
namespace: hello <1>
146+
spec:
147+
selector:
148+
matchLabels:
149+
app: hello
150+
template:
151+
metadata:
152+
labels:
153+
app: hello
154+
spec:
155+
serviceAccount: hello-account <2>
156+
containers:
157+
- name: hello
158+
image: registry.k8s.io/sig-storage/hello-populator:v1.0.1
159+
imagePullPolicy: IfNotPresent
160+
args:
161+
- --mode=controller
162+
- --image-name=registry.k8s.io/sig-storage/hello-populator:v1.0.1
163+
- --http-endpoint=:8080
164+
ports:
165+
- containerPort: 8080
166+
name: http-endpoint
167+
protocol: TCP
168+
----
169+
<1> Reference the namespace that you created earlier.
170+
<2> Reference the service account that you created earlier.
171+
172+
. Create a volume populator to register the `kind:Hello` resource as a valid data source for the volume using the following example YAML file:
173+
+
174+
.Example volume populator YAML file
175+
[source,yaml]
176+
----
177+
kind: VolumePopulator
178+
apiVersion: populator.storage.k8s.io/v1beta1
179+
metadata:
180+
name: hello-populator <1>
181+
sourceKind:
182+
group: hello.example.com
183+
kind: Hello
184+
----
185+
<1> Volume populator name.
186+
+
187+
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.
188+
189+
.Next steps
190+
* You can now create CR instances of this CRD to populate PVCs.

‎modules/persistent-storage-csi-vol-populator-procedure.adoc‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="persistent-storage-csi-vol-populator-procedure_{context}"]
7+
= Creating prepopulated volumes using volume populators
8+
9+
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.
10+
11+
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.
12+
13+
.Prerequisites
14+
15+
* You are logged in to a running {product-title} cluster.
16+
17+
* There is an existing custom resource definition (CRD) for volume populators.
18+
19+
* {product-title} does not ship with any volume populators. You *must* create your own volume populator.
20+
21+
.Procedure
22+
23+
. 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:
24+
+
25+
[source,terminal]
26+
----
27+
$ oc apply -f - <<EOF
28+
apiVersion: hello.example.com/v1alpha1
29+
kind: Hello
30+
metadata:
31+
name: example-hello
32+
spec:
33+
fileName: example.txt
34+
fileContents: Hello, world!
35+
EOF
36+
----
37+
38+
. Create a PVC that references the Hello CR similar to the following example file:
39+
+
40+
.Example PVC YAML file
41+
[source,yaml]
42+
----
43+
apiVersion: v1
44+
kind: PersistentVolumeClaim
45+
metadata:
46+
name: example-pvc
47+
spec:
48+
accessModes:
49+
- ReadWriteOnce
50+
resources:
51+
requests:
52+
storage: 10Mi
53+
dataSourceRef: <1>
54+
apiGroup: hello.example.com
55+
kind: Hello
56+
name: example-hello <2>
57+
volumeMode: Filesystem
58+
----
59+
<1> The `dataSourceRef` field specifies the data source for the PVC.
60+
<2> The name of the CR that you are using as the data source. In this example, 'example-hello'.
61+
62+
.Verification
63+
64+
. After a few minutes, ensure that the PVC is created and in the `Bound` status by running the following command:
65+
+
66+
[source,terminal]
67+
----
68+
$ oc get pvc example-pvc -n hello <1>
69+
----
70+
<1> In this example, the name of the PVC is `example-pvc`.
71+
+
72+
.Example output
73+
[source,terminal]
74+
----
75+
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE
76+
example-pvc Bound my-pv 10Mi ReadWriteOnce gp3-csi <unset> 14s
77+
----
78+
79+
. Create a job that reads from the PVC to verify that the data source information was applied using the following example file:
80+
+
81+
.Example job YAML file
82+
[source,yaml]
83+
----
84+
apiVersion: batch/v1
85+
kind: Job
86+
metadata:
87+
name: example-job
88+
spec:
89+
template:
90+
spec:
91+
containers:
92+
- name: example-container
93+
image: busybox:latest
94+
command:
95+
- cat
96+
- /mnt/example.txt <1>
97+
volumeMounts:
98+
- name: vol
99+
mountPath: /mnt
100+
restartPolicy: Never
101+
volumes:
102+
- name: vol
103+
persistentVolumeClaim:
104+
claimName: example-pvc <2>
105+
----
106+
<1> The location and name of the file with the "Hello, world!" text.
107+
<2> The name of the PVC you created in Step 2. In this example, `example-pvc`.
108+
109+
. Start the job by running the following command:
110+
+
111+
[source,terminal]
112+
----
113+
$ oc run example-job --image=busybox --command -- sleep 30 --restart=OnFailure
114+
----
115+
+
116+
.Example output
117+
[source,terminal]
118+
----
119+
pod/example-job created
120+
----
121+
122+
. Wait for the job, and all of its dependencies, to finish by running the following command:
123+
+
124+
[source,terminal]
125+
----
126+
$ oc wait --for=condition=Complete pod/example-job
127+
----
128+
129+
. Verify the contents collected by the job by running the following command:
130+
+
131+
[source,terminal]
132+
----
133+
$ oc logs job/example-job
134+
----
135+
+
136+
.Expected output
137+
+
138+
[source,terminal]
139+
----
140+
Hello, world!
141+
----

‎modules/persistent-storage-csi-vol-populator-uninstall.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="persistent-storage-csi-vol-populator-uninstall_{context}"]
7+
= Uninstalling volume populators
8+
9+
The following procedure explains how to uninstall volume populators.
10+
11+
.Prerequisites
12+
13+
* Access to the {product-title} web console.
14+
15+
* Access to the cluster with cluster-admin privileges.
16+
17+
.Procedure
18+
19+
To uninstall volume populators, delete in reverse order all objects installed in the procedures under:
20+
21+
. Section _Creating prepopulated volumes using volume populators_.
22+
23+
. Section _Creating CRDs for volume populators_.
24+
+
25+
Be sure to remove the `VolumePopulator` instance.
26+

‎modules/persistent-storage-csi-vol-populator.adoc‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
11
// Module included in the following assemblies:
22
//
3-
// * storage/container_storage_interface/persistent-storage-csi.adoc
3+
// * storage/container_storage_interface/persistent-storage-csi-vol-populators.adoc
44

55
:_mod-docs-content-type: CONCEPT
66
[id="persistent-storage-csi-vol-populator_{context}"]
7-
= Volume populators
7+
= Volume populators overview
88

9-
Volume populators use the `datasource` field in a persistent volume claim (PVC) spec to create pre-populated volumes.
9+
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.
1010

11-
Volume population is currently enabled, and supported as a Technology Preview feature. However, {product-title} does not ship with any volume populators.
11+
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.
12+
13+
[NOTE]
14+
====
15+
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.
16+
====
17+
18+
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.
1219

13-
:FeatureName: Volume populators
14-
include::snippets/technology-preview.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)