OSDOCS-16947#CQA work Stor3 - CSI basics

modules/persistent-storage-csi-architecture.adoc

@@ -7,17 +7,22 @@
 [id="persistent-storage-csi-architecture_{context}"]
 = CSI architecture
 
-CSI drivers are typically shipped as container images. These containers
-are not aware of {product-title} where they run. To use CSI-compatible
-storage back end in {product-title}, the cluster administrator must deploy
-several components that serve as a bridge between {product-title} and the
-storage driver.
+[role="_abstract"]
+Container Storage Interface (CSI) architecture uses containerized drivers and bridge components for communication between {product-title} and storage backends. Each driver requires controller deployments and daemon sets for volume operations. Multiple drivers can run simultaneously.
 
-The following diagram provides a high-level overview about the components
-running in pods in the {product-title} cluster.
+The Container Storage Interface (CSI) allows {product-title} to consume storage from storage back ends that implement the CSI interface as persistent storage.
+
+[NOTE]
+====
+{product-title} {product-version} supports version 1.6.0 of the CSI specification.
+====
+
+For more information about the CSI spec, see _CSI spec_ under _Additional resources_.
+
+CSI drivers are typically shipped as container images. These containers are not aware of {product-title} where they run. To use CSI-compatible storage back end in {product-title}, the cluster administrator must deploy several components that serve as a bridge between {product-title} and the storage driver.
+
+The following diagram provides a high-level overview about the components running in pods in the {product-title} cluster.
 
 image::csi-arch-rev1.png["Architecture of CSI components"]
 
-It is possible to run multiple CSI drivers for different storage back ends.
-Each driver needs its own external controllers deployment and daemon set
-with the driver and CSI registrar.
+It is possible to run multiple CSI drivers for different storage back ends. Each driver needs its own external controllers deployment and daemon set with the driver and CSI registrar.

modules/persistent-storage-csi-driver-daemonset.adoc

@@ -7,18 +7,11 @@
 [id="csi-driver-daemonset_{context}"]
 = CSI driver daemon set
 
-The CSI driver daemon set runs a pod on every node that allows
-{product-title} to mount storage provided by the CSI driver to the node
-and use it in user workloads (pods) as persistent volumes (PVs). The pod
-with the CSI driver installed contains the following containers:
+[role="_abstract"]
+CSI driver daemon sets run on every node to enable volume mounting and operations. Each pod contains a driver and registrar communicating with node services using UNIX Domain Sockets. The node driver uses minimal credentials and implements node-specific CSI operations like publish and stage.
 
-* A CSI driver registrar, which registers the CSI driver into the
-`openshift-node` service running on the node. The `openshift-node` process
-running on the node then directly connects with the CSI driver using the
-UNIX Domain Socket available on the node.
-* A CSI driver.
+The CSI driver daemon set runs a pod on every node that allows {product-title} to mount storage provided by the CSI driver to the node and use it in user workloads (pods) as persistent volumes (PVs). The pod with the CSI driver installed contains the following containers:
 
-The CSI driver deployed on the node should have as few credentials to the
-storage back end as possible. {product-title} will only use the node plugin
-set of CSI calls such as `NodePublish`/`NodeUnpublish` and
-`NodeStage`/`NodeUnstage`, if these calls are implemented.
+CSI driver registrar:: The CSI driver registrar registers the CSI driver into the `openshift-node` service running on the node. The `openshift-node` process running on the node then directly connects with the CSI driver using the UNIX Domain Socket available on the node.
+
+CSI driver:: The CSI driver deployed on the node should have as few credentials to the storage back end as possible. {product-title} will only use the node plugin set of CSI calls such as `NodePublish`/`NodeUnpublish` and `NodeStage`/`NodeUnstage`, if these calls are implemented.

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

@@ -7,7 +7,7 @@
 = CSI drivers supported by {product-title}
 
 [role="_abstract"]
-{product-title} installs certain CSI drivers by default, giving users storage options that are not possible with in-tree volume plugins.
+{product-title} installs several CSI drivers by default, automatically deploying the driver Operator, driver, and storage class for supported backends. Default drivers provide enhanced features beyond in-tree plugins. Some drivers, such as AWS EFS and GCP Filestore, require manual installation.
 
 To create CSI-provisioned persistent volumes that mount to these supported storage assets, {product-title} installs the necessary CSI driver Operator, the CSI driver, and the required storage class by default. For more details about the default namespace of the Operator and driver, see the documentation for the specific CSI Driver Operator.
 

