Skip to content

OSDOCS-16947#CQA work Stor3 - CSI group snapshots #114215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lpettyjo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

OSDOCS-16947#CQA work Stor3 - CSI group snapshots #114215

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 7 additions & 9 deletions modules/persistent-storage-csi-group-snapshot-create-admin.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:
+
Expand Down
34 changes: 20 additions & 14 deletions modules/persistent-storage-csi-group-snapshots-create.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -18,16 +20,14 @@ 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]
----
$ oc get pvc
----
+
.Example command output
.Example
Comment thread
lpettyjo marked this conversation as resolved.
Comment thread
lpettyjo marked this conversation as resolved.
+
[source, terminal]
----
Expand Down Expand Up @@ -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: <volume-group-snapshot-name> <2>
namespace: <namespace> <3>
name: <volume-group-snapshot-name>
namespace: <namespace>
spec:
volumeGroupSnapshotClassName: <volume-group-snapshot-class-name> <4>
volumeGroupSnapshotClassName: <volume-group-snapshot-class-name>
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:
+
Expand All @@ -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: <hash of VolumeGroupSnaphotContentUUID+volumeHandle>:

.Example individual volume snapshot
.Example
[source, yaml]
----
apiVersion: snapshot.storage.k8s.io/v1
Expand Down
5 changes: 4 additions & 1 deletion modules/persistent-storage-csi-group-snapshots-limitations.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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_.
3 changes: 3 additions & 0 deletions modules/persistent-storage-csi-group-snapshots-overview.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
38 changes: 22 additions & 16 deletions modules/persistent-storage-csi-group-snapshots-restore.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -28,33 +27,40 @@ To restore existing volumes to a previous state from a volume group snapshot:
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: <pvc-restore-name> <1>
namespace: <namespace> <2>
name: <pvc-restore-name>
namespace: <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 <pvc-restore-filename>.yaml <1>
$ oc create -f <pvc-restore-filename>.yaml
----
<1> Name of the PVC restore file specified in the preceding step.
Where `<pvc-restore-filename>.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:
+
Expand All @@ -63,6 +69,6 @@ $ oc create -f <pvc-restore-filename>.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.
16 changes: 14 additions & 2 deletions storage/container_storage_interface/persistent-storage-csi-group-snapshots.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]