From 74e7fd0cb2618dc6fcb2f8a766b5d58122b82aa1 Mon Sep 17 00:00:00 2001 From: Lisa Pettyjohn Date: Thu, 12 Dec 2024 13:00:08 -0500 Subject: [PATCH] OSDOCS-????#Group Volume Snapshots (GA) --- _topic_maps/_topic_map.yml | 2 + ...sistent-storage-csi-drivers-supported.adoc | 53 +++---- ...orage-csi-group-snapshot-create-admin.adoc | 43 ++++++ ...nt-storage-csi-group-snapshots-create.adoc | 132 ++++++++++++++++++ ...orage-csi-group-snapshots-limitations.adoc | 13 ++ ...-storage-csi-group-snapshots-overview.adoc | 26 ++++ ...t-storage-csi-group-snapshots-restore.adoc | 68 +++++++++ ...ersistent-storage-csi-group-snapshots.adoc | 29 ++++ 8 files changed, 341 insertions(+), 25 deletions(-) create mode 100644 modules/persistent-storage-csi-group-snapshot-create-admin.adoc create mode 100644 modules/persistent-storage-csi-group-snapshots-create.adoc create mode 100644 modules/persistent-storage-csi-group-snapshots-limitations.adoc create mode 100644 modules/persistent-storage-csi-group-snapshots-overview.adoc create mode 100644 modules/persistent-storage-csi-group-snapshots-restore.adoc create mode 100644 storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 4dc9eb18af..939fd0e1cb 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1764,6 +1764,8 @@ Topics: File: ephemeral-storage-csi-inline - Name: CSI volume snapshots File: persistent-storage-csi-snapshots + - Name: CSI volume group snapshots + File: persistent-storage-csi-group-snapshots - Name: CSI volume cloning File: persistent-storage-csi-cloning - Name: Managing the default storage class diff --git a/modules/persistent-storage-csi-drivers-supported.adoc b/modules/persistent-storage-csi-drivers-supported.adoc index f055d83835..de1f0dac21 100644 --- a/modules/persistent-storage-csi-drivers-supported.adoc +++ b/modules/persistent-storage-csi-drivers-supported.adoc @@ -35,44 +35,42 @@ In addition to the drivers listed in the following table, ROSA functions with CS endif::openshift-rosa,openshift-aro[] .Supported CSI drivers and features in {product-title} -[cols=",^v,^v,^v,^v,^v width="100%",options="header"] +[cols=",^v,^v,^v,^v,^v,^v width="100%",options="header"] |=== -|CSI driver |CSI volume snapshots |CSI cloning |CSI resize |Inline ephemeral volumes -|AWS EBS | ✅ | | ✅| -|AWS EFS | | | | +|CSI driver |CSI volume snapshots |CSI volume group snapshots ^[1]^ |CSI cloning |CSI resize |Inline ephemeral volumes +|AWS EBS | ✅ | | | ✅| +|AWS EFS | | | | | ifndef::openshift-rosa[] -|Google Compute Platform (GCP) persistent disk (PD)| ✅| ✅^[5]^ | ✅| -|GCP Filestore | ✅ | | ✅| +|Google Compute Platform (GCP) persistent disk (PD)| ✅| |✅^[2]^ | ✅| +|GCP Filestore | ✅ | | | ✅| endif::openshift-rosa[] ifndef::openshift-dedicated,openshift-rosa[] -|{ibm-power-server-name} Block | | | ✅ | -|{ibm-cloud-name} Block | ✅^[3]^ | | ✅^[3]^| +|{ibm-power-server-name} Block | | | | ✅ | +|{ibm-cloud-name} Block | ✅^[3]^ | | | ✅^[3]^| endif::openshift-dedicated,openshift-rosa[] -|LVM Storage | ✅ | ✅ | ✅ | +|LVM Storage | ✅ | | ✅ | ✅ | ifndef::openshift-dedicated,openshift-rosa[] -|Microsoft Azure Disk | ✅ | ✅ | ✅| -|Microsoft Azure Stack Hub | ✅ | ✅ | ✅| -|Microsoft Azure File | ✅^[4]^ | ✅^[4]^ | ✅| ✅ -|OpenStack Cinder | ✅ | ✅ | ✅| -|OpenShift Data Foundation | ✅ | ✅ | ✅| -|OpenStack Manila | ✅ | | ✅ | -|CIFS/SMB | | ✅ | | -|VMware vSphere | ✅^[1]^ | | ✅^[2]^| +|Microsoft Azure Disk | ✅ | | ✅ | ✅| +|Microsoft Azure Stack Hub | ✅ | | ✅ | ✅| +|Microsoft Azure File | ✅^[4]^ | | ✅^[4]^ | ✅| ✅ +|OpenStack Cinder | ✅ | | ✅ | ✅| +|OpenShift Data Foundation | ✅ | ✅ | ✅ | ✅| +|OpenStack Manila | ✅ | | | ✅ | +|Shared Resource | | | | | ✅ +|CIFS/SMB | | | ✅ | | +|VMware vSphere | ✅^[5]^ | | | ✅^[6]^| endif::openshift-dedicated,openshift-rosa[] |=== ifndef::openshift-dedicated,openshift-rosa[] -- 1. -* Requires vSphere version 7.0 Update 3 or later for both vCenter Server and ESXi. - -* Does not support fileshare volumes. +:FeatureName: CSI volume group snapshots +include::snippets/technology-preview.adoc[leveloffset=+1] 2. -* Offline volume expansion: minimum required vSphere version is 6.7 Update 3 P06 - -* Online volume expansion: minimum required vSphere version is 7.0 Update 2. +* Cloning is not supported on hyperdisk-balanced disks with storage pools. 3. @@ -85,11 +83,16 @@ ifndef::openshift-dedicated,openshift-rosa[] * Azure File cloning and snapshot are Technology Preview features: :FeatureName: Azure File CSI cloning and snapshot -include::snippets/technology-preview.adoc[leveloffset=+2] +include::snippets/technology-preview.adoc[leveloffset=+1] 5. -* Cloning is not supported on hyperdisk-balanced disks with storage pools. +* Requires vSphere version 7.0 Update 3 or later for both vCenter Server and ESXi. +* Does not support fileshare volumes. + +6. + +* Online expansion is supported from vSphere version 7.0 Update 2 and later. -- endif::openshift-dedicated,openshift-rosa[] \ No newline at end of file diff --git a/modules/persistent-storage-csi-group-snapshot-create-admin.adoc b/modules/persistent-storage-csi-group-snapshot-create-admin.adoc new file mode 100644 index 0000000000..2ace7dae60 --- /dev/null +++ b/modules/persistent-storage-csi-group-snapshot-create-admin.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc + +:_mod-docs-content-type: PROCEDURE +[id="persistent-storage-csi-group-snapshots-create-admin_{context}"] += Creating a volume group snapshot class + +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. + +.Prerequisites +* Logged in to a running {product-title} cluster with administrator privileges. + +* Enabled this feature using feature gates. For information about how to use feature gates, see _Enabling features sets by using feature gates_. + +.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/v1beta1 +kind: VolumeGroupSnapshotClass <1> +metadata: + name: csi-hostpath-groupsnapclass <2> +deletionPolicy: Delete +driver: hostpath.csi.k8s.io + …... +---- +<1> Specifies the `VolumeGroupSnapshotClass` object. +<2> Name of the `VolumeGroupSnapshotClass`. + +. Create the 'VolumeGroupSnapshotClass' object by running the following command: ++ +[source,terminal] +---- +$ oc create -f .yaml +---- diff --git a/modules/persistent-storage-csi-group-snapshots-create.adoc b/modules/persistent-storage-csi-group-snapshots-create.adoc new file mode 100644 index 0000000000..0ceb001bb3 --- /dev/null +++ b/modules/persistent-storage-csi-group-snapshots-create.adoc @@ -0,0 +1,132 @@ +// Module included in the following assemblies: +// +// * storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc + +:_mod-docs-content-type: PROCEDURE +[id="persistent-storage-csi-group-snapshots-create_{context}"] += Creating a volume group snapshot + +When you create a `VolumeGroupSnapshot` object, {product-title} creates a volume group snapshot. + +.Prerequisites +* Logged in to a running {product-title} cluster. +* Enabled this feature using feature gates. For information about how to use feature gates, see _Enabling features sets by using feature gates_. +* The persistent volume claims (PVCs) that you want to group for the snapshot have been created using a CSI driver that supports `VolumeGroupSnapshot` objects. +* A storage class to provision the storage back end. +* Administrator has created the `VolumeGroupSnapshotClass` object. + +.Procedure + +To create a volume group snapshot: + +. Locate (or create) the PVCs that you want to include in the volume group snapshot: ++ +[source, terminal] +---- +$ oc get pvc +---- ++ +.Example command output ++ +[source, terminal] +---- +NAME STATUS VOLUME CAPACITY ACCESSMODES AGE +pvc-0 Bound pvc-a42d7ea2-e3df-11ed-b5ea-0242ac120002 1Gi RWO 48s +pvc-1 Bound pvc-a42d81b8-e3df-11ed-b5ea-0242ac120002 1Gi RWO 48S +---- ++ +This example uses two PVCs + +. Label the PVCs to belong to a snapshot group: +.. Label PVC pvc-0 by running the following command: ++ +[source, terminal] +---- +$ oc label pvc pvc-0 group=myGroup +---- ++ +.Example output +[source, terminal] +---- +persistentvolumeclaim/pvc-0 labeled +---- +.. Label PVC pvc-1 by running the following command: ++ +[source, terminal] +---- +$ oc label pvc pvc-1 group=myGroup +---- ++ +.Example output +[source, terminal] +---- +persistentvolumeclaim/pvc-1 labeled +---- ++ +In this example, you are labeling PVC "pvc-0" and "pvc-1" to belong to group "myGroup". + +. Create a `VolumeGroupSnapshot` object to specify your volume group snapshot: +.. Create a `VolumeGroupSnapshot` object YAML file with the following example file: ++ +.Example VolumeGroupSnapshot YAML file +[source, yaml] +---- +apiVersion: groupsnapshot.storage.k8s.io/v1beta1 +kind: VolumeGroupSnapshot <1> +metadata: + name: <2> + namespace: <3> +spec: + volumeGroupSnapshotClassName: <4> + source: + selector: + matchLabels: + group: myGroup <5> +---- +<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". + +.. Create the `VolumeGroupSnapshot` object by running the following command: ++ +[source,terminal] +---- +$ oc create -f .yaml +---- + +.Results +Individual volume snapshots are created according to how many PVCs were specified as part of the volume group snapshot. + +These individual volume snapshots are named with the following format: : + +.Example individual volume snapshot +[source, yaml] +---- +apiVersion: snapshot.storage.k8s.io/v1 +kind: VolumeSnapshot +metadata: + name: snapshot-4dc1c53a29538b36e85003503a4bcac5dbde4cff59e81f1e3bb80b6c18c3fd03 + namespace: default + ownerReferences: + - apiVersion: groupsnapshot.storage.k8s.io/v1beta1 + kind: VolumeGroupSnapshot + name: my-groupsnapshot + uid: ba2d60c5-5082-4279-80c2-daa85f0af354 + resourceVersion: "124503" + uid: c0137282-f161-4e86-92c1-c41d36c6d04c +spec: + source: + persistentVolumeClaimName:pvc-1 +status: + volumeGroupSnapshotName: volume-group-snapshot-name +---- + +In the preceding example, two individual volume snapshots are created as part of the volume group snapshot. + +[source, terminal] +---- +snapshot-4dc1c53a29538b36e85003503a4bcac5dbde4cff59e81f1e3bb80b6c18c3fd03 +snapshot-fbfe59eff570171765df664280910c3bf1a4d56e233a5364cd8cb0152a35965b +---- \ No newline at end of file diff --git a/modules/persistent-storage-csi-group-snapshots-limitations.adoc b/modules/persistent-storage-csi-group-snapshots-limitations.adoc new file mode 100644 index 0000000000..b9df79c628 --- /dev/null +++ b/modules/persistent-storage-csi-group-snapshots-limitations.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc + +:_mod-docs-content-type: CONCEPT +[id="persistent-storage-csi-group-snapshots-limitations_{context}"] += CSI volume group snapshots limitations + +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 diff --git a/modules/persistent-storage-csi-group-snapshots-overview.adoc b/modules/persistent-storage-csi-group-snapshots-overview.adoc new file mode 100644 index 0000000000..da8eec6073 --- /dev/null +++ b/modules/persistent-storage-csi-group-snapshots-overview.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc + +:_mod-docs-content-type: CONCEPT +[id="persistent-storage-csi-group-snapshots-overview_{context}"] += Overview of CSI volume group snapshots + +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. + +Container Storage Interface (CSI) volume group snapshots needs to be supported by the CSI driver. {rh-storage} supports volume group snapshots. + +Volume group snapshots provide three new API objects for managing snapshots: + +`VolumeGroupSnapshot`:: +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. + +`VolumeGroupSnapshotContent`:: +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. + +`VolumeGroupSnapshotClass`:: +Created by cluster administrators to describe how volume group snapshots should be created, including the driver information, the deletion policy, etc. + +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. \ No newline at end of file diff --git a/modules/persistent-storage-csi-group-snapshots-restore.adoc b/modules/persistent-storage-csi-group-snapshots-restore.adoc new file mode 100644 index 0000000000..0437ce6e1b --- /dev/null +++ b/modules/persistent-storage-csi-group-snapshots-restore.adoc @@ -0,0 +1,68 @@ +// Module included in the following assemblies: +// +// * storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc + +:_mod-docs-content-type: PROCEDURE +[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. + +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. + +.Prerequisites +* Logged in to a running {product-title} cluster. +* PVC has been created using a Container Storage Interface (CSI) driver that supports volume group snapshots. +* A storage class to provision the storage back end. +* A volume group snapshot has been created and is ready to use. + +.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 +[source, yaml] +---- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: <1> + namespace: <2> +spec: + storageClassName: csi-hostpath-sc + dataSource: + name: snapshot-fbfe59eff570171765df664280910c3bf1a4d56e233a5364cd8cb0152a35965b <3> + kind: VolumeSnapshot <4> + apiGroup: snapshot.storage.k8s.io <5> + 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 + +. Create the PVC by running the following command: ++ +[source,terminal] +---- +$ oc create -f .yaml <1> +---- +<1> Name of the PVC restore file specified in the preceding step. + +. Verify that the restored PVC has been created by running the following command: ++ +[source,terminal] +---- +$ oc get pvc +---- ++ +A new PVC with the name you specified in the first step appears. + +. 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 new file mode 100644 index 0000000000..329e1645b6 --- /dev/null +++ b/storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc @@ -0,0 +1,29 @@ +:_mod-docs-content-type: ASSEMBLY +[id="persistent-storage-csi-group-snapshots"] += CSI volume group snapshots +include::_attributes/common-attributes.adoc[] +:context: persistent-storage-csi-group-snapshots + +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. + +: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]. + +include::modules/persistent-storage-csi-group-snapshots-overview.adoc[leveloffset=+1] + +include::modules/persistent-storage-csi-group-snapshots-limitations.adoc[leveloffset=+1] + +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] + +== Additional resources +* 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