modules/persistent-storage-csi-dynamic-provisioning.adoc

@@ -8,33 +8,36 @@
 [id="csi-dynamic-provisioning_{context}"]
 = Dynamic provisioning
 
-Dynamic provisioning of persistent storage depends on the capabilities of
-the CSI driver and underlying storage back end. The provider of the CSI
-driver should document how to create a storage class in {product-title} and
-the parameters available for configuration.
+[role="_abstract"]
+Dynamic provisioning creates persistent volumes on demand from storage class configurations. Container Storage Interface (CSI) drivers support specific parameters determining behavior. Create a default storage class to enable provisioning for claims without a specified class.
+
+Dynamic provisioning of persistent storage depends on the capabilities of the CSI driver and underlying storage back end. The provider of the CSI driver should document how to create a storage class in {product-title} and the parameters available for configuration.
 
 The created storage class can be configured to enable dynamic provisioning.
 
 .Procedure
 
-* Create a default storage class that ensures all PVCs that do not require
-any special storage class are provisioned by the installed CSI driver.
+* Create a default storage class that ensures all PVCs that do not require any special storage class are provisioned by the installed CSI driver.
 +
 [source,shell]
 ----
 # oc create -f - << EOF
 apiVersion: storage.k8s.io/v1
 kind: StorageClass
 metadata:
-  name: <storage-class> <1>
+  name: <storage-class>
   annotations:
     storageclass.kubernetes.io/is-default-class: "true"
-provisioner: <provisioner-name> <2>
+provisioner: <provisioner-name>
 parameters:
-  csi.storage.k8s.io/fstype: xfs  <3>
+  csi.storage.k8s.io/fstype: xfs
 EOF
 ----
-<1> The name of the storage class that will be created.
-<2> The name of the CSI driver that has been installed.
-<3> The vSphere CSI driver supports all of the file systems supported by the underlying Red Hat Core operating system release, including XFS and Ext4. 
++
+Where:
+* `metadata.name`: The name of the storage class that will be created.
+
+* `provisioner`: The name of the CSI driver that has been installed.
+
+* `parameters.csi.storage.k8s.io/fstype`: The vSphere CSI driver supports all of the file systems supported by the underlying Red Hat Core operating system release, including XFS and Ext4. 
 

modules/persistent-storage-csi-external-controllers.adoc

@@ -7,38 +7,31 @@
 [id="external-csi-contollers_{context}"]
 = External CSI controllers
 
-External CSI controllers is a deployment that deploys one or more pods
-with five containers:
+[role="_abstract"]
+External Container Storage Interface (CSI) controllers run as deployments with containers handling volume provisioning, deletion, attachment, snapshotting, and resizing. Controller pods communicate with CSI drivers using UNIX Domain Sockets and run on infrastructure nodes to protect credentials.
+
+External CSI controllers is a deployment that deploys one or more pods with five containers:
 
 * The snapshotter container watches `VolumeSnapshot` and `VolumeSnapshotContent` objects and is responsible for the creation and deletion of `VolumeSnapshotContent` object.
+
 * The resizer container is a sidecar container that watches for `PersistentVolumeClaim` updates and triggers `ControllerExpandVolume` operations against a CSI endpoint if you request more storage on `PersistentVolumeClaim` object.
-* An external CSI attacher container translates `attach` and `detach`
-calls from {product-title} to respective `ControllerPublish` and
+
+* An external CSI attacher container translates `attach` and `detach` calls from {product-title} to respective `ControllerPublish` and
 `ControllerUnpublish` calls to the CSI driver.
-* An external CSI provisioner container that translates `provision` and
-`delete` calls from {product-title} to respective `CreateVolume` and
-`DeleteVolume` calls to the CSI driver.
+
+* An external CSI provisioner container that translates `provision` and `delete` calls from {product-title} to respective `CreateVolume` and `DeleteVolume` calls to the CSI driver.
+
 * A CSI driver container.
 
