openshift · lpettyjo · May 11, 2023 · Feb 20, 2023
diff --git a/modules/persistent-storage-csi-vsphere-top-aware-during-install.adoc b/modules/persistent-storage-csi-vsphere-top-aware-during-install.adoc
@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// storage/container_storage_interface/persistent-storage-csi-vsphere.adoc
+//
+
+:content-type: PROCEDURE
+[id="persistent-storage-csi-vsphere-top-aware-during-install_{context}"]
+= Creating vSphere storage topology during installation
+
+== Procedure
+
+* Specify the topology during installation. See the _Configuring regions and zones for a VMware vCenter_ section.
+
+No additional action is necessary and the default storage class that is created by {product-title}
+is topology aware and should allow provisioning of volumes in different failure domains.
diff --git a/...istent-storage-csi-vsphere-top-aware.adoc → ...rage-csi-vsphere-top-aware-infra-top.adoc b/...istent-storage-csi-vsphere-top-aware.adoc → ...rage-csi-vsphere-top-aware-infra-top.adoc
@@ -1,43 +1,22 @@
 // Module included in the following assemblies:
 //
-// persistent-storage-csi-vsphere.adoc
+// storage/container_storage_interface/persistent-storage-csi-vsphere.adoc
 //
 
 :content-type: PROCEDURE
-[id="persistent-storage-csi-vsphere-top-aware_{context}"]
-= Configuring vSphere CSI Topology
-
-{product-title} provides the ability to deploy {product-title} for vSphere on different zones and regions, which allows you to deploy over multiple compute clusters, thus helping to avoid a single point of failure. 
+[id="persistent-storage-csi-vsphere-top-aware-infra-top_{context}"]
+= Creating vSphere storage topology without an infra topology
 
 [NOTE]
 ====
-{product-title} on vSphere does not support multiple Datacenters.
+{product-title} recommends using the infrastructure object for specifying failure domains in a topology aware setup. Specifying failure domains in the infrastructure object and specify topology-categories in the `ClusterCSIDriver` object at the same time is an unsupported operation.
 ====
 
-This is accomplished by defining zone and region categories in vCenter, and then assigning these categories to different failure domains, such as a compute cluster, by creating tags for these zone and region categories. After you have created the appropriate categories, and assigned tags to vCenter objects, you can create additional machinesets that create virtual machines (VMs) that are responsible for scheduling pods in those failure domains.
-
-.Procedure
+== Procedure
 . In the VMware vCenter vSphere client GUI, define appropriate zone and region catagories and tags.
 +
 While vSphere allows you to create categories with any arbitrary name, {product-title} strongly recommends use of `openshift-region` and `openshift-zone` names for defining topology.
 +
-The following example defines two failure domains with one region and two zones:
-+
-.vSphere topology with one region and two zones
-|===
-|Compute cluster | Failure domain |Description
-
-|Compute cluster: ocp1, 
-Datacenter: Atlanta
-|openshift-region: us-east-1 (tag), openshift-zone: us-east-1a (tag)
-|This defines a failure domain in region us-east-1 with zone us-east-1a.
-
-|Computer cluster: ocp2, 
-Datacenter: Atlanta
-|openshift-region: us-east-1 (tag), openshift-zone: us-east-1b (tag)
-|This defines a different failure domain within the same region called us-east-1b.
-|===
-+
 For more information about vSphere categories and tags, see the VMware vSphere documentation.
 
 . To allow the container storage interface (CSI) driver to detect this topology, edit the `clusterCSIDriver` object YAML file `driverConfig` section:
@@ -56,19 +35,19 @@ For more information about vSphere categories and tags, see the VMware vSphere d
 apiVersion: operator.openshift.io/v1
 kind: ClusterCSIDriver
 metadata:
- name: csi.vsphere.vmware.com
+  name: csi.vsphere.vmware.com
 spec:
