Merge pull request #62557 from ShaunaDiaz/OSDOCS-6534

OSDOCS-6534: adding CSI snapshotting

Author: michaelryanpeter

_topic_maps/_topic_map_ms.yml

@@ -142,6 +142,8 @@ Topics:
   File: expanding-persistent-volumes-microshift
 - Name: Dynamic storage using the LVMS plugin
   File: microshift-storage-plugin-overview
+- Name: Working with volume snapshots
+  File: volume-snapshots-microshift
 ---
 Name: Running applications
 Dir: microshift_running_apps

microshift_storage/container_storage_interface_microshift/_attributes renamed to _unused_topics/container_storage_interface_microshift/_attributes

@@ -18,4 +18,6 @@ include::modules/microshift-lvmd-yaml-creating.adoc[leveloffset=+1]
 
 include::modules/microshift-lvms-config-example-basic.adoc[leveloffset=+1]
 
-include::modules/microshift-lvms-using.adoc[leveloffset=+1]
+include::modules/microshift-lvms-using.adoc[leveloffset=+1]
+
+include::modules/microshift-storage-device-classes.adoc[leveloffset=+2]

microshift_storage/container_storage_interface_microshift/images renamed to _unused_topics/container_storage_interface_microshift/images

@@ -0,0 +1,98 @@
+:_content-type: ASSEMBLY
+[id="working-with-volume-snapshots-microshift"]
+= Working with volume snapshots
+include::_attributes/attributes-microshift.adoc[]
+:context: volume-snapshots-microshift
+
+toc::[]
+
+Cluster administrators can use volume snapshots to help protect against data loss by using the supported {product-title} logical volume manager storage (LVMS) Container Storage Interface (CSI) provider. Familiarity with xref:../microshift_storage/understanding-persistent-storage-microshift.adoc#persistent-volumes_understanding-persistent-storage-microshift[persistent volumes] is required.
+
+A snapshot represents the state of the storage volume in a cluster at a particular point in time. Volume snapshots can also be used to provision new volumes. Snapshots are created as read-only logical volumes (LVs) located on the same device as the original data.
+
+A cluster administrator can complete the following tasks using CSI volume snapshots:
+
+* Create a snapshot of an existing persistent volume claim (PVC).
+* Back up a volume snapshot to a secure location.
+* Restore a volume snapshot as a different PVC.
+* Delete an existing volume snapshot.
+
+[IMPORTANT]
+====
+Only the logical volume manager storage (LVMS) plugin CSI driver is supported by {product-title}.
+====
+
+//additional resources for assembly intro; trailing because 1) relevant here, 2) TOC levels, and 2) last called module has addt'l resources
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../microshift_storage/understanding-persistent-storage-microshift.adoc#persistent-volumes_understanding-persistent-storage-microshift[Understanding persistent volumes]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html/configuring_and_managing_logical_volumes/creating-and-managing-thin-provisioned-volumes_configuring-and-managing-logical-volumes[Configuring and managing logical volumes]
+
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/storage/using-container-storage-interface-csi#persistent-storage-csi-snapshots[CSI snapshots: `VolumeSnapshot` APIs]
+
+* link:https://docs.openshift.com/container-platform/{ocp-version}/rest_api/storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.html[VolumeSnapshot API specification]
+
+include::modules/microshift-lvm-thin-volumes.adoc[leveloffset=+1]
+
+//additional resources for thin volumes module
+[role="_additional-resources"]
+.Additional resources
+
+* To create a thin pool on the host, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html/configuring_and_managing_logical_volumes/creating-and-managing-thin-provisioned-volumes_configuring-and-managing-logical-volumes[Creating and managing thin provisioned volumes]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html/configuring_and_managing_logical_volumes/creating-and-managing-thin-provisioned-volumes_configuring-and-managing-logical-volumes#creating-thinly-provisioned-logical-volumes_creating-and-managing-thin-provisioned-volumes[Creating thinly provisioned logical volumes]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/{op-system-version-major}/html/configuring_and_managing_logical_volumes/creating-and-managing-thin-provisioned-volumes_configuring-and-managing-logical-volumes[Configuring and managing thin provisioned volumes]
+
+* xref:../microshift_storage/volume-snapshots-microshift.adoc#microshift-storage-classes_volume-snapshots-microshift[Storage classes]
+
+* xref:../microshift_storage/microshift-storage-plugin-overview.adoc#microshift-storage-device-classes_microshift-storage-plugin-overview[Storage device classes]
+
+include::modules/microshift-storage-classes.adoc[leveloffset=+2]
+
+//additional resources for storage classes module
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/storage/dynamic-provisioning#defining-storage-classes_dynamic-provisioning[Defining storage classes]
+
+* xref:../microshift_storage/microshift-storage-plugin-overview.adoc#microshift-storage-device-classes_microshift-storage-plugin-overview[Storage device classes]
+
+include::modules/microshift-storage-vol-snapshot-class.adoc[leveloffset=+1]
+
+//additional resources for volume snapshot classes module
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://docs.openshift.com/container-platform/{ocp-version}/storage/container_storage_interface/persistent-storage-csi-snapshots.html#volume-snapshot-crds[OpenShift CSI volume snapshots]
+
+include::modules/microshift-storage-about-vol-snapshots.adoc[leveloffset=+1]
+
+include::modules/microshift-storage-creating-vol-snapshot.adoc[leveloffset=+2]
+
+include::modules/microshift-storage-backup-volume-snapshots.adoc[leveloffset=+2]
+
+include::modules/microshift-storage-vol-snapshot-restore.adoc[leveloffset=+2]
+
+//additional resources for volume snapshot restore module
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/storage/using-container-storage-interface-csi#persistent-storage-csi-snapshots-provision_persistent-storage-csi-snapshots[Restoring a volume snapshot]
+
+//this module is reused from OCP; take care in editing for MicroShift
+include::modules/persistent-storage-csi-snapshots-delete.adoc[leveloffset=+2]
+
+include::modules/microshift-storage-volume-cloning.adoc[leveloffset=+1]
+
+//additional resources for volume cloning module
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://docs.openshift.com/container-platform/{ocp-version}/storage/container_storage_interface/persistent-storage-csi-cloning.html[CSI volume cloning]
+
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/storage/configuring-persistent-storage#lvms-creating-volume-clones-in-single-node-openshift_logical-volume-manager-storage[LVMS volume cloning for Single-Node OpenShift]
+
+* To configure the host to enable cloning, see xref:../microshift_storage/volume-snapshots-microshift.adoc#microshift-lvm-thin-volumes_volume-snapshots-microshift[About LVM thin volumes]

