Merge pull request #99435 from tedaveryredhat/OSDOCS-11089

OSDOCS-11089:Plan refactor of MicroShift Storage book

Author: bscott-rh

_topic_maps/_topic_map_ms.yml

@@ -195,18 +195,16 @@ Name: Storage
 Dir: microshift_storage
 Distros: microshift
 Topics:
-- Name: About storage
-  File: index
-- Name: Understanding ephemeral storage
-  File: understanding-ephemeral-storage-microshift
+- Name: Using dynamic storage with the LVMS plugin
+  File: microshift-storage-plugin-overview
+- Name: Using ephemeral storage
+  File: using-ephemeral-storage-microshift
 - Name: Generic ephemeral volumes
   File: generic-ephemeral-volumes-microshift
-- Name: Understanding persistent storage
-  File: understanding-persistent-storage-microshift
+- Name: Using persistent storage
+  File: using-persistent-storage-microshift
 - Name: Expanding persistent volumes
   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: Understanding storage migration

microshift_storage/microshift-storage-plugin-overview.adoc

@@ -1,12 +1,14 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="microshift-storage-plugin-overview"]
-= Dynamic storage using the LVMS plugin
+= Using dynamic storage with the LVMS plugin
 include::_attributes/attributes-microshift.adoc[]
 include::_attributes/common-attributes.adoc[]
 :context: microshift-storage-plugin-overview
 
 toc::[]
 
+Using dynamic provisioning allows you to create storage volumes on-demand, eliminating the need for pre-provisioned storage.
+
 {microshift-short} enables dynamic storage provisioning that is ready for immediate use with the logical volume manager storage (LVMS) Container Storage Interface (CSI) provider. The LVMS plugin is the Red Hat downstream version of TopoLVM, a CSI plugin for managing logical volume management (LVM) logical volumes (LVs) for Kubernetes.
 
 LVMS provisions new LVM logical volumes for container workloads with appropriately configured persistent volume claims (PVCs). Each PVC references a storage class that represents an LVM Volume Group (VG) on the host node. LVs are only provisioned for scheduled pods.

…anding-ephemeral-storage-microshift.adoc …/using-ephemeral-storage-microshift.adocmicroshift_storage/understanding-ephemeral-storage-microshift.adoc renamed to microshift_storage/using-ephemeral-storage-microshift.adoc microshift_storage/understanding-ephemeral-storage-microshift.adoc renamed to microshift_storage/using-ephemeral-storage-microshift.adoc

@@ -1,8 +1,8 @@
 :_mod-docs-content-type: ASSEMBLY
-[id="understanding-ephemeral-storage-microshift"]
-= Understanding ephemeral storage
+[id="using-ephemeral-storage-microshift"]
+= Using ephemeral storage
 include::_attributes/attributes-microshift.adoc[]
-:context: understanding-ephemeral-storage-microshift
+:context: using-ephemeral-storage-microshift
 
 toc::[]
 

…nding-persistent-storage-microshift.adoc …using-persistent-storage-microshift.adocmicroshift_storage/understanding-persistent-storage-microshift.adoc renamed to microshift_storage/using-persistent-storage-microshift.adoc microshift_storage/understanding-persistent-storage-microshift.adoc renamed to microshift_storage/using-persistent-storage-microshift.adoc

@@ -1,18 +1,18 @@
 :_mod-docs-content-type: ASSEMBLY
-[id="understanding-persistent-storage-microshift"]
-= Understanding persistent storage
+[id="using-persistent-storage-microshift"]
+= Using persistent storage
 include::_attributes/attributes-microshift.adoc[]
-:context: understanding-persistent-storage-microshift
+:context: using-persistent-storage-microshift
 
 toc::[]
 
-Managing storage is a distinct problem from managing compute resources. {microshift-short} uses the Kubernetes persistent volume (PV) framework to allow {microshift-short} administrators to provision persistent storage for a node. Developers can use persistent volume claims (PVCs) to request PV resources without having specific knowledge of the underlying storage infrastructure.
+Managing storage is a distinct problem from managing compute resources. {microshift-short} uses the Kubernetes persistent volume (PV) framework to allow node administrators to provision persistent storage for a node. Developers can use persistent volume claims (PVCs) to request PV resources without having specific knowledge of the underlying storage infrastructure.
 
 include::modules/microshift-control-permissions-security-context-constraints.adoc[leveloffset=+1]
 
 include::modules/storage-persistent-storage-overview.adoc[leveloffset=+1]
 
-[id="additional-resources_understanding-persistent-storage-microshift_{context}"]
+[id="additional-resources_using-persistent-storage-microshift_{context}"]
 [role="_additional-resources"]
 == Additional resources
 * link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/storage/understanding-persistent-storage#pv-access-modes_understanding-persistent-storage[Access modes for persistent storage]

microshift_storage/volume-snapshots-microshift.adoc

@@ -6,11 +6,11 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-{microshift-short} administrators can use volume snapshots to help protect against data loss by using the supported {microshift-short} 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.
+{microshift-short} administrators can use volume snapshots to help protect against data loss by using the supported {microshift-short} logical volume manager storage (LVMS) Container Storage Interface (CSI) provider. Familiarity with xref:../microshift_storage/using-persistent-storage-microshift.adoc#persistent-volumes_using-persistent-storage-microshift[persistent volumes] is required.
 
 A snapshot represents the state of the storage volume in a node 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 {microshift-short} administrator can complete the following tasks by using CSI volume snapshots:
