Merge pull request #71942 from sr1kar99/doc_improv_2

OCPBUGS#27913: Doc improvements related to "Scaling up storage of clusters"

Author: kcarmichael08

_attributes/common-attributes.adoc

@@ -198,7 +198,7 @@ endif::[]
 //:openshift-networking: OKD Networking
 //endif::[]
 // logical volume manager storage
-:lvms-first: Logical volume manager storage (LVM Storage)
+:lvms-first: Logical Volume Manager (LVM) Storage 
 :lvms: LVM Storage
 //Operator SDK version
 :osdk_ver: 1.31.0

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

@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="lvms-about-scaling-storage-of-cluster_{context}"]
+= Scaling 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. 
+
+{lvms-first} detects and uses additional worker nodes when the nodes become active.
+
+To add a new device to the existing worker nodes on a cluster, you must add the path to the new device in the `deviceSelector` field of the `LVMCluster` custom resource (CR).
+
+[IMPORTANT]
+====
+You can add the `deviceSelector` field in the `LVMCluster` CR only while creating the `LVMCluster` CR. If you have not added the `deviceSelector` field while creating the `LVMCluster` CR, you must delete the `LVMCluster` CR and create a new `LVMCluster` CR containing the `deviceSelector` field.
+====
+
+If you do not add the `deviceSelector` field in the `LVMCluster` CR, {lvms} automatically adds the new devices when the devices are available.
+[NOTE]
+====
+{lvms} adds only the supported devices. For information about unsupported devices, see "Devices not supported by LVM Storage" in the "Additional resources" section.
+====

modules/lvms-scaling-storage-of-clusters-using-cli.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="lvms-scaling-storage-of-clusters-using-cli_{context}"]
+= Scaling up the storage of clusters by using the CLI
+
+You can scale up the storage capacity of the worker nodes on a cluster by using the OpenShift CLI (`oc`).
+
+.Prerequisites
+
+* You have additional unused devices on each cluster to be used by {lvms-first}.
+* You have installed the OpenShift CLI (`oc`).
+* You have created an `LVMCluster` custom resource (CR).
+
+.Procedure
+
+. Edit the `LVMCluster` CR by running the following command:
++
+[source, terminal]
+----
+$ oc edit <lvmcluster_file_name> -n <namespace>
+----
+
+. Add the path to the new device in the `deviceSelector` field.
++
+include::snippets/lvms-scaling-up-storage-lvmcluster-cr-snippet.adoc[]
+
+. Save the `LVMCluster` CR.

modules/lvms-scaling-storage-of-clusters-using-web-console.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: PROCEDURE
+[id="lvms-scaling-storage-of-clusters-using-web-console_{context}"]
+= Scaling up the storage of clusters by using the web console
+
+You can scale up the storage capacity of the worker nodes on a cluster by using the {product-title} web console.
+
+.Prerequisites
+
+* You have additional unused devices on each cluster to be used by {lvms-first}.
+* You have created an `LVMCluster` custom resource (CR).
+
+.Procedure
+
+. Log in to the {product-title} web console.
+. Click *Operators* -> *Installed Operators*. 
+. Click *LVM Storage* in the `openshift-storage` namespace.
+. Click the *LVMCluster* tab to view the `LVMCluster` CR created on the cluster.
+. From the *Actions* menu, select *Edit LVMCluster*.
+. Click the *YAML* tab.
+. Edit the `LVMCluster` CR to add the new device path in the `deviceSelector` field:
++
+include::snippets/lvms-scaling-up-storage-lvmcluster-cr-snippet.adoc[]
+. Click *Save*.

modules/lvms-scaling-storage-of-single-node-open-concept.adoc

@@ -0,0 +1,34 @@
+:_mod-docs-content-type: SNIPPET
+.Example `LVMCluster` CR
+[source,yaml]
+----
+apiVersion: lvm.topolvm.io/v1alpha1
+kind: LVMCluster
+metadata:
+  name: my-lvmcluster
+spec:
+  storage:
+    deviceClasses:
+# ...
+      deviceSelector: <1>
+        paths: <2>
+        - /dev/disk/by-path/pci-0000:87:00.0-nvme-1
+        - /dev/disk/by-path/pci-0000:88:00.0-nvme-1
+        optionalPaths: <3>
+        - /dev/disk/by-path/pci-0000:89:00.0-nvme-1
+        - /dev/disk/by-path/pci-0000:90:00.0-nvme-1
+# ...
+----
+<1> 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 `paths` field, the `optionalPaths` field, or both. If you do not specify the device paths in both `paths` and `optionalPaths`, {lvms-first} adds the supported unused devices to the LVM volume group. {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}. For information about unsupported devices, see "Devices not supported by {lvms}" in the "Additional resources" section.
+<2> Specify the device paths. If the device path specified in this field does not exist, or the device is not supported by {lvms}, the `LVMCluster` CR moves to the `Failed` state.
+<3> Specify the optional device paths. If the device path specified in this field does not exist, or the device is not supported by {lvms}, {lvms} ignores the device without causing an error. 
++
+[IMPORTANT]
+====
+After a device is added to the LVM volume group, it cannot be removed.
+====
+
+