- logLevel: Normal
- managementState: Managed
- observedConfig: null
- operatorLogLevel: Normal
- unsupportedConfigOverrides: null
- driverConfig: 
-  driverType: vSphere <1>
-    vSphere:
-      topologyCategories: <2>
-      - openshift-zone
-      - openshift-region
+  logLevel: Normal
+  managementState: Managed
+  observedConfig: null
+  operatorLogLevel: Normal
+  unsupportedConfigOverrides: null
+  driverConfig: 
+    driverType: vSphere <1>
+      vSphere:
+        topologyCategories: <2>
+        - openshift-zone
+        - openshift-region
 ----
 <1> Ensure that `driverType` is set to `vSphere`.
 <2> `openshift-zone` and `openshift-region` categories created earlier in vCenter.
@@ -84,14 +63,14 @@ spec:
 +
 [source, terminal]
 ----
-NAME                        DRIVERS     AGE
-co8-4s88d-infra-2m5vd       1           27m
-co8-4s88d-master-0          1           70m
-co8-4s88d-master-1          1           70m
-co8-4s88d-master-2          1           70m
-co8-4s88d-worker-j2hmg      1           47m
-co8-4s88d-worker-mbb46      1           47m
-co8-4s88d-worker-zlk7d      1           47m
+NAME DRIVERS AGE
+co8-4s88d-infra-2m5vd 1 27m
+co8-4s88d-master-0 1 70m
+co8-4s88d-master-1 1 70m
+co8-4s88d-master-2 1 70m
+co8-4s88d-worker-j2hmg 1 47m
+co8-4s88d-worker-mbb46 1 47m
+co8-4s88d-worker-zlk7d 1 47m
 ----
 +
 [source, terminal]
@@ -105,14 +84,14 @@ co8-4s88d-worker-zlk7d      1           47m
 ----
 ...
 spec:
-    drivers:
-    - allocatable:
-        count: 59
-    name: csi-vsphere.vmware.com
-    nodeID: co8-4s88d-worker-j2hmg
-    topologyKeys: <1>
-    - topology.csi.vmware.com/openshift-zone
-    - topology.csi.vmware.com/openshift-region
+  drivers:
+  - allocatable:
+      count: 59
+  name: csi-vsphere.vmware.com
+  nodeID: co8-4s88d-worker-j2hmg
+  topologyKeys: <1>
+  - topology.csi.vmware.com/openshift-zone
+  - topology.csi.vmware.com/openshift-region
 ----
 <1> Topology keys from vSphere `openshift-zone` and `openshift-region` catagories.
 +
@@ -172,38 +151,4 @@ volumeBindingMode: WaitForFirstConsumer
 [NOTE]
 ====
 You can also create the storage class by editing the preceding YAML file and running the command `oc create -f $FILE`.
