OSDOCS-12592: Docs for OCPSTRAT-1577 OpenShift Zones support for vSphere Host Groups Day 1, IPI

Author: sslocket

installing/installing_vsphere/ipi/installing-restricted-networks-installer-provisioned-vsphere.adoc

@@ -39,6 +39,8 @@ include::modules/installation-creating-image-restricted.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-regions-zones.adoc[leveloffset=+1]
 
+include::modules/installation-vsphere-regions-zones-host-groups.adoc[leveloffset=+1]
+
 [role="_additional-resources"]
 .Additional resources
 
@@ -50,6 +52,8 @@ include::modules/installation-vsphere-regions-zones.adoc[leveloffset=+1]
 
 * xref:../../../storage/container_storage_interface/persistent-storage-csi-vsphere.adoc#persistent-storage-csi-vsphere-top-aware_persistent-storage-csi-vsphere[VMware vSphere CSI Driver Operator]
 
+* xref:../../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
+
 include::modules/installation-initializing.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -62,6 +66,12 @@ include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
 include::modules/configuring-vsphere-regions-zones.adoc[leveloffset=+2]
 
+include::modules/configuring-vsphere-host-groups.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
+
 // Services for a user-managed load balancer
 include::modules/nw-osp-services-external-load-balancer.adoc[leveloffset=+1]
 

installing/installing_vsphere/ipi/installing-vsphere-installer-provisioned-customizations.adoc

@@ -31,6 +31,8 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-regions-zones.adoc[leveloffset=+1]
 
+include::modules/installation-vsphere-regions-zones-host-groups.adoc[leveloffset=+1]
+
 [role="_additional-resources"]
 .Additional resources
 
@@ -42,6 +44,8 @@ include::modules/installation-vsphere-regions-zones.adoc[leveloffset=+1]
 
 * xref:../../../storage/container_storage_interface/persistent-storage-csi-vsphere.adoc#persistent-storage-csi-vsphere-top-aware_persistent-storage-csi-vsphere[VMware vSphere CSI Driver Operator]
 
+* xref:../../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
+
 include::modules/installation-initializing.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -54,6 +58,12 @@ include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
 include::modules/configuring-vsphere-regions-zones.adoc[leveloffset=+2]
 
+include::modules/configuring-vsphere-host-groups.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
+
 // Services for a user-managed load balancer
 include::modules/nw-osp-services-external-load-balancer.adoc[leveloffset=+1]
 

installing/installing_vsphere/ipi/installing-vsphere-installer-provisioned-network-customizations.adoc

@@ -33,6 +33,8 @@ include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-vsphere-regions-zones.adoc[leveloffset=+1]
 
+include::modules/installation-vsphere-regions-zones-host-groups.adoc[leveloffset=+1]
+
 [role="_additional-resources"]
 .Additional resources
 
@@ -44,6 +46,8 @@ include::modules/installation-vsphere-regions-zones.adoc[leveloffset=+1]
 
 * xref:../../../storage/container_storage_interface/persistent-storage-csi-vsphere.adoc#persistent-storage-csi-vsphere-top-aware_persistent-storage-csi-vsphere[VMware vSphere CSI Driver Operator]
 
+* xref:../../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
+
 include::modules/installation-initializing.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -58,6 +62,12 @@ include::modules/ipi-install-modifying-install-config-for-dual-stack-network.ado
 
 include::modules/configuring-vsphere-regions-zones.adoc[leveloffset=+2]
 
+include::modules/configuring-vsphere-host-groups.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
+
 // Specifying multiple NICS
 include::modules/installation-vsphere-multiple-nics.adoc[leveloffset=+2]
 

modules/configuring-vsphere-host-groups.adoc

