OSDOCS-18757#LSO Symlinks updating

modules/persistent-storage-local-symlinks-overview.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * storage/persistent_storage/persistent-storage-local.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="local-storage-symlinks_{context}"]
+= Local Storage Operator symlinks overview
+
+[role="_abstract"] 
+The Local Storage Operator (LSO) traditionally creates persistent volumes (PVs) based on `/dev/disk/by-id/` paths, following the assumption that they are stable. However, Linux kernel updates, firmware updates, or `udev` rule changes can cause these supposedly stable names to change or disappear.
+
+== Administrator options
+Administrators have the following notification and correction options to deal with symlink disruptions:
+
+* *Monitoring*: (default) If the current and preferred path do not match, an alerts occurs, but no changes occur to the current path.
+
+* *Use existing path*: Alerts are silenced and LSO uses the existing path.
+
+* *Recreate symlinks*: Symlinks are recreated to point to the new, updated device path.

modules/persistent-storage-local-symlinks-procedure.adoc

@@ -0,0 +1,60 @@
+// Module included in the following assemblies:
+//
+// * storage/persistent_storage/persistent-storage-local.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="local-storage-symlinks-procedure_{context}"]
+= Selecting symlinks management options for the Local Storage Operator
+
+[role="_abstract"] 
+To prevent storage breakage during {product-title} upgrades, an administrator can elect to detect, alert, and remap broken symlinks without manual node-level intervention.
+
+.Prerequisites
+
+* Access to the {product-title} web console or command-line interface (CLI) with administrative privileges.
+
+* Install the Local Storage Operator (LSO). See the _Installing the Local Storage Operator_ section.
+
+.Procedure
+
+. Log in to the {product-title} web console.
+
+. Do not change the default setting (none) for `localVolumeDeviceLink.spec.policy`.
++
+This establishes link monitoring and generates an alert if the current and preferred paths do not match.
+
+. If an alert occurs, go to the Custom Resource Definition, `localVolumeDeviceLink`:
+
+.. Click *Administration* > *CustomResourcesDefinitions*. 
+
+.. On the *CustomResourceDefinitions* page, in the *Filter by name* box, type "LocalVolumeDeviceLink".
+
+.. Click *CustomResourceDefinitions*. 
+
+.. On the *CustomResourceDefinitions* page, click the *YAML* tab.
+
+.. Navigate to `localVolumeDeviceLink.status` and view its nested fields that are shown in the following table for a list of valid symlink targets, current link (`by-id)`, and the generated preferred symlink.
++
+.`localVolumeDeviceLink.status` nested fields
+[width="100%", cols="autowidth", options="header"]
+|===
+| Status fields |Description
+| validLinkTargets |The full list of valid symlink targets, since there might be multiple `by-id` symlinks pointing to the same physical device.
+| currentLinkTarget |The by-id symlink currently used by the PV.
+| preferredLinkTarget |The preferred symlink chosen by diskmaker.
+| filesystemUUID |The corresponding UUID of the filesystem, if one is found.
+|===
+
+.. Navigate to `localVolumeDeviceLink.spec.policy` field and set its value to one of the following options:
++
+* `CurrentLinkTarget`: Silences alerts and tells LSO to use the existing path.
+
+* `PreferredLinkTarget`: LSO recreates the symlink to point to the new, updated device path.
+
+. Click *Save*.
+
+. Set `localVolumeDeviceLink.spec.policy` back to null.
++
+This re-establishes link monitoring for future link disruptions, and generates an alert if the current and preferred paths do not match.
+
+. Click *Save*.

modules/persistent-storage-local-symlinks-top-level.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * storage/persistent_storage/persistent-storage-local.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="local-storage-symlinks-top-level_{context}"]
+= Local Storage Operator symlinks management
+
+[role="_abstract"] 
+To prevent storage breakage during {product-title} upgrades, {product-title} provides a mechanism, the `LocalVolumeDeviceLink` Custom Resource Definition, to detect, alert, and remap broken symlinks without manual node-level intervention.

storage/persistent_storage_local/persistent-storage-local.adoc

@@ -33,6 +33,12 @@ include::modules/persistent-storage-local-pod.adoc[leveloffset=+1]
 
 include::modules/persistent-storage-local-discovery.adoc[leveloffset=+1]
 
+include::modules/persistent-storage-local-symlinks-top-level.adoc[leveloffset=+1]
+
+include::modules/persistent-storage-local-symlinks-overview.adoc[leveloffset=+2]
+
+include::modules/persistent-storage-local-symlinks-procedure.adoc[leveloffset=+2]
+
 include::modules/persistent-storage-local-tolerations.adoc[leveloffset=+1]
 
 include::modules/persistent-storage-local-metrics.adoc[leveloffset=+1]