Skip to content

Commit 997c861

Browse files
lpettyjolpettyjo
authored
Merge pull request #86332 from lpettyjo/OSDOCS-12927
OSDOCS-12927#Group Volume Snapshots (TP)
2 parents 5b32f8b + 53b45c6 commit 997c861

8 files changed

+341
-25
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1765,6 +1765,8 @@ Topics:
17651765
File: ephemeral-storage-csi-inline
17661766
- Name: CSI volume snapshots
17671767
File: persistent-storage-csi-snapshots
1768+
- Name: CSI volume group snapshots
1769+
File: persistent-storage-csi-group-snapshots
17681770
- Name: CSI volume cloning
17691771
File: persistent-storage-csi-cloning
17701772
- Name: Managing the default storage class

‎modules/persistent-storage-csi-drivers-supported.adoc

Lines changed: 28 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -35,44 +35,42 @@ In addition to the drivers listed in the following table, ROSA functions with CS
3535
endif::openshift-rosa,openshift-aro[]
3636

3737
.Supported CSI drivers and features in {product-title}
38-
[cols=",^v,^v,^v,^v,^v width="100%",options="header"]
38+
[cols=",^v,^v,^v,^v,^v,^v width="100%",options="header"]
3939
|===
40-
|CSI driver |CSI volume snapshots |CSI cloning |CSI resize |Inline ephemeral volumes
41-
|AWS EBS | ✅ | | ✅|
42-
|AWS EFS | | | |
40+
|CSI driver |CSI volume snapshots |CSI volume group snapshots ^[1]^ |CSI cloning |CSI resize |Inline ephemeral volumes
41+
|AWS EBS | ✅ | | | ✅|
42+
|AWS EFS | | | | |
4343
ifndef::openshift-rosa[]
44-
|Google Compute Platform (GCP) persistent disk (PD)| ✅| ✅^[5]^ | ✅|
45-
|GCP Filestore | ✅ | | ✅|
44+
|Google Compute Platform (GCP) persistent disk (PD)| ✅| |✅^[2]^ | ✅|
45+
|GCP Filestore | ✅ | | | ✅|
4646
endif::openshift-rosa[]
4747
ifndef::openshift-dedicated,openshift-rosa[]
48-
|{ibm-power-server-name} Block | | | ✅ |
49-
|{ibm-cloud-name} Block | ✅^[3]^ | | ✅^[3]^|
48+
|{ibm-power-server-name} Block | | | | ✅ |
49+
|{ibm-cloud-name} Block | ✅^[3]^ | | | ✅^[3]^|
5050
endif::openshift-dedicated,openshift-rosa[]
51-
|LVM Storage | ✅ | ✅ | ✅ |
51+
|LVM Storage | ✅ | | ✅ | ✅ |
5252
ifndef::openshift-dedicated,openshift-rosa[]
53-
|Microsoft Azure Disk | ✅ | ✅ | ✅|
54-
|Microsoft Azure Stack Hub | ✅ | ✅ | ✅|
55-
|Microsoft Azure File | ✅^[4]^ | ✅^[4]^ | ✅| ✅
56-
|OpenStack Cinder | ✅ | ✅ | ✅|
57-
|OpenShift Data Foundation | ✅ | ✅ | ✅|
58-
|OpenStack Manila | ✅ | | ✅ |
59-
|CIFS/SMB | | ✅ | |
60-
|VMware vSphere | ✅^[1]^ | | ✅^[2]^|
53+
|Microsoft Azure Disk | ✅ | | ✅ | ✅|
54+
|Microsoft Azure Stack Hub | ✅ | | ✅ | ✅|
55+
|Microsoft Azure File | ✅^[4]^ | | ✅^[4]^ | ✅| ✅
56+
|OpenStack Cinder | ✅ | | ✅ | ✅|
57+
|OpenShift Data Foundation | ✅ | ✅ | ✅ | ✅|
58+
|OpenStack Manila | ✅ | | | ✅ |
59+
|Shared Resource | | | | | ✅
60+
|CIFS/SMB | | | ✅ | |
61+
|VMware vSphere | ✅^[5]^ | | | ✅^[6]^|
6162
endif::openshift-dedicated,openshift-rosa[]
6263
|===
6364
ifndef::openshift-dedicated,openshift-rosa[]
6465
--
6566
1.
6667

67-
* Requires vSphere version 7.0 Update 3 or later for both vCenter Server and ESXi.
68-
69-
* Does not support fileshare volumes.
68+
:FeatureName: CSI volume group snapshots
69+
include::snippets/technology-preview.adoc[leveloffset=+1]
7070

7171
2.
7272

73-
* Offline volume expansion: minimum required vSphere version is 6.7 Update 3 P06
74-
75-
* Online volume expansion: minimum required vSphere version is 7.0 Update 2.
73+
* Cloning is not supported on hyperdisk-balanced disks with storage pools.
7674

7775
3.
7876

@@ -85,11 +83,16 @@ ifndef::openshift-dedicated,openshift-rosa[]
8583
* Azure File cloning and snapshot are Technology Preview features:
8684

8785
:FeatureName: Azure File CSI cloning and snapshot
88-
include::snippets/technology-preview.adoc[leveloffset=+2]
86+
include::snippets/technology-preview.adoc[leveloffset=+1]
8987

9088
5.
9189

92-
* Cloning is not supported on hyperdisk-balanced disks with storage pools.
90+
* Requires vSphere version 7.0 Update 3 or later for both vCenter Server and ESXi.
91+
92+
* Does not support fileshare volumes.
93+
94+
6.
9395

96+
* Online expansion is supported from vSphere version 7.0 Update 2 and later.
9497
--
9598
endif::openshift-dedicated,openshift-rosa[]

‎modules/persistent-storage-csi-group-snapshot-create-admin.adoc

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="persistent-storage-csi-group-snapshots-create-admin_{context}"]
7+
= Creating a volume group snapshot class
8+
9+
Before you can create volume group snapshots, the cluster administrator needs to create a `VolumeGroupSnapshotClass`.
10+
11+
This object describes how volume group snapshots should be created, including the driver information, the deletion policy, etc.
12+
13+
.Prerequisites
14+
* Logged in to a running {product-title} cluster with administrator privileges.
15+
16+
* Enabled this feature using feature gates. For information about how to use feature gates, see _Enabling features sets by using feature gates_.
17+
18+
.Procedure
19+
20+
To create a `VolumeGroupSnapshotClass`:
21+
22+
. Create a `VolumeGroupSnapshotClass` YAML file using the following example file:
23+
+
24+
.Example volume group snapshot class YAML file
25+
[source, yaml]
26+
----
27+
apiVersion: groupsnapshot.storage.k8s.io/v1beta1
28+
kind: VolumeGroupSnapshotClass <1>
29+
metadata:
30+
name: csi-hostpath-groupsnapclass <2>
31+
deletionPolicy: Delete
32+
driver: hostpath.csi.k8s.io
33+
…...
34+
----
35+
<1> Specifies the `VolumeGroupSnapshotClass` object.
36+
<2> Name of the `VolumeGroupSnapshotClass`.
37+
38+
. Create the 'VolumeGroupSnapshotClass' object by running the following command:
39+
+
40+
[source,terminal]
41+
----
42+
$ oc create -f <volume-group-snapshot-class-filename>.yaml
43+
----

‎modules/persistent-storage-csi-group-snapshots-create.adoc

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="persistent-storage-csi-group-snapshots-create_{context}"]
7+
= Creating a volume group snapshot
8+
9+
When you create a `VolumeGroupSnapshot` object, {product-title} creates a volume group snapshot.
10+
11+
.Prerequisites
12+
* Logged in to a running {product-title} cluster.
13+
* Enabled this feature using feature gates. For information about how to use feature gates, see _Enabling features sets by using feature gates_.
14+
* The persistent volume claims (PVCs) that you want to group for the snapshot have been created using a CSI driver that supports `VolumeGroupSnapshot` objects.
15+
* A storage class to provision the storage back end.
16+
* Administrator has created the `VolumeGroupSnapshotClass` object.
17+
18+
.Procedure
19+
20+
To create a volume group snapshot:
21+
22+
. Locate (or create) the PVCs that you want to include in the volume group snapshot:
23+
+
24+
[source, terminal]
25+
----
26+
$ oc get pvc
27+
----
28+
+
29+
.Example command output
30+
+
31+
[source, terminal]
32+
----
33+
NAME STATUS VOLUME CAPACITY ACCESSMODES AGE
34+
pvc-0 Bound pvc-a42d7ea2-e3df-11ed-b5ea-0242ac120002 1Gi RWO 48s
35+
pvc-1 Bound pvc-a42d81b8-e3df-11ed-b5ea-0242ac120002 1Gi RWO 48S
36+
----
37+
+
38+
This example uses two PVCs
39+
40+
. Label the PVCs to belong to a snapshot group:
41+
.. Label PVC pvc-0 by running the following command:
42+
+
43+
[source, terminal]
44+
----
45+
$ oc label pvc pvc-0 group=myGroup
46+
----
47+
+
48+
.Example output
49+
[source, terminal]
50+
----
51+
persistentvolumeclaim/pvc-0 labeled
52+
----
53+
.. Label PVC pvc-1 by running the following command:
54+
+
55+
[source, terminal]
56+
----
57+
$ oc label pvc pvc-1 group=myGroup
58+
----
59+
+
60+
.Example output
61+
[source, terminal]
62+
----
63+
persistentvolumeclaim/pvc-1 labeled
64+
----
65+
+
66+
In this example, you are labeling PVC "pvc-0" and "pvc-1" to belong to group "myGroup".
67+
68+
. Create a `VolumeGroupSnapshot` object to specify your volume group snapshot:
69+
.. Create a `VolumeGroupSnapshot` object YAML file with the following example file:
70+
+
71+
.Example VolumeGroupSnapshot YAML file
72+
[source, yaml]
73+
----
74+
apiVersion: groupsnapshot.storage.k8s.io/v1beta1
75+
kind: VolumeGroupSnapshot <1>
76+
metadata:
77+
name: <volume-group-snapshot-name> <2>
78+
namespace: <namespace> <3>
79+
spec:
80+
volumeGroupSnapshotClassName: <volume-group-snapshot-class-name> <4>
81+
source:
82+
selector:
83+
matchLabels:
84+
group: myGroup <5>
85+
----
86+
<1> The `VolumeGroupSnapshot` object requests creation of a volume group snapshot for multiple PVCs.
87+
<2> Name of the volume group snapshot.
88+
<3> Namespace for the volume group snapshot.
89+
<4> The `VolumeGroupSnapshotClass` name. This object is created by the administrator and describes how volume group snapshots should be created.
90+
<5> The name of the label used to group the desired PVCs for the snapshot. In this example, it is "myGroup".
91+
92+
.. Create the `VolumeGroupSnapshot` object by running the following command:
93+
+
94+
[source,terminal]
95+
----
96+
$ oc create -f <volume-group-snapshot-filename>.yaml
97+
----
98+
99+
.Results
100+
Individual volume snapshots are created according to how many PVCs were specified as part of the volume group snapshot.
101+
102+
These individual volume snapshots are named with the following format: <hash of VolumeGroupSnaphotContentUUID+volumeHandle>:
103+
104+
.Example individual volume snapshot
105+
[source, yaml]
106+
----
107+
apiVersion: snapshot.storage.k8s.io/v1
108+
kind: VolumeSnapshot
109+
metadata:
110+
name: snapshot-4dc1c53a29538b36e85003503a4bcac5dbde4cff59e81f1e3bb80b6c18c3fd03
111+
namespace: default
112+
ownerReferences:
113+
- apiVersion: groupsnapshot.storage.k8s.io/v1beta1
114+
kind: VolumeGroupSnapshot
115+
name: my-groupsnapshot
116+
uid: ba2d60c5-5082-4279-80c2-daa85f0af354
117+
resourceVersion: "124503"
118+
uid: c0137282-f161-4e86-92c1-c41d36c6d04c
119+
spec:
120+
source:
121+
persistentVolumeClaimName:pvc-1
122+
status:
123+
volumeGroupSnapshotName: volume-group-snapshot-name
124+
----
125+
126+
In the preceding example, two individual volume snapshots are created as part of the volume group snapshot.
127+
128+
[source, terminal]
129+
----
130+
snapshot-4dc1c53a29538b36e85003503a4bcac5dbde4cff59e81f1e3bb80b6c18c3fd03
131+
snapshot-fbfe59eff570171765df664280910c3bf1a4d56e233a5364cd8cb0152a35965b
132+
----