@@ -0,0 +1,126 @@
+// Module included in the following assemblies:
+//
+//* /installing/installing_vsphere/ipi/installing-vsphere-installer-provisioned-customizations.adoc
+//* /installing/installing_vsphere/ipi/installing-vsphere-installer-provisioned-network-customizations.adoc
+//* /installing/installing_vsphere/ipi/installing-restricted-networks-installer-provisioned-vsphere.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-vsphere-host-groups_{context}"]
+= Configuring host groups for a VMware vCenter
+
+:FeatureName: Openshift zones support for vSphere host groups 
+include::snippets/technology-preview.adoc[]
+
+You can modify the default installation configuration file to deploy an {product-title} cluster on a {vmw-first} stretched cluster, where ESXi hosts are grouped into host groups by physical location.
+
+The default `install-config.yaml` file configuration from previous releases of {product-title} is deprecated. Though you can still use it, the {product-title} installer will display a warning message that indicates the use of deprecated fields in the configuration file.
+
+.Prerequisites
+
+* You have an existing `install-config.yaml` installation configuration file.
+* You have arranged your ESXi hosts into host groups.
+* You have granted the `Host.Inventory.EditCluster` privilege on the {vmw-short} vCenter cluster object.
+* You have downloaded and installed the `govc` command line tool. Instructions can be found on the VMware documentation website. Note that `govc` is an open-source tool that is not maintained by the Red{nbsp}Hat support team.
+* You have enabled the `TechPreviewNoUpgrade` feature set. For more information, see  "Enabling features using feature gates".
++
+[IMPORTANT]
+====
+To enable host group support, you must define multiple failure domains for your {product-title} cluster.
+====
+
+.Procedure
+
+. Create the `openshift-region` and `openshift-zone` vCenter tag categories by running the following commands:
++
+[IMPORTANT]
+====
+If you specify different names for the `openshift-region` and `openshift-zone` vCenter tag categories, the installation of the {product-title} cluster fails.
+====
+
++
+[source,terminal]
+----
+$ govc tags.category.create -d "OpenShift region" openshift-region
+----
++
+[source,terminal]
+----
+$ govc tags.category.create -d "OpenShift zone" openshift-zone
+----
+
+. Create a region tag for the {vmw-short} cluster where you want to deploy your {product-title} cluster by entering the following command:
++
+[source,terminal]
+----
+$ govc tags.create -c <region_tag_category> <region_tag>
+----
+
+. Create a zone tag for each host group by entering the following command as needed:
++
+[source,terminal]
+----
+$ govc tags.create -c <zone_tag_category> <zone_tag>
+----
+
+. Attach the region tag to the vCenter cluster object by entering the following command:
++
+[source,terminal]
+----
+$ govc tags.attach -c <region_tag_category> <region_tag_1> /<datacenter_1>/host/<cluster_1>
+----
+
+. Use zone tags to associate each ESXi host with its host group, by entering the following command for each ESXi host:
++
+[source,terminal]
+----
+$ govc tags.attach -c <zone_tag_category> <zone_tag_for_host_group_1> /<datacenter_1>/host/<cluster_1>/<esxi_host_in_host_group_1>
+----
+
+. Change to the directory that contains the installation program and initialize the cluster deployment according to your chosen installation requirements.
+
+.Sample `install-config.yaml` file with multiple host groups
+
+[source,yaml]
+----
+featureSet: TechPreviewNoUpgrade
+featureGate:
+  - "VSphereHostVMGroupZonal=true"
+# ...
+platform:
+  vsphere:
+    vcenters:
+# ...
+    datacenters:
+      - <data_center_1_name>
+    failureDomains:
+    - name: <host_group_1>
+      region: <cluster_1_region_tag>
+      zone: <host_group_1_zone_tag>
+      regionType: "ComputeCluster"
+      zoneType: "HostGroup"
+      server: <fully_qualified_domain_name>
+      topology:
+        datacenter: <data_center_1>
+        computeCluster: "/<data_center_1>/host/<cluster_1>"
+        networks:
+        - <VM_Network1_name>
+        hostGroup: <host_group_1_name>
+        datastore: "/<data_center_1>/datastore/<datastore_1>"
+        resourcePool: "/<data_center_1>/host/<cluster_1>/Resources/<resourcePool_1>"
+        folder: "/<data_center_1>/vm/<folder_1>"
+    - name: <host_group_2>
+      region: <cluster_1_region_tag>
+      zone: <host_group_2_zone_tag>
+      regionType: "ComputeCluster"
+      zoneType: "HostGroup"
+      server: <fully_qualified_domain_name>
+      topology:
+        datacenter: <data_center_1>
+        computeCluster: "/<data_center_1>/host/<cluster_1>"
+        networks:
+        - <VM_Network1_name>
+        hostGroup: <host_group_2_name>
+        datastore: "/<data_center_1>/datastore/<datastore_1>"
+        resourcePool: "/<data_center_1>/host/<cluster_1>/Resources/<resourcePool_1>"
+        folder: "/<data_center_1>/vm/<folder_1>"
+----

modules/installation-configuration-parameters.adoc

@@ -2869,6 +2869,22 @@ endif::vsphere[]
     failureDomains:
       region:
 |If you define multiple failure domains for your cluster, you must attach the tag to each vCenter data center. To define a region, use a tag from the `openshift-region` tag category. For a single vSphere data center environment, you do not need to attach a tag, but you must enter an alphanumeric value, such as `datacenter`, for the parameter.
