OSDOCS-17125: MSH-STOR-1 Core Storage Concepts

microshift_storage/expanding-persistent-volumes-microshift.adoc

@@ -6,10 +6,17 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-Learn how to expand persistent volumes in {microshift-short}.
+[role="_abstract"]
+To increase available storage capacity, expand persistent volumes in {microshift-short}. You can resize existing volumes to accommodate growing application data requirements without recreating storage resources.
 
 include::modules/storage-expanding-csi-volumes.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/storage/using-container-storage-interface-csi#csi-drivers-supported_persistent-storage-csi[CSI drivers supported by {product-title}]
+
 include::modules/storage-expanding-local-volumes.adoc[leveloffset=+1]
 
 include::modules/storage-expanding-filesystem-pvc.adoc[leveloffset=+1]

microshift_storage/generic-ephemeral-volumes-microshift.adoc

@@ -6,7 +6,8 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-Learn about ephemeral volumes for {microshift-short}, including their lifecycles, security, and naming.
+[role="_abstract"]
+To understand temporary storage that persists only for the duration of a pod, review the properties of ephemeral volumes in {microshift-short}.
 
 include::modules/storage-ephemeral-vols-overview.adoc[leveloffset=+1]
 

microshift_updating/microshift-storage-migration.adoc

@@ -6,6 +6,9 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-Storage version migration is used to update existing objects in the {microshift-short} node from their current version to the latest version. The Kube Storage Version Migrator embedded controller is used in {microshift-short} to migrate resources without having to re-create those resources. Either you or a controller can create a `StorageVersionMigration` custom resource (CR) that requests a migration through the Migrator Controller.
+[role="_abstract"]
+To update existing objects to their latest version without recreating them, use storage version migration in {microshift-short}. By creating a `StorageVersionMigration` custom resource (CR), you request the Kube Storage Version Migrator embedded controller to handle the transition automatically.
+
+Either you or a controller can create a `StorageVersionMigration` custom resource (CR) that requests a migration through the Migrator Controller.
 
 include::modules/microshift-updating-stored-data-to-latest-storage-version.adoc[leveloffset=+1]

migrating_from_ocp_3_to_4/planning-migration-3-4.adoc

@@ -94,7 +94,7 @@ For more information, see xref:../storage/persistent_storage/persistent-storage-
 
 ==== Container Storage Interface (CSI) persistent storage
 
-Persistent storage using the Container Storage Interface (CSI) was link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] in {product-title} 3.11. {product-title} {product-version} ships with xref:../storage/container_storage_interface/persistent-storage-csi.adoc#csi-drivers-supported_persistent-storage-csi[several CSI drivers]. You can also install your own driver.
+Persistent storage using the Container Storage Interface (CSI) was link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] in {product-title} 3.11. {product-title} {product-version} includes with xref:../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi-drivers-supported_persistent-storage-csi[several CSI drivers]. You can also install your own driver.
 
 For more information, see xref:../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-using-csi[Persistent storage using the Container Storage Interface (CSI)].
 

modules/microshift-updating-stored-data-to-latest-storage-version.adoc

@@ -6,14 +6,16 @@
 [id="microshift-updating-stored-data-to-latest-storage-version_{context}"]
 = Updating stored data to the latest storage version
 
-Updating stored data to the latest Kubernetes storage version is called storage migration. For example, updating from `v1beta1` to `v1beta2` is migration. To update your storage version, use the following procedure.
+[role="_abstract"]
+To update stored data to the latest Kubernetes storage version, perform a storage migration. 
+
+The procedure shows an example of converting existing objects on the `v1beta1` version to the current version, such as `v1beta2`, to ensure compatibility with the cluster APIs.
 
 .Procedure
 
 * Either you or any controller that has support for the `StorageVersionMigration` API must trigger a migration request. Use the following example request for reference:
 +
 .Example request
-+
 [source,terminal]
 ----
 apiVersion: migration.k8s.io/v1alpha1
@@ -23,16 +25,21 @@ metadata:
 spec:
   resource:
     group: example.storage.k8s.io
-    resource: volumeclasses <1>
-    version: v1alpha1 <2>
+    resource: volumeclasses
+    version: v1alpha1
+# ...
 ----
-<1> You must use the plural name of the resource.
-<2> Version being updated to.
++
+where:
++
+`resource.resource`:: Specifies the plural name of the resource.
+`resource.version`:: Specifies the version to update to.
+
+.Verification
 