modules/lvms-scaling-storage-of-single-node-openshift-cluster.adoc

@@ -39,16 +39,11 @@ include::modules/lvms-installing-logical-volume-manager-operator-disconnected-en
 
 * xref:../../../openshift_images/image-configuration.adoc#images-configuration-registry-mirror_image-configuration[Configuring image registry repository mirroring]
 
-
 include::modules/lvms-installing-logical-volume-manager-operator-using-rhacm.adoc[leveloffset=+2]
 
-[role="_additional-resources"]
-.Additional resources
-
 * link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/{rh-rhacm-version}/html/install/installing#installing-while-connected-online[Red Hat Advanced Cluster Management for Kubernetes: Installing while connected online]
 
-* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#about-lvmcluster_logical-volume-manager-storage[About the `LVMCluster` custom resource]
-
+* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#about-lvmcluster_logical-volume-manager-storage[About the LVMCluster custom resource]
 
 // Creating an LVMCluster custom resource
 
@@ -84,19 +79,36 @@ include::modules/lvms-integrating-software-raid-arrays.adoc[leveloffset=+1]
 include::modules/lvms-provisioning-storage-using-logical-volume-manager-operator.adoc[leveloffset=+1]
 
 //Scaling
-include::modules/lvms-scaling-storage-of-single-node-open-concept.adoc[leveloffset=+1]
+include::modules/lvms-about-scaling-storage-of-clusters.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
 * xref:../../../nodes/nodes/nodes-sno-worker-nodes.adoc[Adding worker nodes to {sno} clusters]
 
-include::modules/lvms-scaling-storage-of-single-node-openshift-cluster.adoc[leveloffset=+2]
+* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#lvms-unsupported-devices_logical-volume-manager-storage[Devices not supported by {lvms}]
+
+include::modules/lvms-scaling-storage-of-clusters-using-cli.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#about-lvmcluster_logical-volume-manager-storage[About the `LVMCluster` custom resource]
+* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#about-lvmcluster_logical-volume-manager-storage[About the LVMCluster custom resource]
+
+* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#lvms-unsupported-devices_logical-volume-manager-storage[Devices not supported by {lvms}]
+
+* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#lvms-integrating-software-raid-arrays_logical-volume-manager-storage[Integrating software RAID arrays with {lvms}]
+
+include::modules/lvms-scaling-storage-of-clusters-using-web-console.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#lvms-unsupported-devices_logical-volume-manager-storage[Devices not supported by {lvms}]
+
+* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#lvms-integrating-software-raid-arrays_logical-volume-manager-storage[Integrating software RAID arrays with {lvms}]
+
+* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#about-lvmcluster_logical-volume-manager-storage[About the LVMCluster custom resource]
 
 include::modules/lvms-scaling-storage-of-single-node-openshift-cluster-using-rhacm.adoc[leveloffset=+2]
 
@@ -107,15 +119,13 @@ include::modules/lvms-scaling-storage-of-single-node-openshift-cluster-using-rha
 
 * xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#about-lvmcluster_logical-volume-manager-storage[About the `LVMCluster` custom resource]
 
-// Expanding PVC
+// Expanding PVCs
 include::modules/lvms-scaling-storage-expand-pvc.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#lvms-scaling-storage-of-single-node-openshift-cluster_logical-volume-manager-storage[Scaling up storage by adding capacity to your cluster]
-
-* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#lvms-scaling-storage-of-single-node-openshift-cluster-using-rhacm_logical-volume-manager-storage[Scaling up storage by adding capacity to your cluster using {rh-rhacm}]
+* xref:../../../storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc#lvms-about-scaling-storage-of-cluster_logical-volume-manager-storage[Scaling up the storage of clusters]
 
 * xref:../../../storage/expanding-persistent-volumes.adoc#add-volume-expansion_expanding-persistent-volumes[Enabling volume expansion support]