STOR-402: Auto-discovery and auto-provisioning in LSO

modules/persistent-storage-local-discovery.adoc

@@ -0,0 +1,148 @@
+// Module included in the following assemblies:
+//
+// storage/persistent_storage/persistent-storage-local.adoc
+
+[id="local-storage-discovery_{context}"]
+= Automating discovery and provisioning for local storage devices
+
+The Local Storage Operator automates local storage discovery and provisioning. With this feature, you can simplify installation when dynamic provisioning is not available during deployment, such as with bare metal, VMware, or AWS store instances with attached devices.
+
+[IMPORTANT]
+====
+Automatic discovery and provisioning is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
+
+For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.
+====
+
+Use the following procedure to automatically discover local devices, and to automatically provision local volumes for selected devices.
+
+.Prerequisites
+* You have cluster administrator permissions.
+
+* You have installed the Local Storage Operator.
+
+* You have attached local disks to {product-title} nodes.
+
+* You have access to the {product-title} web console and the `oc` command-line interface (CLI).
+
+.Procedure
+
+. To enable automatic discovery of local devices from the web console:
+
+.. In the _Administrator_ perspective, navigate to *Operators* -> *Installed Operators* and click on the *Local Volume Discovery* tab.
+
+.. Click *Create Local Volume Discovery*.
+
+.. Select either *All nodes* or *Select nodes*, depending on whether you want to discover available disks on all or specific nodes.
++
+[NOTE]
+====
+Only worker nodes are available, regardless of whether you filter using *All nodes* or *Select nodes*.
+====
++
+.. Click *Create*.
+
+A local volume discovery instance named `auto-discover-devices` is displayed.
+
+. To display a continuous list of available devices on a node:
+
+.. Log in to the {product-title} web console.
+
+.. Navigate to *Compute* -> *Nodes*.
+
+.. Click the node name that you want to open. The "Node Details" page is displayed.
+
+.. Select the *Disks* tab to display the list of the selected devices.
++
+The device list updates continuously as local disks are added or removed. You can filter the devices by name, status, type, model, capacity, and mode.
+
+. To automatically provision local volumes for the discovered devices from the web console:
+
+.. Navigate to *Operators* -> *Installed Operators* and select *Local Storage* from the list of Operators.
+
+.. Select *Local Volume Set* -> *Create Local Volume Set*.
+
+.. Enter a volume set name and a storage class name.
+
+.. Choose *All nodes* or *Select nodes* to apply filters accordingly.
++
+[NOTE]
+====
+Only worker nodes are available, regardless of whether you filter using *All nodes* or *Select nodes*.
+====
++
+.. Select the disk type, mode, size, and limit you want to apply to the local volume set, and click *Create*.
++
+A message displays after several minutes, indicating that the "Operator reconciled successfully."
+
+[start=3]
+. Alternatively, to provision local volumes for the discovered devices from the CLI:
+
+.. Create an object YAML file to define the local volume set, such as `local-volume-set.yaml`, as shown in the following example:
++
+[source,yaml]
+----
+apiVersion: local.storage.openshift.io/v1alpha1
+kind: LocalVolumeSet
+metadata:
+  name: example-autodetect
+spec:
+  nodeSelector:
+    nodeSelectorTerms:
+      - matchExpressions:
+          - key: kubernetes.io/hostname
+            operator: In
+            values:
+              - worker-0
+              - worker-1
+  storageClassName: example-storageclass <1>
+  volumeMode: Filesystem
+  fstype: ext4
+  maxDeviceCount: 10
+  deviceInclusionSpec:
+    deviceTypes: <2>
+      - disk
+      - part
+    deviceMechanicalProperty:
+      - NonRotational
+    minSize: 10G
+    maxSize: 100G
+    models:
+      - SAMSUNG
+      - Crucial_CT525MX3
+    vendors:
+      - ATA
+      - ST2000LM
+----
++
+<1> Determines the storage class that is created for persistent volumes that are provisioned from discovered devices.
++
+<2> When using the local volume set feature, the Local Storage Operator does not support the use of logical volume management (LVM) devices.
+
+.. Create the local volume set object:
++
+[source,terminal]
+----
+$ oc apply -f local-volume-set.yaml
+----
+
+.. Verify that the local persistent volumes were dynamically provisioned based on the storage class:
++
+[source,terminal]
+----
+$ oc -n get pv
+----
++
+.Example output
+[source,terminal]
+----
+NAME                CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS           REASON   AGE
+local-pv-1cec77cf   100Gi      RWO            Delete           Available           example-storageclass            88m
+local-pv-2ef7cd2a   100Gi      RWO            Delete           Available           example-storageclass            82m
+local-pv-3fa1c73    100Gi      RWO            Delete           Available           example-storageclass            48m
+----
+
+[NOTE]
+====
+Results are deleted after they are removed from the node. Symlinks must be manually removed.
+====