-*  The progress of the migration is posted to the `StorageVersionMigration` status.
+* To monitor the progress of the update, review the status of the `StorageVersionMigration` custom resource (CR).
 
 [NOTE]
 ====
-* Failures can occur because of a misnamed group or resource.
-* Migration failures can also occur when there is an incompatibility between the previous and latest versions.
+A migration fails when you misname a group or resource. Incompatible versions between the previous and latest versions can also cause a migration to fail.
 ====

modules/persistent-storage-csi-drivers-supported.adoc

@@ -3,7 +3,7 @@
 // * storage/container_storage_interface/persistent-storage-csi.adoc
 
 :_mod-docs-content-type: REFERENCE
-[id="csi-drivers-supported_{context}"]
+[id="persistent-storage-csi-drivers-supported_{context}"]
 = CSI drivers supported by {product-title}
 
 [role="_abstract"]

modules/storage-ephemeral-vols-lifecycle.adoc

@@ -8,15 +8,21 @@
 [id="generic-ephemeral-vols-lifecycle_{context}"]
 = Lifecycle and persistent volume claims
 
-The parameters for a volume claim are allowed inside a volume source of a pod. Labels, annotations, and the whole set of fields for persistent volume claims (PVCs) are supported. When such a pod is created, the ephemeral volume controller then creates an actual PVC object (from the template shown in the _Creating generic ephemeral volumes_ procedure) in the same namespace as the pod, and ensures that the PVC is deleted when the pod is deleted. This triggers volume binding and provisioning in one of two ways:
+[role="_abstract"]
+To bind the lifecycle of storage resources to a specific pod, configure persistent volume claim (PVC) parameters within the volume source of the pod. This setup ensures that the ephemeral volume controller creates the PVC in the same namespace upon pod creation and automatically deletes the PVC when the pod is removed.
 
+Labels, annotations, and the whole set of fields for persistent volume claims (PVCs) are supported.
+
+The ephemeral volume controller creates a PVC object from the template shown in the _Creating generic ephemeral volumes_ procedure.
+
+Volume binding and provisioning can be triggered in one of two ways:
 
 * Either immediately, if the storage class uses immediate volume binding.
 +
 With immediate binding, the scheduler is forced to select a node that has access to the volume after it is available.
 
-* When the pod is tentatively scheduled onto a node (`WaitForFirstConsumervolume` binding mode).
+* When the pod is tentatively scheduled onto a node (`WaitForFirstConsumer` volume binding mode).
 +
 This volume binding option is recommended for generic ephemeral volumes because then the scheduler can choose a suitable node for the pod.
 
-In terms of resource ownership, a pod that has generic ephemeral storage is the owner of the PVCs that provide that ephemeral storage. When the pod is deleted, the Kubernetes garbage collector deletes the PVC, which then usually triggers deletion of the volume because the default reclaim policy of storage classes is to delete volumes. You can create quasi-ephemeral local storage by using a storage class with a reclaim policy of retain: the storage outlives the pod, and in this case, you must ensure that volume clean-up happens separately. While these PVCs exist, they can be used like any other PVC. In particular, they can be referenced as data sources in volume cloning or snapshotting. The PVC object also holds the current status of the volume.
+In terms of resource ownership, a pod that has generic ephemeral storage is the owner of the PVCs that provide that ephemeral storage. When the pod is deleted, the Kubernetes garbage collector deletes the PVC, which then usually triggers deletion of the volume because the default reclaim policy of storage classes is to delete volumes. You can create quasi-ephemeral local storage by using a storage class with a reclaim policy of retain. The storage outlives the pod, and in this case, you must ensure that volume clean-up happens separately. While these PVCs exist, they can be used like any other PVC. In particular, they can be referenced as data sources in volume cloning or snapshotting. The PVC object also holds the current status of the volume.

modules/storage-ephemeral-vols-overview.adoc

@@ -3,28 +3,28 @@
 // * storage/generic-ephemeral-vols.adoc
 //* microshift_storage/generic-ephemeral-volumes-microshift.adoc
 
-
 :_mod-docs-content-type: CONCEPT
 [id="generic-ephemeral-vols-overview_{context}"]
-= Overview
+= Overview of generic ephemeral volumes
 