+If you want base your failure domains on host groups, attach these tags to your vSphere clusters instead of your data centers. 
+
+:FeatureName: Openshift zones support for vSphere host groups 
+include::snippets/technology-preview.adoc[]
+
+|String
+
+|platform:
+  vsphere:
+    failureDomains:
+      regionType:
+|Specifies the `ComputeCluster` region type to enable host groups. 
+
+:FeatureName: Openshift zones support for vSphere host groups 
+include::snippets/technology-preview.adoc[]
+
 |String
 
 |platform:
@@ -2883,6 +2899,22 @@ endif::vsphere[]
     failureDomains:
       zone:
 |If you define multiple failure domains for your cluster, you must attach a tag to each vCenter cluster. To define a zone, use a tag from the `openshift-zone` tag category. For a single vSphere data center environment, you do not need to attach a tag, but you must enter an alphanumeric value, such as `cluster`, for the parameter.
+If you want to base your failure domains on host groups, define zones that correspond to your host groups instead of your clusters. Use these tags to associate each ESXi host with its host group. 
+
+:FeatureName: Openshift zones support for vSphere host groups
+include::snippets/technology-preview.adoc[]
+
+|String
+
+|platform:
+  vsphere:
+    failureDomains:
+      zoneType:
+|Specifies the `HostGroup` zone type to enable host groups. 
+
+:FeatureName: Openshift zones support for vSphere host groups
+include::snippets/technology-preview.adoc[]
+
 |String
 
 |platform:
@@ -2940,6 +2972,18 @@ If you do not provide this value, the installation program creates a top-level f
 endif::vsphere[]
 |String
 
+|platform:
+  vsphere:
+    failureDomains:
+      topology:
+        hostGroup:
+|Specifies the vSphere host group to associate with the failure domain.
+
+:FeatureName: Openshift zones support for vSphere host groups
+include::snippets/technology-preview.adoc[]  
+
+|String
+
 |platform:
   vsphere:
     failureDomains:

modules/installation-vsphere-regions-zones-host-groups.adoc

@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+//* installing/installing-vsphere-installer-provisioned-customizations.adoc [IPI]
+//* installing/installing-vsphere-installer-provisioned-network-customizations.adoc [IPI]
+//* installing/installing-restricted-networks-installer-provisioned-vsphere.adoc [IPI]
+
+:_mod-docs-content-type: CONCEPT
+[id="installation-vsphere-regions-zones-host-groups_{context}"]
+= VMware vSphere host group enablement
+
+:FeatureName: Openshift zones support for vSphere host groups
+include::snippets/technology-preview.adoc[]
+
+When deploying an {product-title} cluster to {vmw-first}, you can map your {vmw-short} host groups onto {product-title} failure domains. This is useful if you are using a stretched cluster configuration, where ESXi hosts are grouped into host groups by physical location.
+
+To enable this feature, you must meet the following requirements:
+
+* You must arrange your ESXi hosts into host groups.
+* You must create a vCenter tag in the `openshift-region` tag category for your cluster. After you create the tag, you must attach the tag to the cluster.
+* You must create a vCenter tag in the `openshift-zone` tag category for each host group and then attach the correct tag to each ESXi host.
+* You must define multiple failure domains for your {product-title} cluster in the `install-config.yaml` file.
+* You must grant the `Host.Inventory.EditCluster` privilege on the {vmw-short} vCenter cluster object.
+* You must include the following parameters in your `install-config.yaml` file to enable this Technology Preview feature:
++
+[source,yaml]
+----
+featureSet: TechPreviewNoUpgrade
+featureGate:
+  - "VSphereHostVMGroupZonal=true"
+----
++
+[NOTE]
+====
+For further information on feature gates, see "Enabling features using feature gates".
+====
+
+Review the following key terms, which correspond to parameters in your `install-config.yaml` file that you must configure to enable this feature:
+
+* Failure domain: Specifies the relationships between regions and zones in {product-title}, and clusters and host groups in {vmw-short}. You define a failure domain by using vCenter objects, such as a `datastore` object. A failure domain defines the vCenter location for {product-title} cluster nodes.
+* Region: Specifies a vCenter cluster. You define a region by using a tag from the `openshift-region` tag category.
+* Zone: Specifies a vCenter host group. You define a zone by using a tag from the `openshift-zone` tag category.
+* Region type: Specifies the `ComputeCluster` region type to enable this feature.
+* Zone type: Specifies the `HostGroup` zone type to enable this feature.