From 87460e2bee1d181812ccc93954a2c0e4a7f38677 Mon Sep 17 00:00:00 2001 From: Lisa Pettyjohn Date: Thu, 25 Jun 2026 13:30:35 -0400 Subject: [PATCH] OSDOCS-16947#CQA work Stor3 - CSI group snapshots --- ...orage-csi-group-snapshot-create-admin.adoc | 16 ++++---- ...nt-storage-csi-group-snapshots-create.adoc | 34 ++++++++++------- ...orage-csi-group-snapshots-limitations.adoc | 5 ++- ...-storage-csi-group-snapshots-overview.adoc | 3 ++ ...t-storage-csi-group-snapshots-restore.adoc | 38 +++++++++++-------- ...ersistent-storage-csi-group-snapshots.adoc | 16 +++++++- 6 files changed, 70 insertions(+), 42 deletions(-) diff --git a/modules/persistent-storage-csi-group-snapshot-create-admin.adoc b/modules/persistent-storage-csi-group-snapshot-create-admin.adoc index 1f6003791723..d3d7ba00780a 100644 --- a/modules/persistent-storage-csi-group-snapshot-create-admin.adoc +++ b/modules/persistent-storage-csi-group-snapshot-create-admin.adoc @@ -7,9 +7,7 @@ = Creating a volume group snapshot class [role="_abstract"] -Before you can create volume group snapshots, the cluster administrator needs to create a `VolumeGroupSnapshotClass`. - -This object describes how volume group snapshots should be created, including the driver information, the deletion policy, etc. +Create a `VolumeGroupSnapshotClass` to define how volume group snapshots are provisioned, including the Container Storage Interface (CSI) driver and deletion policy. Cluster administrators must create this class before users can provision volume group snapshots. .Prerequisites * Logged in to a running {product-title} cluster with administrator privileges. @@ -18,23 +16,23 @@ This object describes how volume group snapshots should be created, including th .Procedure -To create a `VolumeGroupSnapshotClass`: - . Create a `VolumeGroupSnapshotClass` YAML file using the following example file: + .Example volume group snapshot class YAML file [source, yaml] ---- apiVersion: groupsnapshot.storage.k8s.io/v1beta2 -kind: VolumeGroupSnapshotClass <1> +kind: VolumeGroupSnapshotClass metadata: - name: csi-hostpath-groupsnapclass <2> + name: csi-hostpath-groupsnapclass deletionPolicy: Delete driver: hostpath.csi.k8s.io …... ---- -<1> Specifies the `VolumeGroupSnapshotClass` object. -<2> Name of the `VolumeGroupSnapshotClass`. +Where: ++ +* `kind`: Specifies the `VolumeGroupSnapshotClass` object. +* `metadata.name`: Name of the `VolumeGroupSnapshotClass`. . Create the 'VolumeGroupSnapshotClass' object by running the following command: + diff --git a/modules/persistent-storage-csi-group-snapshots-create.adoc b/modules/persistent-storage-csi-group-snapshots-create.adoc index 7bedfe3c2854..2e613a7b066c 100644 --- a/modules/persistent-storage-csi-group-snapshots-create.adoc +++ b/modules/persistent-storage-csi-group-snapshots-create.adoc @@ -7,6 +7,8 @@ = Creating a volume group snapshot [role="_abstract"] +Create a `VolumeGroupSnapshot` object to capture point-in-time copies of multiple persistent volume claims (PVCs). Label the PVCs to include, specify the `VolumeGroupSnapshotClass`, and use a selector to reference them. Individual `VolumeSnapshot` objects are created automatically for each PVC. + When you create a `VolumeGroupSnapshot` object, {product-title} creates a volume group snapshot. .Prerequisites @@ -18,8 +20,6 @@ When you create a `VolumeGroupSnapshot` object, {product-title} creates a volume .Procedure -To create a volume group snapshot: - . Locate (or create) the PVCs that you want to include in the volume group snapshot: + [source, terminal] @@ -27,7 +27,7 @@ To create a volume group snapshot: $ oc get pvc ---- + -.Example command output +.Example + [source, terminal] ---- @@ -73,22 +73,28 @@ In this example, you are labeling PVC "pvc-0" and "pvc-1" to belong to group "my [source, yaml] ---- apiVersion: groupsnapshot.storage.k8s.io/v1beta2 -kind: VolumeGroupSnapshot <1> +kind: VolumeGroupSnapshot metadata: - name: <2> - namespace: <3> + name: + namespace: spec: - volumeGroupSnapshotClassName: <4> + volumeGroupSnapshotClassName: source: selector: matchLabels: - group: myGroup <5> + group: myGroup ---- -<1> The `VolumeGroupSnapshot` object requests creation of a volume group snapshot for multiple PVCs. -<2> Name of the volume group snapshot. -<3> Namespace for the volume group snapshot. -<4> The `VolumeGroupSnapshotClass` name. This object is created by the administrator and describes how volume group snapshots should be created. -<5> The name of the label used to group the desired PVCs for the snapshot. In this example, it is "myGroup". +Where: ++ +* `kind`: The `VolumeGroupSnapshot` object requests creation of a volume group snapshot for multiple PVCs. + +* `metadata.name`: Name of the volume group snapshot. + +* `metadata.namespace`: Namespace for the volume group snapshot. + +* `spec.volumeGroupSnapshotClassName`: The `VolumeGroupSnapshotClass` name. This object is created by the administrator and describes how volume group snapshots should be created. + +* `spec.source.selector.matchLabels.group`: The name of the label used to group the required PVCs for the snapshot. In this example, it is "myGroup". .. Create the `VolumeGroupSnapshot` object by running the following command: + @@ -102,7 +108,7 @@ Individual volume snapshots are created according to how many PVCs were specifie These individual volume snapshots are named with the following format: : -.Example individual volume snapshot +.Example [source, yaml] ---- apiVersion: snapshot.storage.k8s.io/v1 diff --git a/modules/persistent-storage-csi-group-snapshots-limitations.adoc b/modules/persistent-storage-csi-group-snapshots-limitations.adoc index b9df79c62869..de18c85f9f19 100644 --- a/modules/persistent-storage-csi-group-snapshots-limitations.adoc +++ b/modules/persistent-storage-csi-group-snapshots-limitations.adoc @@ -6,8 +6,11 @@ [id="persistent-storage-csi-group-snapshots-limitations_{context}"] = CSI volume group snapshots limitations +[role="_abstract"] +Volume group snapshots have operational and consistency limitations that affect how you can use them for data protection and recovery. Understanding these constraints helps you design appropriate backup and recovery strategies for multi-volume applications. + Volume group snapshots has the following limitations: * 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. -* 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]. \ No newline at end of file +* 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 _Quiesce and Unquiesce Hooks_ under _Additional resources_. \ No newline at end of file diff --git a/modules/persistent-storage-csi-group-snapshots-overview.adoc b/modules/persistent-storage-csi-group-snapshots-overview.adoc index da8eec60735e..a0ca31b28eff 100644 --- a/modules/persistent-storage-csi-group-snapshots-overview.adoc +++ b/modules/persistent-storage-csi-group-snapshots-overview.adoc @@ -6,6 +6,9 @@ [id="persistent-storage-csi-group-snapshots-overview_{context}"] = Overview of CSI volume group snapshots +[role="_abstract"] +Volume group snapshots capture point-in-time copies of multiple persistent volume claims using label selectors. Three API objects manage snapshots: VolumeGroupSnapshot, VolumeGroupSnapshotContent, and VolumeGroupSnapshotClass. Container Storage Interface driver support is required. + 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. 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. diff --git a/modules/persistent-storage-csi-group-snapshots-restore.adoc b/modules/persistent-storage-csi-group-snapshots-restore.adoc index 0437ce6e1be0..f1f4ab46c6e6 100644 --- a/modules/persistent-storage-csi-group-snapshots-restore.adoc +++ b/modules/persistent-storage-csi-group-snapshots-restore.adoc @@ -6,7 +6,8 @@ [id="persistent-storage-csi-group-snapshots-restore_{context}"] = Restoring a volume group snapshot -You can use the `VolumeGroupSnapshot` custom resource definition (CRD) content to restore the existing volumes to a previous state. +[role="_abstract"] +Restore volumes from a volume group snapshot by creating new persistent volume claims (PVCs) from individual `VolumeSnapshot` objects. Each PVC provisions a volume populated with snapshot data. Repeat for each `VolumeSnapshot` in the group to restore all volumes to their previous state. 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. @@ -18,8 +19,6 @@ To restore existing volumes, you can request a new persistent volume claim (PVC) .Procedure -To restore existing volumes to a previous state from a volume group snapshot: - . Specify a `VolumeSnapshot` data source from a volume group snapshot for a PVC as shown in the following example: + .Example restore PVC YAML file @@ -28,33 +27,40 @@ To restore existing volumes to a previous state from a volume group snapshot: apiVersion: v1 kind: PersistentVolumeClaim metadata: - name: <1> - namespace: <2> + name: + namespace: spec: storageClassName: csi-hostpath-sc dataSource: - name: snapshot-fbfe59eff570171765df664280910c3bf1a4d56e233a5364cd8cb0152a35965b <3> - kind: VolumeSnapshot <4> - apiGroup: snapshot.storage.k8s.io <5> + name: snapshot-fbfe59eff570171765df664280910c3bf1a4d56e233a5364cd8cb0152a35965b + kind: VolumeSnapshot + apiGroup: snapshot.storage.k8s.io accessModes: - ReadWriteOnce resources: requests: storage: 1Gi ---- -<1> Name of the restore PVC. -<2> Name of the namespace. -<3> Name of an individual volume snapshot that is part of the volume group snapshot to use as source. -<4> Must be set to the `VolumeSnapshot` value. -<5> Must be set to the `snapshot.storage.k8s.io` value ++ +Where: ++ +* `metadata.name`: Name of the restore PVC. + +* `metadata.namespace`: Name of the namespace. + +* `spec.dataSource.name`: Name of an individual volume snapshot that is part of the volume group snapshot to use as source. + +* `spec.dataSource.kind`: Must be set to the `VolumeSnapshot` value. + +* `spec.dataSource.apiGroup`: Must be set to the `snapshot.storage.k8s.io` value. . Create the PVC by running the following command: + [source,terminal] ---- -$ oc create -f .yaml <1> +$ oc create -f .yaml ---- -<1> Name of the PVC restore file specified in the preceding step. +Where `.yaml` is the name of the PVC restore file specified in the preceding step. . Verify that the restored PVC has been created by running the following command: + @@ -63,6 +69,6 @@ $ oc create -f .yaml <1> $ oc get pvc ---- + -A new PVC with the name you specified in the first step appears. +A new PVC with the name you specified in the first step is displayed. . Repeat the procedure as needed until all volumes are created from all the snapshots that are part of a volume group snapshot. diff --git a/storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc b/storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc index 329e1645b693..00a0768e662e 100644 --- a/storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc +++ b/storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc @@ -6,24 +6,36 @@ include::_attributes/common-attributes.adoc[] toc::[] -This document describes how to use volume group snapshots with supported Container Storage Interface (CSI) drivers to help protect against data loss in {product-title}. Familiarity with xref:../../storage/understanding-persistent-storage.adoc#persistent-volumes_understanding-persistent-storage[persistent volumes] is suggested. +[role="_abstract"] +Volume group snapshots capture point-in-time copies of multiple volumes simultaneously, gathering data across related volumes. This enables restoring multi-volume applications to a previous state or provisioning new volume sets with the same data for testing or development purposes. + +Using volume group snapshots with supported Container Storage Interface (CSI) drivers helps protect against data loss in {product-title}. Familiarity with persistent volumes is suggested. For information about persistent volumes, see _Understanding persistent volumes_ under _Additional resources_. :FeatureName: CSI volume group snapshots include::snippets/technology-preview.adoc[leveloffset=+1] -To use this Technology Preview feature, you must xref:../../hosted_control_planes/hcp-using-feature-gates.adoc#hcp-enable-feature-sets_hcp-using-feature-gates[enable it using feature gates]. +To use this Technology Preview feature, you must enable it using feature gates. For information about using feature gates, see _Enabling features using feature gates_ under _Additional resources_. include::modules/persistent-storage-csi-group-snapshots-overview.adoc[leveloffset=+1] include::modules/persistent-storage-csi-group-snapshots-limitations.adoc[leveloffset=+1] +[role="_additional-resources"] +.Additional resources +* https://github.com/kubernetes/community/blob/master/wg-data-protection/data-protection-workflows-white-paper.md#quiesce-and-unquiesce-hooks[Quiesce and Unquiesce Hooks] + include::modules/persistent-storage-csi-group-snapshot-create-admin.adoc[leveloffset=+1] include::modules/persistent-storage-csi-group-snapshots-create.adoc[leveloffset=+1] include::modules/persistent-storage-csi-group-snapshots-restore.adoc[leveloffset=+1] +[role="_additional-resources"] == Additional resources +* xref:../../storage/understanding-persistent-storage.adoc#persistent-volumes_understanding-persistent-storage[Understanding persistent volumes] + +* xref:../../hosted_control_planes/hcp-using-feature-gates.adoc#hcp-enable-feature-sets_hcp-using-feature-gates[Enabling features using feature gates] + * xref:../../storage/container_storage_interface/persistent-storage-csi-snapshots.adoc#persistent-storage-csi-snapshots[CSI volume snapshots] * xref:../../hosted_control_planes/hcp-using-feature-gates.adoc#hcp-enable-feature-sets_hcp-using-feature-gates[Enabling features sets by using feature gates] \ No newline at end of file