-Generic ephemeral volumes are a type of ephemeral volume that can be provided by all storage drivers that support persistent volumes and dynamic provisioning. Generic ephemeral volumes are similar to `emptyDir` volumes in that they provide a per-pod directory for scratch data, which is usually empty after provisioning.
+[role="_abstract"]
+To manage scratch data by using standard storage drivers, use generic ephemeral volumes. These volumes provide per-pod directories similar to `emptyDir` volumes but work with any driver that supports persistent volumes and dynamic provisioning, so that you can leverage existing storage infrastructure for temporary needs.
 
-Generic ephemeral volumes are specified inline in the pod spec and follow the pod's lifecycle. They are created and deleted along with the pod.
+Generic ephemeral volumes are specified inline in the pod specification and follow the lifecycle of a pod. They are created and deleted along with the pod.
 
 Generic ephemeral volumes have the following features:
 
 * Storage can be local or network-attached.
 
-* Volumes can have a fixed size that pods are not able to exceed.
+* Volumes can have a fixed size that pods cannot exceed.
 
 * Volumes might have some initial data, depending on the driver and parameters.
 
 * Typical operations on volumes are supported, assuming that the driver supports them, including snapshotting, cloning, resizing, and storage capacity tracking.
 
 [NOTE]
 ====
-Generic ephemeral volumes do not support offline snapshots and resize.
+Generic ephemeral volumes do not support offline snapshotting and resizing.
 
 ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp,microshift[]
 Due to this limitation, the following Container Storage Interface (CSI) drivers do not support the following features for generic ephemeral volumes:

modules/storage-ephemeral-vols-procedure.adoc

@@ -8,6 +8,9 @@
 [id="generic-ephemeral-vols-procedure_{context}"]
 = Creating generic ephemeral volumes
 
+[role="_abstract"]
+Configure temporary storage by creating generic ephemeral volumes that use drivers that support dynamic provisioning.
+
 .Procedure
 
 . Create the `pod` object definition and save it to a file.
@@ -30,7 +33,7 @@ spec:
         name: data
       command: [ "sleep", "1000000" ]
   volumes:
-    - name: data <1>
+    - name: data
       ephemeral:
         volumeClaimTemplate:
           metadata:
@@ -49,4 +52,5 @@ endif::microshift[]
                 storage: 1Gi
 
 ----
-<1> Generic ephemeral volume claim.
+** `volumes.name`:: Specifies the name for the generic ephemeral volume.
+

modules/storage-ephemeral-vols-pvc-naming.adoc

@@ -7,7 +7,8 @@
 [id="generic-ephemeral-vols-pvc-naming_{context}"]
 = Persistent volume claim naming
 
-Automatically created persistent volume claims (PVCs) are named by a combination of the pod name and the volume name, with a hyphen (-) in the middle. This naming convention also introduces a potential conflict between different pods, and between pods and manually created PVCs.
+[role="_abstract"]
+To avoid resource conflicts, review the naming convention for automatically created persistent volume claims (PVCs). Because the system generates names by combining the pod name and volume name with a hyphen, you must ensure manually created resources do not inadvertently match this pattern.
 
 For example, `pod-a` with volume `scratch` and `pod` with volume `a-scratch` both end up with the same PVC name, `pod-a-scratch`.
 

modules/storage-ephemeral-vols-security.adoc

@@ -7,6 +7,9 @@
 [id="generic-ephemeral-security_{context}"]
 = Security
 
-You can enable the generic ephemeral volume feature to allows users who can create pods to also create persistent volume claims (PVCs) indirectly. This feature works even if these users do not have permission to create PVCs directly. Cluster administrators must be aware of this. If this does not fit your security model, use an admission webhook that rejects objects such as pods that have a generic ephemeral volume.
+[role="_abstract"]
+You can enable the generic ephemeral volume feature so that if a user can create pods, they can also create persistent volume claims (PVCs) indirectly. 
+
+The generic ephemeral volume feature works even if these users do not have permission to create PVCs directly. Cluster administrators must be aware of this. If this does not fit your security model, use an admission webhook that rejects objects such as pods that have a generic ephemeral volume.
 
 The normal namespace quota for PVCs still applies, so even if users are allowed to use this new mechanism, they cannot use it to circumvent other policies.

modules/storage-expanding-csi-volumes.adoc

@@ -3,14 +3,17 @@
 // * storage/expanding-persistent-volumes.adoc
 //* microshift_storage/expanding-persistent-volumes-microshift.adoc
 
-
 :_mod-docs-content-type: PROCEDURE
 [id="expanding-csi-volumes_{context}"]
 = Expanding CSI volumes
 
