Merge pull request #72137 from sr1kar99/doc-improv-deleting-lvmcluster

/lgtm OCPBUGS#27147: Doc improvements related to "LVMCluster" custom resource

Author: JoeAldinger

modules/lvms-about-adding-devices-to-a-vg.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="about-adding-devices-to-a-vg_{context}"]
+= About adding devices to a volume group
+
+The `deviceSelector` field in the `LVMCluster` CR contains the configuration to specify the paths to the devices that you want to add to the LVM volume group.
+
+You can specify the device paths in the `deviceSelector.paths` field, the `deviceSelector.optionalPaths` field, or both. If you do not specify the device paths in both the `deviceSelector.paths` field and the `deviceSelector.optionalPaths` field, {lvms} adds the supported unused devices to the LVM volume group. 
+
+The devices that you want to add to the volume group must be supported by {lvms}. For information about unsupported devices, see "Devices not supported by {lvms}" in the "Additional resources" section.
+
+If you do not add the `deviceSelector` field in the `LVMCluster` CR, {lvms} automatically adds the new devices when the devices are available.
+
+{lvms} adds the devices to the LVM volume group only if the following conditions are met:
+
+* The device path exists.
+* The device is supported by {lvms}.
+
+You can also add the path to the RAID arrays to integrate the RAID arrays with {lvms}. For more information, see "Integrating RAID arrays with {lvms}" in the "Additional resources" section. 
+
+[IMPORTANT]
+====
+After a device is added to the LVM volume group, it cannot be removed.
+==== 

modules/lvms-about-creating-lvmcluster-cr.adoc

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="about-creating-lvmcluster-cr_{context}"]
+= Ways to create an LVMCluster custom resource
+
+You can create an `LVMCluster` custom resource (CR) by using the OpenShift CLI (`oc`) or the {product-title} web console. If you have installed {lvms} by using {rh-rhacm-first}, you can also create an `LVMCluster` CR by using {rh-rhacm}. 
+
+Upon creating the `LVMCluster` CR, {lvms} creates the following system-managed CRs:
+
+* A `storageClass` and `volumeSnapshotClass` for each device class.
++
+[NOTE]
+====
+{lvms} configures the name of the storage class and volume snapshot class in the format `lvms-<device_class_name>`, where, `<device_class_name>` is the value of the `deviceClasses.name` field in the `LVMCluster` CR. For example, if the `deviceClasses.name` field is set to vg1, the name of the storage class and volume snapshot class is `lvms-vg1`.
+====
+
+* `LVMVolumeGroup`: This CR is a specific type of persistent volume (PV) that is backed by an LVM volume group. It tracks the individual volume groups across multiple nodes.
+* `LVMVolumeGroupNodeStatus`: This CR tracks the status of the volume groups on a node.

modules/lvms-about-deleting-lvmcluster-cr.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="about-deleting-lvmcluster-cr_{context}"]
+= Ways to delete an LVMCluster custom resource
+
+You can delete an `LVMCluster` custom resource (CR) by using the OpenShift CLI (`oc`) or the {product-title} web console. If you have installed {lvms} by using {rh-rhacm-first}, you can also delete an `LVMCluster` CR by using {rh-rhacm}.
+
+Upon deleting the `LVMCluster` CR, {lvms} deletes the following CRs:
+
+* `storageClass`
+* `volumeSnapshotClass`
+* `LVMVolumeGroup`
+* `LVMVolumeGroupNodeStatus`

modules/lvms-about-lvm-storage-installation.adoc

@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="lvms-about-lvm-storage-installation_{context}"]
-= Installing Logical Volume Manager Storage
+= Logical Volume Manager Storage installation
 
 You can install Logical Volume Manager (LVM) Storage on a bare metal or user-provisioned infrastructure cluster and configure it to dynamically provision storage for your workloads.
 
@@ -29,4 +29,4 @@ The prerequisites to install {lvms} are as follows:
 You cannot wipe the disks that are in use.
 ====
 