modules/persistent-storage-local-pod.adoc

@@ -5,35 +5,36 @@
 [id="local-pod_{context}"]
 = Attach the local claim
 
-After a local volume has been mapped to a PersistentVolumeClaim (PVC)
+After a local volume has been mapped to a persistent volume claim
 it can be specified inside of a resource.
 
 .Prerequisites
 
-* A PVC exists in the same namespace.
+* A persistent volume claim exists in the same namespace.
 
 .Procedure
 
-. Include the defined claim in the resource's Spec. The following example
-declares the PVC inside a Pod:
+. Include the defined claim in the resource spec. The following example
+declares the persistent volume claim inside a pod:
 +
+[source,yaml]
 ----
 apiVersion: v1
 kind: Pod
 spec:
   ...
   containers:
     volumeMounts:
-    - name: localpvc <1>
-      mountPath: "/data" <2>
+    - name: local-disks <1>
+      mountPath: /data <2>
   volumes:
   - name: localpvc
     persistentVolumeClaim:
-      claimName: localpvc <3>
+      claimName: local-pvc-name <3>
 ----
-<1> Name of the volume to mount.
-<2> Path inside the Pod where the volume is mounted.
-<3> Name of the existing PVC to use.
+<1> The name of the volume to mount.
+<2> The path inside the pod where the volume is mounted.
+<3> The name of the existing persistent volume claim to use.
 
 . Create the resource in the {product-title} cluster, specifying the file
 you just created:

modules/persistent-storage-local-removing-devices.adoc

@@ -3,13 +3,13 @@
 // storage/persistent_storage/persistent-storage-local.adoc
 
 [id="local-removing-device_{context}"]
-= Removing a local volume
+= Removing a local volume or local volume set
 
-Occasionally, local volumes must be deleted. While removing the entry in the LocalVolume resource and deleting the PersistentVolume is typically enough, if you want to re-use the same device path or have it managed by a different StorageClass, then additional steps are needed.
+Occasionally, local volumes and local volume sets must be deleted. While removing the entry in the resource and deleting the persistent volume is typically enough, if you want to reuse the same device path or have it managed by a different StorageClass, then additional steps are needed.
 
-[WARNING]
+[NOTE]
 ====
-The following procedure involves accessing a node as the root user. Modifying the state of the node beyond the steps in this procedure could result in cluster instability.
+The following procedure outlines an example for removing a local volume. The same procedure can also be used to remove symlinks for a local volume set custom resource.
 ====
 
 .Prerequisite
@@ -42,6 +42,12 @@ $ oc delete pv <pv-name>
 ----
 
 . Delete any symlinks on the node.
++
+[WARNING]
+====
+The following step involves accessing a node as the root user. Modifying the state of the node beyond the steps in this procedure could result in cluster instability.
+====
++
 .. Create a debug pod on the node:
 +
 [source,terminal]

storage/persistent_storage/persistent-storage-local.adoc

@@ -8,16 +8,16 @@ toc::[]
 {product-title} can be provisioned with persistent storage by using
 local volumes. Local persistent volumes allow you to access local storage
 devices, such as a disk or partition, by using the standard
-PVC interface.
+persistent volume claim interface.
 
-Local volumes can be used without manually scheduling Pods to nodes,
-because the system is aware of the volume node's constraints. However,
+Local volumes can be used without manually scheduling pods to nodes
+because the system is aware of the volume node constraints. However,
 local volumes are still subject to the availability of the underlying node
 and are not suitable for all applications.
 
 [NOTE]
 ====
-Local volumes can only be used as a statically created Persistent Volume.
+Local volumes can only be used as a statically created persistent volume.
 ====
 
 include::modules/persistent-storage-local-install.adoc[leveloffset=+1]
@@ -28,9 +28,11 @@ include::modules/persistent-storage-local-pvc.adoc[leveloffset=+1]
 
 include::modules/persistent-storage-local-pod.adoc[leveloffset=+1]
 
+include::modules/persistent-storage-local-discovery.adoc[leveloffset=+1]
+
 include::modules/persistent-storage-local-tolerations.adoc[leveloffset=+1]
 
-== Deleting the Local Storage Operator's resources
+== Deleting the Local Storage Operator resources
 
 include::modules/persistent-storage-local-removing-devices.adoc[leveloffset=+2]