microshift_storage/container_storage_interface_microshift/microshift-persistent-storage-csi.adoc renamed to _unused_topics/container_storage_interface_microshift/microshift-persistent-storage-csi.adoc

@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//
+// * microshift_storage/volume-snapshots-microshift.adoc
+
+:_content-type: CONCEPT
+[id="microshift-lvm-thin-volumes_{context}"]
+= About LVM thin volumes
+
+To use advanced storage features such as creating volume snapshots or volume cloning, you must perform the following actions:
+
+* Configure both the logical volume manager storage (LVMS) provider and the cluster.
+* Provision a logical volume manager (LVM) thin-pool on the {op-system-ostree} host.
+* Attach LVM thin-pools to a volume group.
+
+[IMPORTANT]
+====
+To create Container Storage Interface (CSI) snapshots, you must configure thin volumes on the {op-system-ostree} host. The CSI does not support volume shrinking.
+====
+
+For LVMS to manage thin logical volumes (LVs), a thin-pool `device-class` array must be specified in the `etc/lvmd.yaml` configuration file. Multiple thin-pool device classes are permitted.
+
+If additional storage pools are configured with device classes, then additional storage classes must also exist to expose the storage pools to users and workloads. To enable dynamic provisioning on a thin-pool, a `StorageClass` resource must be present on the cluster. The `StorageClass` resource specifies the source `device-class` array in the `topolvm.io/device-class` parameter.
+
+.Example `lvmd.yaml` file that specifies a single device class for a thin-pool
+
+[source, yaml]
+----
+socket-name: <1>
+device-classes: <2>
+  - name: thin <3>
+    default: true
+    spare-gb: 0 <4>
+    thin-pool:
+      name: thin
+      overprovision-ratio: 10 <5>
+    type: thin <6>
+    volume-group: ssd <7>
+----
+[.small]
+<1> String. The UNIX domain socket endpoint of gRPC. Defaults to `/run/lvmd/lvmd.socket`.
+<2> A list of maps for the settings for each `device-class`.
+<3> String. The unique name of the `device-class`.
+<4> Unsigned 64-bit integer. Storage capacity in GB to be left unallocated in the volume group. Defaults to `0`.
+<5> If you have multiple thin-provisioned devices that share the same pool, then these devices can be over-provisioned. Over-provisioning requires a float value of 1 or greater.
+<6> Thin provisioning is required to create volume snapshots.
+<7> String. The group where the `device-class` creates the logical volumes.
+
+[IMPORTANT]
+====
+When multiple PVCs are created simultaneously, a race condition prevents LVMS from accurately tracking the allocated space and preserving the storage capacity for a device class. Use separate volume groups and device classes to protect the storage of highly dynamic workloads from each other.
+====

microshift_storage/container_storage_interface_microshift/modules renamed to _unused_topics/container_storage_interface_microshift/modules

@@ -8,6 +8,11 @@
 
 {product-title} supports passing through your LVM configuration and allows you to specify custom volume groups, thin volume provisioning parameters, and reserved unallocated volume group space. You can edit the LVMS configuration file you created at any time. You must restart {product-title} to deploy configuration changes after editing the file.
 
+[NOTE]
+====
+If you need to take volume snapshots, you must use thin provisioning in your `lvmd.conf` file. If you do not need to take volume snapshots, you can use thick volumes.
+====
+
 The following `lvmd.yaml` example file shows a basic LVMS configuration:
 
 .LVMS configuration example
@@ -25,7 +30,7 @@ device-classes: <2>
 <2> A list of maps for the settings for each `device-class`.
 <3> String. The name of the `device-class`.
 <4> String. The group where the `device-class` creates the logical volumes.
-<5> Unsigned 64-bit integer. Storage capacity in GiB to be left unallocated in the volume group. Defaults to `0`.
+<5> Unsigned 64-bit integer. Storage capacity in GB to be left unallocated in the volume group. Defaults to `0`.
 <6> Boolean. Indicates that the `device-class` is used by default. Defaults to `false`. At least one value must be entered in the YAML file values when this is set to `true`.
 
 [IMPORTANT]