-* If you want to install {lvms} by using {rh-rhacm-first}, ensure that you have installed {rh-rhacm} on an {product-title} cluster. See the _Installing LVM Storage using RHACM_ section.
+* If you want to install {lvms} by using {rh-rhacm-first}, ensure that you have installed {rh-rhacm} on an {product-title} cluster. See the "Installing LVM Storage using RHACM" section.

modules/lvms-about-lvmcluster-cr.adoc

@@ -6,21 +6,19 @@
 [id="about-lvmcluster_{context}"]
 = About the LVMCluster custom resource
 
-After you have installed {lvms}, you must create an `LVMCluster` custom resource (CR) on a worker node.
-
 You can configure the `LVMCluster` CR to perform the following actions:
 
 * Create LVM volume groups that you can use to provision persistent volume claims (PVCs).
 * Configure a list of devices that you want to add to the LVM volume groups. 
 * Configure the requirements to select the nodes on which you want to create an LVM volume group, and the thin pool configuration for the volume group.
 * Force wipe the selected devices.
 
-You can create an `LVMCluster` CR using the OpenShift CLI (`oc`) or the {product-title} web console.
+After you have installed {lvms}, you must create an `LVMCluster` custom resource (CR).
 
 include::snippets/lvms-creating-lvmcluster.adoc[]
 
 [discrete]
-== LVMCluster custom resource configuration
+== Explanation of fields in the LVMCluster CR
 
 The `LVMCluster` CR fields are described in the following table:
 
@@ -34,23 +32,13 @@ The `LVMCluster` CR fields are described in the following table:
 |`array`
 |Contains the configuration to assign the local storage devices to the LVM volume groups. 
 
-To create multiple device storage classes, create a device class for each storage class. 
+LVM Storage creates a storage class and volume snapshot class for each device class that you create. 
 
 |`deviceClasses.name`
 |`string`
 |Specify a name for the LVM volume group (VG). 
 
-If this field is set to the name of a VG from the previous {lvms} installation, {lvms} recreates the resources related to that volume group in the current {lvms} installation. 
-
-You can only recover the VGs but not the logical volume associated with the VG.
-
-[IMPORTANT]
-====
-Before recovering the VGs from the previous {lvms} installation, ensure that the following conditions are met:
-
-* VGs must not be corrupted.
-* VGs must have the `lvms` tag. For more information on adding tags to LVMS objects, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/configuring_and_managing_logical_volumes/grouping-lvm-objects-with-tags_configuring-and-managing-logical-volumes#doc-wrapper[Grouping LVM objects with tags].
-====
+You can also configure this field to reuse a volume group that you created in the previous installation. For more information, see "Reusing a volume group from the previous LVM Storage installation" in the "Additional resources" section.
 
 |`deviceClasses.fstype`
 |`string`
@@ -64,38 +52,20 @@ Before recovering the VGs from the previous {lvms} installation, ensure that the
 |`object`
 |Contains the configuration to choose the nodes on which you want to create the LVM volume group. If this field is empty, all nodes without no-schedule taints are considered.
 
-[NOTE]
-====
 On the control-plane node, {lvms} detects and uses the additional worker nodes when the new nodes become active in the cluster. 
-====
 
 |`nodeSelector.nodeSelectorTerms`
 |`array`
 |Configure the requirements that are used to select the node.
 
 |`deviceClasses.deviceSelector`
 |`object`
-|Contains the configuration to specify the paths to the devices that you want to add to the LVM volume group, and force wipe the devices that are added to the LVM volume group. 
-
-You can specify the device paths in the `paths` field, the `optionalPaths` field, or both. If you do not specify the device paths in both `paths` and `optionalPaths`, {lvms} adds the supported unused devices to the LVM volume group.
-
-[IMPORTANT]
-====
-After a device is added to the LVM volume group, it cannot be removed.
-==== 
-
-{lvms} adds the devices to the LVM volume group only if the following conditions are met:
-
-* The device path exists.
-
-* The device is supported by {lvms}.
+|Contains the configuration to perform the following actions:
 