-====
-
-.Results
-Creating persistent volume claims (PVCs) and PVs from the topology aware storage class are truly zonal, and should use the datastore in their respective zone depending on how pods are scheduled:
-
-[source, terminal]
-----
-~ $ oc get pv <pv-name> -o yaml
-----
-
-.Example output
-
-[source, terminal]
-----
-...
-nodeAffinity:
-  required:
-    nodeSelectorTerms:
-    - matchExpressions:
-      - key: topology.csi.vmware.com/openshift-zone <1>
-        operator: In  
-        values:
-        - <openshift-zone>
-      -key: topology.csi.vmware.com/openshift-region <1>
-        operator: In
-        values:
-        - <openshift-region>
-...
-peristentVolumeclaimPolicy: Delete
-storageClassName: <zoned-storage-class-name> <2>
-volumeMode: Filesystem
-...
-----
-<1> PV has zoned keys.
-<2> PV is using the zoned storage class.
+====
diff --git a/modules/persistent-storage-csi-vsphere-top-aware-overview.adoc b/modules/persistent-storage-csi-vsphere-top-aware-overview.adoc
@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+//
+// storage/container_storage_interface/persistent-storage-csi-vsphere.adoc
+//
+
+:content-type: CONCEPT
+[id="persistent-storage-csi-vsphere-top-aware-overview_{context}"]
+= vSphere CSI topology overview
+
+{product-title} provides the ability to deploy {product-title} for vSphere on different zones and regions, which allows you to deploy over multiple compute clusters and datacenters, thus helping to avoid a single point of failure. 
+
+This is accomplished by defining zone and region categories in vCenter, and then assigning these categories to different failure domains, such as a compute cluster, by creating tags for these zone and region categories. After you have created the appropriate categories, and assigned tags to vCenter objects, you can create additional machinesets that create virtual machines (VMs) that are responsible for scheduling pods in those failure domains.
+
+The following example defines two failure domains with one region and two zones:
+
+.vSphere storage topology with one region and two zones
+|===
+|Compute cluster | Failure domain |Description
+
+|Compute cluster: ocp1, 
+Datacenter: Atlanta
+|openshift-region: us-east-1 (tag), openshift-zone: us-east-1a (tag)
+|This defines a failure domain in region us-east-1 with zone us-east-1a.
+
+|Computer cluster: ocp2, 
+Datacenter: Atlanta
+|openshift-region: us-east-1 (tag), openshift-zone: us-east-1b (tag)
+|This defines a different failure domain within the same region called us-east-1b.
+|===
diff --git a/modules/persistent-storage-csi-vsphere-top-aware-post-install.adoc b/modules/persistent-storage-csi-vsphere-top-aware-post-install.adoc
@@ -0,0 +1,70 @@
+// Module included in the following assemblies:
+//
+// storage/container_storage_interface/persistent-storage-csi-vsphere.adoc
+//
+
+:content-type: PROCEDURE
+[id="persistent-storage-csi-vsphere-top-aware-post-install_{context}"]
+= Creating vSphere storage topology post-installation
+
+== Procedure
+. In the VMware vCenter vSphere client GUI, define appropriate zone and region catagories and tags.
++
+While vSphere allows you to create categories with any arbitrary name, {product-title} strongly recommends use of `openshift-region` and `openshift-zone` names for defining topology categories.
++
+For more information about vSphere categories and tags, see the VMware vSphere documentation.
+
+. In {product-title}, create failure domains. See the _Specifying multiple regions and zones for your cluster on vSphere_ section.
+
+. Create a tag to assign to datastores across failure domains:
++
+When an {product-title} spans more than one failure domain, the datastore might not be shared across those failure domains, which is where topology-aware provisioning of persistent volumes (PVs) is useful. 
++
+.. In vCenter, create a category for tagging the datastores. For example, `openshift-zonal-datastore-cat`. You can use any other category name, provided the category uniquely is used for tagging datastores participating in {product-title} cluster. Also, ensure that `StoragePod`, `Datastore`, and `Folder` are selected as Associable Entities for the created category. 
+.. In vCenter, create a tag that uses the previously created category. This example uses the tag name `openshift-zonal-datastore`.
+.. Assign the previously created tag (in this example `openshift-zonal-datastore`) to each datastore in a failure domain that would be considered for dynamic provisioning.
++
+[NOTE]
+====
+You can use any names you like for datastore categories and tags. The names used in this example are provided as recommendations. Ensure that the tags and categories that you define uniquely identify only datastores that are shared with all hosts in the {product-title} cluster.
+====
+
+. As needed, create a storage policy that targets the tag-based datastores in each failure domain:
+.. In vCenter, from the main menu, click *Policies and Profiles*.
+.. On the *Policies and Profiles* page, in the navigation pane, click *VM Storage Policies*.
+.. Click *CREATE*.
+.. Type a name for the storage policy.
+.. For the rules, choose Tag Placement rules and select the tag and category that targets the desired datastores (in this example, the `openshift-zonal-datastore` tag).
++ 
+The datastores are listed in the storage compatibility table.
+
+. Create a new storage class that uses the new zoned storage policy:
+.. Click *Storage* > *StorageClasses*.
+.. On the *StorageClasses* page, click *Create StorageClass*.
+.. Type a name for the new storage class in *Name*.
+.. Under *Provisioner*, select *csi.vsphere.vmware.com*. 
+.. Under *Additional parameters*, for the StoragePolicyName parameter, set *Value* to the name of the new zoned storage policy that you created earlier.
+.. Click *Create*.
++
+.Example output
++
+[source, yaml]
+----
+kind: StorageClass
+apiVersion: storage.k8s.io/v1
+metadata:
+  name: zoned-sc <1>
+provisioner: csi.vsphere.vmware.com
+parameters:
+  StoragePolicyName: zoned-storage-policy <2>
+reclaimPolicy: Delete
+allowVolumeExpansion: true
+volumeBindingMode: WaitForFirstConsumer
+----
+<1> New topology aware storage class name.
+<2> Specify zoned storage policy.
++
+[NOTE]
+====
+You can also create the storage class by editing the preceding YAML file and running the command `oc create -f $FILE`.
+====
diff --git a/modules/persistent-storage-csi-vsphere-top-aware-results.adoc b/modules/persistent-storage-csi-vsphere-top-aware-results.adoc
@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// storage/container_storage_interface/persistent-storage-csi-vsphere.adoc
+//
+
+:content-type: PROCEDURE
+[id="persistent-storage-csi-vsphere-top-aware-results_{context}"]
+= Results
+
+Creating persistent volume claims (PVCs) and PVs from the topology aware storage class are truly zonal, and should use the datastore in their respective zone depending on how pods are scheduled:
+
+[source, terminal]
+----
+~ $ oc get pv <pv-name> -o yaml
+----
+
+.Example output
+
+[source, terminal]
+----
+...
+nodeAffinity:
+  required:
+    nodeSelectorTerms:
+    - matchExpressions:
+      - key: topology.csi.vmware.com/openshift-zone <1>
+        operator: In 
+        values:
+        - <openshift-zone>
+      -key: topology.csi.vmware.com/openshift-region <1>
+        operator: In
+        values:
+        - <openshift-region>
+...
+peristentVolumeclaimPolicy: Delete
+storageClassName: <zoned-storage-class-name> <2>
+volumeMode: Filesystem
+...
+----
+<1> PV has zoned keys.
+<2> PV is using the zoned storage class.
diff --git a/storage/container_storage_interface/persistent-storage-csi-vsphere.adoc b/storage/container_storage_interface/persistent-storage-csi-vsphere.adoc
@@ -48,11 +48,6 @@ To remove a third-party CSI driver, see xref:../../storage/container_storage_int
 
 include::modules/persistent-storage-csi-vsphere-install-issues.adoc[leveloffset=+1]
 
