Merge pull request #13994 from huffmanca/OSDOCS-318-2

OSDOCS-318: Following up on peer review changes.

Author: huffmanca

_topic_map.yml

@@ -298,7 +298,7 @@ Name: Storage
 Dir: storage
 Distros: openshift-*
 Topics:
-- Name: Persistent storage
+- Name: Understanding persistent storage
   File: understanding-persistent-storage
 - Name: Configuring persistent storage
   Dir: persistent-storage

modules/storage-persistent-storage-block-volume-examples.adoc

@@ -135,5 +135,5 @@ match the  name of the PVC as expected.
 
 [IMPORTANT]
 ====
-Unspecified values result in the default value of *Filesystem*.
+Unspecified values result in the default value of `Filesystem`.
 ====

modules/storage-persistent-storage-block-volume.adoc

@@ -12,10 +12,10 @@ You can statically provision raw block volumes by including API fields
 in your PV and PVC specifications. This functionality is only available for
 manually provisioned PVs.
 
-To use block volume, you must first enable the `BlockVolume` feature gate. 
-To enable the feature gates for master(s), add `feature-gates` to
+To use a block volume, you must first enable the `BlockVolume` feature 
+gate. To enable the feature gates for master(s), add `feature-gates` to
 `apiServerArguments` and `controllerArguments`. To enable the feature 
-gates fornode(s), add `feature-gates` to `kubeletArguments`. For example:
+gates for node(s), add `feature-gates` to `kubeletArguments`. For example:
 
 ----
 kubeletArguments:

modules/storage-persistent-storage-lifecycle.adoc

@@ -34,23 +34,23 @@ with manually provisioned PVs. To minimize the excess, {product-title}
 binds to the smallest PV that matches all other criteria.
 
 Claims remain unbound indefinitely if a matching volume does not exist or 
-cannot be created with any available provisioner servicing a storage 
+can not be created with any available provisioner servicing a storage 
 class. Claims are bound as matching volumes become available. For example, 
 a cluster with many manually provisioned 50Gi volumes would not match a 
 PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the 
 cluster.
 
 [[using]]
-== Use pods and claimed PVs
+== Use Pods and claimed PVs
 
 Pods use claims as volumes. The cluster inspects the claim to find the bound
-volume and mounts that volume for a pod. For those volumes that support 
+volume and mounts that volume for a Pod. For those volumes that support 
 multiple access modes, you must specify which mode applies when you use 
-the claim as a volume in a pod.
+the claim as a volume in a Pod.
 
 Once you have a claim and that claim is bound, the bound PV belongs to you
-for as long as you need it. You can schedule pods and access claimed
-PVs by including `persistentVolumeClaim` in the pod's volumes block.
+for as long as you need it. You can schedule Pods and access claimed
+PVs by including `persistentVolumeClaim` in the Pod's volumes block.
 
 ifdef::openshift-origin,openshift-enterprise[]
 
@@ -77,11 +77,13 @@ The reclaim policy of a `PersistentVolume` tells the cluster what to do with
 the volume after it is released. Volumes reclaim policy can either be 
 `Retain`, `Recycle`, or `Delete`.
 
-`Retain` reclaim policy allows manual reclamation of the resource for 
-those volume plug-ins that support it. `Delete` reclaim policy deletes 
-both the `PersistentVolume` object from {product-title} and the associated 
-storage asset in external infrastructure, such as AWS EBS, GCE PD, or 
-Cinder volume.
+* `Retain` reclaim policy allows manual reclamation of the resource for 
+those volume plug-ins that support it. 
+* `Recycle` reclaim policy recycles the volume back into the pool of
+unbound persistent volumes once it is released from its claim.
+* `Delete` reclaim policy deletes  both the `PersistentVolume` object 
+from {product-title} and the associated storage asset in external 
+infrastructure, such as AWS EBS, GCE PD, or Cinder volume.
 
 [NOTE]
 ====

modules/storage-persistent-storage-overview.adoc

@@ -3,7 +3,7 @@
 // storage/understanding-persistent-storage.adoc[leveloffset=+1]
 
 [id=persistent-storage-overview-{context}]