+A {microshift-short} 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.
@@ -26,7 +26,7 @@ Only the logical volume manager storage (LVMS) plugin CSI driver is supported by
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../microshift_storage/understanding-persistent-storage-microshift.adoc#persistent-volumes_understanding-persistent-storage-microshift[Understanding persistent volumes]
+* xref:../microshift_storage/using-persistent-storage-microshift.adoc#persistent-volumes_using-persistent-storage-microshift[Using persistent volumes]
 
 * link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_logical_volumes/managing-lvm-volume-groups_configuring-and-managing-logical-volumes[Managing LVM volume groups] ({op-system-base} documentation)
 

modules/lvms-about-volume-snapshots.adoc

@@ -3,7 +3,7 @@
 // storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
 
 :_mod-docs-content-type: CONCEPT
-[id="lvms-about-volume-snapsot_{context}"]
+[id="lvms-about-volume-snapshots_{context}"]
 = About volume snapshots
 
 You can create snapshots of persistent volume claims (PVCs) that are provisioned by {lvms}.

modules/microshift-disabling-uninstalling-lvms-csi-snapshot.adoc

@@ -19,5 +19,5 @@ Automated uninstallation is not supported as this can cause orphaning of the pro
 
 [NOTE]
 ====
-You can configure {microshift-short} to disable CSI provider and CSI snapshot only before installing and running {microshift-short}.After {microshift-short} is installed and running, you must update the configuration file and uninstall the components.
+You can configure {microshift-short} to disable CSI provider and CSI snapshot only before installing and running {microshift-short}. After {microshift-short} is installed and running, you must update the configuration file and uninstall the components.
 ====

modules/microshift-lvms-config-example-basic.adoc

@@ -3,7 +3,7 @@
 // * microshift_storage/microshift-storage-plugin-overview.adoc
 
 :_mod-docs-content-type: CONCEPT
-[id="microshift-lvmd-config-example-basic_{context}"]
+[id="microshift-lvms-config-example-basic_{context}"]
 = Basic LVMS configuration example
 
 {microshift-short} 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 {microshift-short} to deploy configuration changes after editing the file.

modules/storage-ephemeral-storage-overview.adoc

@@ -8,6 +8,8 @@
 [id=storage-ephemeral-storage-overview_{context}]
 = Overview
 
+Pods and containers are ephemeral or transient in nature and designed for stateless applications. Ephemeral storage allows administrators and developers to better manage the local storage for some of their operations.
+
 In addition to persistent storage, pods and containers can require ephemeral or transient local storage for their operation. The lifetime of this ephemeral storage does not extend beyond the life of the individual pod, and this ephemeral storage cannot be shared across pods.
 
 Pods use ephemeral local storage for scratch space, caching, and logs. Issues related to the lack of local storage accounting and isolation include the following:

modules/storage-persistent-storage-overview.adoc

@@ -7,14 +7,16 @@
 [id=persistent-storage-overview_{context}]
 = Persistent storage overview
 
+Stateful applications deployed in containers require persistent storage. {microshift-short} uses a pre-provisioned storage framework called persistent volumes (PV) to allow node administrators to provision persistent storage. The data inside these volumes can exist beyond the lifecycle of an individual pod. Developers can use persistent volume claims (PVCs) to request storage requirements.
+
 ifndef::microshift[]
 Managing storage is a distinct problem from managing compute resources. {product-title} uses the Kubernetes persistent volume (PV) framework to allow cluster administrators to provision persistent storage for a cluster. Developers can use persistent volume claims (PVCs) to request PV resources without having specific knowledge of the underlying storage infrastructure.
 
-PVCs are specific to a project, and are created and used by developers as a means to use a PV. PV resources on their own are not scoped to any single project; they can be shared across the entire {product-title} cluster and claimed from any project. After a PV is bound to a PVC, that PV can not then be bound to additional PVCs. This has the effect of scoping a bound PV to a single namespace, that of the binding project.
+PVCs are specific to a project, and are created and used by developers as a means to use a PV. PV resources on their own are not scoped to any single project; they can be shared across the entire {product-title} node and claimed from any project. After a PV is bound to a PVC, that PV can not then be bound to additional PVCs. This has the effect of scoping a bound PV to a single namespace, that of the binding project.
 endif::microshift[]
 
 ifdef::microshift[]
-PVCs are specific to a namespace, and are created and used by developers as a means to use a PV. PV resources on their own are not scoped to any single namespace; they can be shared across the entire {product-title} cluster and claimed from any namespace. After a PV is bound to a PVC, that PV can not then be bound to additional PVCs. This has the effect of scoping a bound PV to a single namespace.
+PVCs are specific to a namespace, and are created and used by developers as a means to use a PV. PV resources on their own are not scoped to any single namespace; they can be shared across the entire {product-title} node and claimed from any namespace. After a PV is bound to a PVC, that PV can not then be bound to additional PVCs. This has the effect of scoping a bound PV to a single namespace.
 endif::microshift[]
 
 PVs are defined by a `PersistentVolume` API object, which represents a piece of existing storage in the cluster that was either statically provisioned by the cluster administrator or dynamically provisioned using a `StorageClass` object. It is a resource in the cluster just like a node is a cluster resource.