-include::modules/persistent-storage-csi-vsphere-top-aware.adoc[leveloffset=+1]
-[role="_additional-resources"]
-.Additional resources
-* https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vcenter-esxi-management/GUID-16422FF7-235B-4A44-92E2-532F6AED0923.html?hWord=N4IghgNiBcIC5gOYgL5A[VMware vSphere tag documentation]
-
 [id="vsphere-pv-encryption"]
 == vSphere persistent disks encryption
 
@@ -83,6 +78,25 @@ include::modules/persistent-storage-csi-vsphere-encryption-datastore-url.adoc[le
 
 include::modules/persistent-storage-csi-vsphere-encryption-tag-based.adoc[leveloffset=+2]
 
-[id="additional-resources"]
+include::modules/persistent-storage-csi-vsphere-top-aware-overview.adoc[leveloffset=+1]
+
+include::modules/persistent-storage-csi-vsphere-top-aware-during-install.adoc[leveloffset=+2]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc#configuring-vsphere-regions-zones_installing-vsphere-installer-provisioned-network-customizations[Configuring regions and zones for a VMware vCenter]
+
+include::modules/persistent-storage-csi-vsphere-top-aware-post-install.adoc[leveloffset=+2]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../post_installation_configuration/post-install-vsphere-zones-regions-configuration.adoc#specifying-regions-zones-infrastructure-vsphere_post-install-vsphere-zones-regions-configuration[Specifying multiple regions and zones for your cluster on vSphere]
+* https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vcenter-esxi-management/GUID-16422FF7-235B-4A44-92E2-532F6AED0923.html?hWord=N4IghgNiBcIC5gOYgL5A[VMware vSphere tag documenation]
+
+include::modules/persistent-storage-csi-vsphere-top-aware-infra-top.adoc[leveloffset=+2]
+[role="_additional-resources"]
+.Additional resources
+* https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vcenter-esxi-management/GUID-16422FF7-235B-4A44-92E2-532F6AED0923.html?hWord=N4IghgNiBcIC5gOYgL5A[VMware vSphere tag documenation]
+
+include::modules/persistent-storage-csi-vsphere-top-aware-results.adoc[leveloffset=+2]
+
 == Additional resources
-* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[Configuring CSI volumes]
+* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[Configuring CSI volumes]