‎modules/persistent-storage-csi-group-snapshots-limitations.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="persistent-storage-csi-group-snapshots-limitations_{context}"]
7+
= CSI volume group snapshots limitations
8+
9+
Volume group snapshots has the following limitations:
10+
11+
* Does not support reverting an existing persistent volume claim (PVC) to an earlier state represented by a snapshot It only supports provisioning a new volume from a snapshot.
12+
13+
* No guarantees of application consistency, for example, crash consistency, are provided beyond those provided by the storage system. For more information about application consistency, see link:https://github.com/kubernetes/community/blob/master/wg-data-protection/data-protection-workflows-white-paper.md#quiesce-and-unquiesce-hooks[Quiesce and Unquiesce Hooks].

‎modules/persistent-storage-csi-group-snapshots-overview.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-group-snapshots.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="persistent-storage-csi-group-snapshots-overview_{context}"]
7+
= Overview of CSI volume group snapshots
8+
9+
A _snapshot_ represents the state of the storage volume in a cluster at a particular point in time. Volume snapshots can be used to provision a new volume.
10+
11+
A _volume group snapshot_ uses a label selector to group multiple persistent volume claims for snapshotting. A volume group snapshot represents copies from multiple volumes that are taken at the same point-in-time. This can be useful for applications that contain multiple volumes.
12+
13+
Container Storage Interface (CSI) volume group snapshots needs to be supported by the CSI driver. {rh-storage} supports volume group snapshots.
14+
15+
Volume group snapshots provide three new API objects for managing snapshots:
16+
17+
`VolumeGroupSnapshot`::
18+
Requests creation of a volume group snapshot for multiple persistent volume claims. It contains information about the volume group snapshot operation, such as the timestamp when the volume group snapshot was taken, and whether it is ready to use.
19+
20+
`VolumeGroupSnapshotContent`::
21+
Created by the snapshot controller for a dynamically created volumeGroupSnapshot. It contains information about the volume group snapshot including the volume group snapshot ID. This object represents a provisioned resource on the cluster (a group snapshot). The `VolumeGroupSnapshotContent` object binds to the volume group snapshot for which it was created with a one-to-one mapping.
22+
23+
`VolumeGroupSnapshotClass`::
24+
Created by cluster administrators to describe how volume group snapshots should be created, including the driver information, the deletion policy, etc.
25+
26+
These three API kinds are defined as `CustomResourceDefinitions` (CRDs). These CRDs must be installed in a {product-title} cluster for a CSI driver to support volume group snapshots.