-The CSI attacher and CSI provisioner containers communicate with the CSI
-driver container using UNIX Domain Sockets, ensuring that no CSI
-communication leaves the pod. The CSI driver is not accessible from
-outside of the pod.
+The CSI attacher and CSI provisioner containers communicate with the CSI driver container using UNIX Domain Sockets, ensuring that no CSI
+communication leaves the pod. The CSI driver is not accessible from outside of the pod.
 
 [NOTE]
 ====
-The `attach`, `detach`, `provision`, and `delete` operations typically require
-the CSI driver to use credentials to the storage backend. Run the CSI
-controller pods on infrastructure nodes so the credentials are never leaked
-to user processes, even in the event of a catastrophic security breach
-on a compute node.
+The `attach`, `detach`, `provision`, and `delete` operations typically require the CSI driver to use credentials to the storage backend. Run the CSI controller pods on infrastructure nodes so the credentials are never leaked to user processes, even in the event of a catastrophic security breach on a compute node.
 ====
 
 [NOTE]
 ====
-The external attacher must also run for CSI drivers that do not support
-third-party `attach` or `detach` operations. The external attacher will
-not issue any `ControllerPublish` or `ControllerUnpublish` operations to
-the CSI driver. However, it still must run to implement the necessary
-{product-title} attachment API.
+The external attacher must also run for CSI drivers that do not support third-party `attach` or `detach` operations. The external attacher does not issue any `ControllerPublish` or `ControllerUnpublish` operations to the CSI driver. However, it still must run to implement the necessary {product-title} attachment API.
 ====

modules/persistent-storage-csi-mysql-example.adoc

@@ -8,8 +8,8 @@
 [id="csi-example-usage_{context}"]
 = Example using the CSI driver
 
-The following example installs a default MySQL template without any
-changes to the template.
+[role="_abstract"]
+Deploy a MySQL application using Container Storage Interface (CSI) persistent storage to demonstrate dynamic volume provisioning. This example shows CSI drivers automatically creating and binding persistent volume claims to dynamically provisioned volumes without manual intervention.
 
 .Prerequisites
 
@@ -41,21 +41,16 @@ ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 .Example output
 [source,terminal]
 ----
-NAME              STATUS    VOLUME                                   CAPACITY
-ACCESS MODES   STORAGECLASS   AGE
-mysql             Bound     kubernetes-dynamic-pv-3271ffcb4e1811e8   1Gi
-RWO            cinder         3s
+NAME              STATUS    VOLUME                                   CAPACITY ACCESS MODES   STORAGECLASS   AGE
+mysql             Bound     kubernetes-dynamic-pv-3271ffcb4e1811e8   1Gi      RWO            cinder         3s
 ----
 endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 ifdef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 .Example output
 [source,terminal]
 ----
-NAME           STATUS         VOLUME                                   CAPACITY
-mysql          Bound          kubernetes-dynamic-pv-3271ffcb4e1811e8   1Gi
-
-ACCESS MODES   STORAGECLASS   AGE
-RWO            gp3-csi        3s
+NAME           STATUS         VOLUME                                   CAPACITY ACCESS MODES   STORAGECLASS   AGE
+mysql          Bound          kubernetes-dynamic-pv-3271ffcb4e1811e8   1Gi      RWO            gp3-csi        3s
 ----
 endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 

storage/container_storage_interface/persistent-storage-csi.adoc

@@ -6,18 +6,15 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-The Container Storage Interface (CSI) allows {product-title} to consume
-storage from storage back ends that implement the
-link:https://github.com/container-storage-interface/spec[CSI interface]
-as persistent storage.
-
-[NOTE]
-====
-{product-title} {product-version} supports version 1.6.0 of the link:https://github.com/container-storage-interface/spec[CSI specification].
-====
+[role="_abstract"] 
+Container Storage Interface (CSI) is a standard specification enabling storage vendors to develop plugins that work across container orchestration systems. {product-title} uses CSI drivers to provision and manage persistent storage from various backends, replacing the need for in-tree storage plugins.
 
 include::modules/persistent-storage-csi-architecture.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+.Additional resources
+* https://github.com/container-storage-interface/spec[CSI spec]
+
 include::modules/persistent-storage-csi-external-controllers.adoc[leveloffset=+2]
 
 include::modules/persistent-storage-csi-driver-daemonset.adoc[leveloffset=+2]