-[NOTE]
-====
-The devices that you want to add to the volume group must be supported by {lvms}. For information about unsupported devices, see _Devices not supported by {lvms}_ in _Additional resources_.
-====
+* Specify the paths to the devices that you want to add to the LVM volume group.
+* Force wipe the devices that are added to the LVM volume group.
 
-You can also add the path to the RAID arrays to integrate the RAID arrays with {lvms}. For more information, see _Integrating RAID arrays with {lvms}_ in _Additional resources_. 
+For more information, see "About adding devices to a volume group" in the "Additional resources" section.
 
 |`deviceSelector.paths`
 |`array`
@@ -114,21 +84,18 @@ forceWipeDevicesAndDestroyAllData`
 |`boolean`
 |To force wipe the selected devices, set this field to `true`. By default, this field is set to `false`.
 
-[IMPORTANT]
+[WARNING]
 ====
+If this field is set to `true`, {lvms} wipes all previous data on the devices. Use this feature with caution.
+====
+
 Wiping the device can lead to inconsistencies in data integrity if any of the following conditions are met:
 
 * The device is being used as swap space.
 * The device is part of a RAID array.
 * The device is mounted.
 
 If any of these conditions are true, do not force wipe the disk. Instead, you must manually wipe the disk.
-====
-
-[WARNING]
-====
-If this field is set to `true`, {lvms} wipes all previous data on the devices. Use this feature with caution.
-====
 
 |`deviceClasses.thinPoolConfig`
 |`object`
@@ -154,26 +121,6 @@ To disable over-provisioning, set this field to 1.
 
 |====
 
-Upon creating the `LVMCluster` CR, {lvms} creates a storage class and volume snapshot class for each device class.
 
-[NOTE]
-====
-{lvms} configures the name of the storage class and volume snapshot class in the format `lvms-<device-class-name>`. Where, `<device-class-name>` is the value of the `deviceClasses.name` field in the `LVMCluster` CR. For example, if the `deviceClasses.name` field is set to vg1, the name of the storage class and volume snapshot class is `lvms-vg1`.
-
-To get the list of storage classes, run the following command:
-[source,terminal]
-----
-$ oc get storageclass
-----
-
-To get the list of volume snapshot classes, run the following command:
-[source,terminal]
-----
-$ oc get volumesnapshotclass
-----
-====
 
-Upon creating the `LVMCluster` CR, {lvms} creates the following system-managed CRs:
 
-* `LVMVolumeGroup`: This CR is a specific type of persistent volume (PV) that is backed by an LVM volume group. It tracks the individual volume groups across multiple nodes.
-* `LVMVolumeGroupNodeStatus`: This CR tracks the status of the volume groups on a node.

modules/lvms-about-scaling-storage-of-clusters.adoc

@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="lvms-about-scaling-storage-of-cluster_{context}"]
-= Scaling up the storage of clusters
+= Ways to scale up the storage of clusters
 
 {product-title} supports additional worker nodes for clusters on bare metal user-provisioned infrastructure. You can scale up the storage of clusters either by adding new worker nodes with available storage or by adding new devices to the existing worker nodes. 
 

modules/lvms-about-volume-snapshots.adoc

@@ -14,7 +14,7 @@ You can perform the following actions using the volume snapshots:
 +
 [IMPORTANT]
 ====
-Volume snapshots are located on the same devices as the original data. To use the volume snapshots as backups, you must move the snapshots to a secure location. You can use OpenShift API for Data Protection (OADP) backup and restore solutions. For information about OADP, see _OADP features_ in the _Additional resources_ section.
+Volume snapshots are located on the same devices as the original data. To use the volume snapshots as backups, you must move the snapshots to a secure location. You can use OpenShift API for Data Protection (OADP) backup and restore solutions. For information about OADP, see "OADP features" in the "Additional resources" section.
 ====
 
 * Revert to a state at which the volume snapshot was taken.

modules/lvms-creating-lvms-cluster-using-cli.adoc

@@ -23,11 +23,13 @@ You can only create a single instance of the `LVMCluster` custom resource (CR) o
 
 * You have installed a worker node in the cluster.
 
+* You read the "About the LVMCluster custom resource" section. See the "Additional resources" section.
+
 .Procedure
 
 . Create an `LVMCluster` custom resource (CR) YAML file:
 +
-.Example `LVMCluster` CR
+.Example `LVMCluster` CR YAML file
 [source,yaml]
 ----
 apiVersion: lvm.topolvm.io/v1alpha1
@@ -66,7 +68,7 @@ lvmcluster/lvmcluster created
 
 .Verification
 
-* Check that the `LVMCluster` CR is in the `Ready` state:
+. Check that the `LVMCluster` CR is in the `Ready` state:
 +
 [source, terminal]
 ----
@@ -119,3 +121,31 @@ status:
   state: Failed
 ----
 ====
+
+. Optional: To view the storage classes created by {lvms} for each device class, run the following command:
++
+[source,terminal]
+----
+$ oc get storageclass
+----
++
+.Example output
+[source, terminal]
+----
+NAME          PROVISIONER          RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
+lvms-vg1      topolvm.io           Delete          WaitForFirstConsumer   true                   31m
+----
+
+. Optional: To view the volume snapshot classes created by {lvms} for each device class, run the following command:
++
+[source,terminal]
+----
+$ oc get volumesnapshotclass
+----
++
+.Example output
+[source, terminal]
+----
+NAME          DRIVER               DELETIONPOLICY   AGE
+lvms-vg1      topolvm.io           Delete           24h
+----

modules/lvms-creating-lvms-cluster-using-web-console.adoc

@@ -21,6 +21,8 @@ You can only create a single instance of the `LVMCluster` custom resource (CR) o
 
 * You have installed a worker node in the cluster.
 
+* You read the "About the LVMCluster custom resource" section. See the "Additional resources" section.
+
 .Procedure
 
 . Log in to the {product-title} web console.
@@ -37,4 +39,6 @@ You can only create a single instance of the `LVMCluster` custom resource (CR) o
 
 .Verification
 
-* On the *LVMCLuster* page, check that the `LVMCluster` CR is in the `Ready` state. 
+. On the *LVMCLuster* page, check that the `LVMCluster` CR is in the `Ready` state. 
+. Optional: To view the available storage classes created by {lvms} for each device class, click *Storage* -> *StorageClasses*. 
+. Optional: To view the available volume snapshot classes created by {lvms} for each device class, click *Storage* -> *VolumeSnapshotClasses*.

modules/lvms-deleting-lvmcluster-using-cli.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+//
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="lvms-deleting-lvmcluster-using-cli_{context}"]
+= Deleting an LVMCluster CR by using the CLI
+
+You can delete the `LVMCluster` custom resource (CR) using the OpenShift CLI (`oc`).
+
+.Prerequisites
+
+* You have access to {product-title} as a user with `cluster-admin` permissions.
+* You have deleted the persistent volume claims (PVCs), volume snapshots, and volume clones provisioned by {lvms}. You have also deleted the applications that are using these resources.
+
+.Procedure
+
+. Log in to the OpenShift CLI (`oc`).
+. Delete the `LVMCluster` CR by running the following command:
++
+[source,terminal]
+----
+$ oc delete lvmcluster <lvmclustername> -n openshift-storage
+----
+
+.Verification
+
+* To verify that the `LVMCluster` CR has been deleted, run the following command:
++
+[source,terminal]
+----
+$ oc get lvmcluster -n <namespace>
+----
++
+.Example output
+[source,terminal]
+----
+No resources found in openshift-storage namespace.
+----