‎modules/persistent-storage-csi-group-snapshots-restore.adoc

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="persistent-storage-csi-group-snapshots-restore_{context}"]
7+
= Restoring a volume group snapshot
8+
9+
You can use the `VolumeGroupSnapshot` custom resource definition (CRD) content to restore the existing volumes to a previous state.
10+
11+
To restore existing volumes, you can request a new persistent volume claim (PVC) to be created from a `VolumeSnapshot` object that is part of a `VolumeGroupSnapshot`. This triggers provisioning of a new volume that is populated with data from the specified snapshot. Repeat this process until all volumes are created from all the snapshots that are part of a volume group snapshot.
12+
13+
.Prerequisites
14+
* Logged in to a running {product-title} cluster.
15+
* PVC has been created using a Container Storage Interface (CSI) driver that supports volume group snapshots.
16+
* A storage class to provision the storage back end.
17+
* A volume group snapshot has been created and is ready to use.
18+
19+
.Procedure
20+
21+
To restore existing volumes to a previous state from a volume group snapshot:
22+
23+
. Specify a `VolumeSnapshot` data source from a volume group snapshot for a PVC as shown in the following example:
24+
+
25+
.Example restore PVC YAML file
26+
[source, yaml]
27+
----
28+
apiVersion: v1
29+
kind: PersistentVolumeClaim
30+
metadata:
31+
name: <pvc-restore-name> <1>
32+
namespace: <namespace> <2>
33+
spec:
34+
storageClassName: csi-hostpath-sc
35+
dataSource:
36+
name: snapshot-fbfe59eff570171765df664280910c3bf1a4d56e233a5364cd8cb0152a35965b <3>
37+
kind: VolumeSnapshot <4>
38+
apiGroup: snapshot.storage.k8s.io <5>
39+
accessModes:
40+
- ReadWriteOnce
41+
resources:
42+
requests:
43+
storage: 1Gi
44+
----
45+
<1> Name of the restore PVC.
46+
<2> Name of the namespace.
47+
<3> Name of an individual volume snapshot that is part of the volume group snapshot to use as source.
48+
<4> Must be set to the `VolumeSnapshot` value.
49+
<5> Must be set to the `snapshot.storage.k8s.io` value
50+
51+
. Create the PVC by running the following command:
52+
+
53+
[source,terminal]
54+
----
55+
$ oc create -f <pvc-restore-filename>.yaml <1>
56+
----
57+
<1> Name of the PVC restore file specified in the preceding step.
58+
59+
. Verify that the restored PVC has been created by running the following command:
60+
+
61+
[source,terminal]
62+
----
63+
$ oc get pvc
64+
----
65+
+
66+
A new PVC with the name you specified in the first step appears.
67+
68+
. Repeat the procedure as needed until all volumes are created from all the snapshots that are part of a volume group snapshot.

0 commit comments

Comments
 (0)