+[role="_abstract"]
 You can use the Container Storage Interface (CSI) to expand storage volumes after they have already been created.
 
+[IMPORTANT]
+====
 Shrinking persistent volumes (PVs) is _not_ supported.
+====
 
 .Prerequisites
 

modules/storage-expanding-filesystem-pvc.adoc

@@ -7,16 +7,16 @@
 [id="expanding-pvc-filesystem_{context}"]
 = Expanding persistent volume claims (PVCs) with a file system
 
+[role="_abstract"] 
 ifndef::microshift,openshift-rosa,openshift-rosa-hcp[]
 Expanding PVCs based on volume types that need file system resizing, such as GCE, EBS, and Cinder, is a two-step process. First, expand the volume objects in the cloud provider. Second, expand the file system on the node.
 endif::microshift,openshift-rosa,openshift-rosa-hcp[]
-
 ifdef::microshift[]
-Expanding PVCs based on volume types that need file system resizing, such as GCE Persistent Disk volumes (gcePD), AWS Elastic Block Store EBS (EBS), and Cinder, is a two-step process. First, expand the volume objects in the cloud provider. Second, expand the file system on the node.
+Expanding PVCs based on volume types that need file system resizing, such as GCE Persistent Disk volumes (gcePD), AWS Elastic Block Store (EBS), and Cinder, is a two-step process. First, expand the volume objects in the cloud provider. Second, expand the file system on the node.
 endif::microshift[]
 
 ifdef::openshift-rosa,openshift-rosa-hcp[]
-Expanding PVCs based on volume types that need file system resizing, such as AWS Elastic Block Store EBS (EBS) is a two-step process. First, expand the volume objects in the cloud provider. Second, expand the file system on the node.
+Expanding PVCs based on volume types that need file system resizing, such as AWS Elastic Block Store (EBS) is a two-step process. First, expand the volume objects in the cloud provider. Second, expand the file system on the node.
 endif::openshift-rosa,openshift-rosa-hcp[]
 
 Expanding the file system on the node only happens when a new pod is started with the volume.
@@ -41,10 +41,9 @@ spec:
     - ReadWriteOnce
   resources:
     requests:
-      storage: 8Gi <1>
+      storage: 8Gi
 ----
-[.small]
-<1> Updating `spec.resources.requests` to a larger amount expands the PVC.
+** `requests.storage`: Specifies the size for the PVC.
 
 . After the cloud provider object has finished resizing, the PVC is set to `FileSystemResizePending`. Check the condition by entering the following command:
 +
@@ -53,4 +52,4 @@ spec:
 $ oc describe pvc <pvc_name>
 ----
 
-. When the cloud provider object has finished resizing, the `PersistentVolume` object reflects the newly requested size in `PersistentVolume.Spec.Capacity`. At this point, you can create or recreate a new pod from the PVC to finish the file system resizing. Once the pod is running, the newly requested size is available and the `FileSystemResizePending` condition is removed from the PVC.
+. When the cloud provider object has finished resizing, the `PersistentVolume` object reflects the newly requested size in `PersistentVolume.Spec.Capacity`. At this point, you can create or re-create a pod from the PVC to finish the file system resizing. Once the pod is running, the newly requested size is available and the `FileSystemResizePending` condition is removed from the PVC.

modules/storage-expanding-local-volumes.adoc

@@ -8,6 +8,7 @@
 [id="expanding-local-volumes_{context}"]
 = Expanding local volumes
 
+[role="_abstract"]
 You can manually expand persistent volumes (PVs) and persistent volume claims (PVCs) created by using the local storage operator (LSO).
 
 .Procedure
@@ -16,8 +17,8 @@ You can manually expand persistent volumes (PVs) and persistent volume claims (P
 
 . Update the corresponding PV objects to match the new device sizes by editing the `.spec.capacity` field of the PV.
 
-. For the storage class that is used for binding the PVC to PVet, set `allowVolumeExpansion:true`.
+. For the storage class that is used for binding the PVC to PV, set the `allowVolumeExpansion` field to `true`.
 
-. For the PVC, set `.spec.resources.requests.storage` to match the new size.
-
-Kubelet should automatically expand the underlying file system on the volume, if necessary, and update the status field of the PVC to reflect the new size.
+. For the PVC, set the `.spec.resources.requests.storage` field to match the new size.
++
+Kubelet automatically expands the underlying file system on the volume, if necessary, and updates the status field of the PVC to reflect the new size.