-= Persistent Storage Overview
+= Persistent storage overview
 
 Managing storage is a distinct problem from managing compute resources.
 {product-title} uses the Kubernetes persistent volume (PV) framework to 
@@ -14,15 +14,15 @@ 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 cannot then be bound to additional PVCs. This has the effect of 
+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.
 
 PVs are defined by a `PersistentVolume` API object, which represents a 
 piece of existing, networked storage in the cluster that was provisioned 
 by the  cluster administrator. It is a resource in the cluster just like a 
 node is a cluster resource. PVs are volume plug-ins like `Volumes` but 
-have a lifecycle that is independent of any individual pod that uses the 
+have a lifecycle that is independent of any individual Pod that uses the 
 PV. PV objects capture the details of the implementation of the storage, 
 be that NFS, iSCSI, or a cloud-provider-specific storage system.
 
@@ -33,8 +33,8 @@ storage provider.
 ====
 
 PVCs are defined by a `PersistentVolumeClaim` API object, which represents a
-request for storage by a developer. It is similar to a pod in that pods 
-consume node resources and PVCs consume PV resources. For example, pods 
-can request specific levels of resources (e.g., CPU and memory), while 
+request for storage by a developer. It is similar to a Pod in that Pods 
+consume node resources and PVCs consume PV resources. For example, Pods 
+can request specific levels of resources, such as CPU and memory, while 
 PVCs can request specific storage capacity and access modes. For example, 
-they can be mounted once read/write or many times read-only.
+they can be mounted once read-write or many times read-only.

modules/storage-persistent-storage-pv.adoc

@@ -3,7 +3,7 @@
 // * storage/understanding-persistent-storage.adoc
 
 [id='persistent-volumes-{context}']
-= Persistent Volumes
+= Persistent volumes
 
 Each PV contains a `spec` and `status`, which is the specification and
 status of the volume, for example:
@@ -25,7 +25,7 @@ spec:
 status:
   ...  
 ----
-<1> Name of the persistent volume
+<1> Name of the persistent volume.
 <2> The amount of storage available to the volume.
 <3> The access mode, defining the read-write and mount permissions.
 <4> The reclaim policy, indicating how the resource should be handled
@@ -65,7 +65,7 @@ requested. Future attributes may include IOPS, throughput, and so on.
 A `PersistentVolume` can be mounted on a host in any way supported by the
 resource provider. Providers have different capabilities and each PV's
 access modes are set to the specific modes supported by that particular 
-volume. For example, NFS can support multiple read/write clients, but a 
+volume. For example, NFS can support multiple read-write clients, but a 
 specific NFS PV might be exported on the server as read-only. Each PV gets 
 its own set of access modes describing that specific PV's capabilities.
 
@@ -98,7 +98,7 @@ The following table lists the access modes:
 |The volume can be mounted as read-write by a single node.
 |ReadOnlyMany
 |`ROX`
-|The volume can be mounted read-only by many nodes.
+|The volume can be mounted as read-only by many nodes.
 |ReadWriteMany
 |`RWX`
 |The volume can be mounted as read-write by many nodes.
@@ -118,7 +118,7 @@ iSCSI and Fibre Channel volumes do not currently have any fencing
 mechanisms. You must ensure the volumes are only used by one node at a 
 time. In certain situations, such as draining a node, the volumes can be 
 used simultaneously by two nodes. Before draining the node, first ensure 
-the pods that use these volumes are deleted.
+the Pods that use these volumes are deleted.
 ====
 
 .Supported access modes for PVs
@@ -142,7 +142,7 @@ the pods that use these volumes are deleted.
 
 [NOTE]
 ====
-Use a recreate deployment strategy for pods that rely on AWS EBS.
+Use a recreate deployment strategy for Pods that rely on AWS EBS.
 // GCE Persistent Disks, or Openstack Cinder PVs. 
 ====
 
@@ -158,28 +158,28 @@ ifdef::openshift-dedicated[]
  * PVs are provisioned with either EBS volumes (AWS) or GCP storage (GCP), 
 depending on where the cluster is provisioned.
  * Only RWO access mode is applicable, as EBS volumes and GCE Persistent 
-Disks cannot be mounted to multiple nodes.
- * *emptyDir* has the same lifecycle as the pod:
+Disks can not be mounted to multiple nodes.
+ * *emptyDir* has the same lifecycle as the Pod:
    ** *emptyDir* volumes survive container crashes/restarts.
-   ** *emptyDir* volumes are deleted when the pod is deleted.
+   ** *emptyDir* volumes are deleted when the Pod is deleted.
 endif::[]
 
 ifdef::openshift-online[]
  * PVs are provisioned with EBS volumes (AWS).
  * Only RWO access mode is applicable, as EBS volumes and GCE Persistent 
-Disks cannot be mounted to multiple nodes.
+Disks can not be mounted to multiple nodes.
  * Docker volumes are disabled.
    ** VOLUME directive without a mapped external volume fails to be 
 instantiated
 .  
  * *emptyDir* is restricted to 512 Mi per project (group) per node.
-   ** A single pod for a project on a particular node can use up to 512 Mi 
+   ** A single Pod for a project on a particular node can use up to 512 Mi 
 of *emptyDir* storage.
-   ** Multiple pods for a project on a particular node share the 512 Mi of 
+   ** Multiple Pods for a project on a particular node share the 512 Mi of 
 *emptyDir* storage. 
- *  *emptyDir* has the same lifecycle as the pod:
+ *  *emptyDir* has the same lifecycle as the Pod:
    ** *emptyDir* volumes survive container crashes/restarts.
-   ** *emptyDir* volumes are deleted when the pod is deleted.
+   ** *emptyDir* volumes are deleted when the Pod is deleted.
 endif::[]
 
 [[pv-reclaim-policy]]
@@ -201,7 +201,7 @@ The following table lists the current reclaim policy:
 
 [WARNING]
 ====
-If you do not want to retain all pods, use dynamic provisioning.
+If you do not want to retain all Pods, use dynamic provisioning.
 ====
 
 [[pv-phase]]

modules/storage-persistent-storage-pvc.adoc

@@ -3,7 +3,7 @@
 // * storage/understanding-persistent-storage.adoc
 
 [id='persistent-volume-claims-{context}']
-= Persistent Volume Claims
+= Persistent volume claims
 
 Each persistent volume claim (PVC) contains a `spec` and `status`, which 
 is the specification and status of the claim, for example:
@@ -55,19 +55,19 @@ specific access modes.
 [[pvc-resources]]
 == Resources
 
-Claims, such as pods, can request specific quantities of a resource. In 
+Claims, such as Pods, can request specific quantities of a resource. In 
 this case, the request is for storage. The same resource model applies to 
 volumes and claims.
 
 [[pvc-claims-as-volumes]]
 == Claims as volumes
 
 Pods access storage by using the claim as a volume. Claims must exist in the
-same namespace as the pod by using the claim. The cluster finds the claim 
-in the pod's namespace and uses it to get the `PersistentVolume` backing 
-the claim. The volume is mounted to the host and into the pod, for example:
+same namespace as the Pod by using the claim. The cluster finds the claim 
+in the Pod's namespace and uses it to get the `PersistentVolume` backing 
+the claim. The volume is mounted to the host and into the Pod, for example:
 
-.Mount volume to the host and into the pod example
+.Mount volume to the host and into the Pod example
 [source,yaml]
 ----
 kind: Pod
@@ -86,6 +86,6 @@ spec:
       persistentVolumeClaim:
         claimName: myclaim <3>
 ----
-<1> Path to mount the volume inside the pod
+<1> Path to mount the volume inside the Pod
 <2> Name of the volume to mount
 <3> Name of the PVC, that exists in the same namespace, to use

storage/understanding-persistent-storage.adoc

@@ -1,5 +1,5 @@
 [id='understanding-persistent-storage']
-= Understanding Persistent Storage
+= Understanding persistent storage
 include::modules/common-attributes.adoc[]
 :context: understanding-persistent-storage
 toc::[]