Merge pull request #64748 from dfitzmau/OCPBUGS-18561

OCPBUGS-18561: Added prere to vSphere docs for reachable vCenter

Author: stevsmit

installing/installing_vsphere/installing-vsphere-network-customizations.adoc

@@ -12,12 +12,12 @@ configuration options. By customizing your network configuration, your cluster
 can coexist with existing IP address allocations in your environment and
 integrate with existing MTU and VXLAN configurations.
 
+include::snippets/vcenter-support.adoc[]
+
 You must set most of the network configuration parameters during installation,
 and you can modify only `kubeProxy` configuration parameters in a running
 cluster.
 
-include::snippets/vcenter-support.adoc[]
-
 [IMPORTANT]
 ====
 The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the vSphere platform and the installation process of {product-title}. Use the user-provisioned infrastructure installation instructions as a guide; you are free to create the required resources through other methods.

modules/installation-configuration-parameters.adoc

@@ -1562,56 +1562,82 @@ ifdef::vsphere[]
 Additional VMware vSphere configuration parameters are described in the following table:
 
 .Additional VMware vSphere cluster parameters
-[cols=".^2,.^3a,.^3a",options="header"]
+[cols=".^2,.^4,.^2",options="header"]
 |====
 |Parameter|Description|Values
 
-|`platform.vsphere.apiVIPs`
+l|platform:
+    vsphere
+      apiVIPs
 |Virtual IP (VIP) addresses that you configured for control plane API access.
-a|Multiple IP addresses
+|Multiple IP addresses
 
-|`platform.vsphere.diskType`
+l|platform
+    vsphere
+      diskType
 |Optional. The disk provisioning method. This value defaults to the vSphere default storage policy if not set.
 |Valid values are `thin`, `thick`, or `eagerZeroedThick`.
 
-|`platform.vsphere.failureDomains`
+l|platform
+    vsphere
+      failureDomains
 |Establishes the relationships between a region and zone. 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.
 |String
 
-|`platform.vsphere.failureDomains.topology.networks`
+l|platform
+    vsphere
+      failureDomains
+        topology
+          networks
 |Lists any network in the vCenter instance that contains the virtual IP addresses and DNS records that you configured.
 |String
 
-|`platform.vsphere.failureDomains.region`
+l|platform
+    vsphere
+      failureDomains
+        region
 |If you define multiple failure domains for your cluster, you must attach the tag to each vCenter datacenter. To define a region, use a tag from the `openshift-region` tag category. For a single vSphere datacenter environment, you do not need to attach a tag, but you must enter an alphanumeric value, such as `datacenter`, for the parameter.
 |String
 
-|`platform.vsphere.failureDomains.zone`
+l|platform
+    vsphere
+      failureDomains
+        zone
 |If you define multiple failure domains for your cluster, you must attach the tag to each vCenter cluster. To define a zone, use a tag from the `openshift-zone` tag category. For a single vSphere datacenter environment, you do not need to attach a tag, but you must enter an alphanumeric value, such as `cluster`, for the parameter.
 |String
 
-|`platform.vsphere.failureDomains.template`
+l|platform
+    vsphere
+      failureDomains
+        template
 |Specify the absolute path to a pre-existing {op-system-first} image template or virtual machine. The installation program can use the image template or virtual machine to quickly install {op-system} on vSphere hosts. Consider using this parameter as an alternative to uploading an {op-system} image on vSphere hosts. The parameter is available for use only on installer-provisioned infrastructure.
 |String
 
-|`platform.vsphere.ingressVIPs`
+l|platform
+    vsphere
+      ingressVIPs
 |Virtual IP (VIP) addresses that you configured for cluster Ingress.
 |Multiple IP addresses
 
-|`platform.vsphere`
+l|platform
+    vsphere
 | Describes your account on the cloud platform that hosts your cluster. You can use the parameter to customize the platform. When providing additional configuration settings for compute and control plane machines in the machine pool, the parameter is optional. You can only specify one vCenter server for your {product-title} cluster.
 |String
 
-|`platform.vsphere.vcenters`
+l|platform
+    vsphere
+      vcenters
 |Lists any fully-qualified hostname or IP address of a vCenter server.
 |String
 
-|`platform.vsphere.vcenters.datacenters`
+l|platform
+    vsphere
+      vcenters
+        datacenters
 |Lists and defines the datacenters where {product-title} virtual machines (VMs) operate. The list of datacenters must match the list of datacenters specified in the `failureDomains` field.
 |String
 |====
 
-
 [id="deprecated-parameters-vsphere_{context}"]
 == Deprecated VMware vSphere configuration parameters
 
@@ -1620,96 +1646,122 @@ In {product-title} 4.13, the following vSphere configuration parameters are depr
 The following table lists each deprecated vSphere configuration parameter:
 
 .Deprecated VMware vSphere cluster parameters
-[cols=".^2,.^3a,.^3a",options="header"]
+[cols=".^2,.^4,.^2",options="header,word-wrap",subs="+quotes,+attributes"]
 |====
 |Parameter|Description|Values
 
-|`platform.vsphere.apiVIP`
+l|platform
+    vsphere
+      apiVIP
 |The virtual IP (VIP) address that you configured for control plane API access.
-a|An IP address, for example `128.0.0.1`.
 
-[NOTE]
-====
-In {product-title} 4.12 and later, the `apiVIP` configuration setting is deprecated. Instead, use a `List` format to enter a value in the `apiVIPs` configuration setting.
-====
+*Note:* In {product-title} 4.12 and later, the `apiVIP` configuration setting is deprecated. Instead, use a `List` format to enter a value in the `apiVIPs` configuration setting.
+a|An IP address, for example `128.0.0.1`.
 
-|`platform.vsphere.cluster`
+l|platform
+    vsphere
+      cluster
 |The vCenter cluster to install the {product-title} cluster in.
 |String
 
-|`platform.vsphere.datacenter`
+l|platform
+    vsphere
+      datacenter
 |Defines the datacenter where {product-title} virtual machines (VMs) operate.
 |String
 
-|`platform.vsphere.defaultDatastore`
+l|platform
+    vsphere
+      defaultDatastore
 |The name of the default datastore to use for provisioning volumes.
 |String
 
-|`platform.vsphere.folder`
+l|platform
+    vsphere
+      folder
 |Optional. The absolute path of an existing folder where the installation program creates the virtual machines. If you do not provide this value, the installation program creates a folder that is named with the infrastructure ID in the data center virtual machine folder.
 |String, for example, `/<datacenter_name>/vm/<folder_name>/<subfolder_name>`.
 
-|`platform.vsphere.ingressVIP`
-|Virtual IP (VIP) addresses that you configured for cluster Ingress.
-a|An IP address, for example `128.0.0.1`.
+l|platform
+    vsphere
+      ingressVIP
+|Virtual IP (VIP) addresses that you configured for cluster Ingress. 
 
-[NOTE]
-====
-In {product-title} 4.12 and later, the `ingressVIP` configuration setting is deprecated. Instead, use a `List` format to enter a value in the `ingressVIPs` configuration setting.
-====
+*Note:* In {product-title} 4.12 and later, the `ingressVIP` configuration setting is deprecated. Instead, use a `List` format to enter a value in the `ingressVIPs` configuration setting.
+a|An IP address, for example `128.0.0.1`.
 
-|`platform.vsphere.network`
+l|platform
+    vsphere
+      network
 |The network in the vCenter instance that contains the virtual IP addresses and DNS records that you configured.
 |String
 
-|`platform.vsphere.password`
+l|platform
+    vsphere
+      password
 |The password for the vCenter user name.
 |String
 
-|`platform.vsphere.resourcePool`
+l|platform
+    vsphere
+      resourcePool
 |Optional. The absolute path of an existing resource pool where the installation program creates the virtual machines. If you do not specify a value, the installation program installs the resources in the root of the cluster under `/<datacenter_name>/host/<cluster_name>/Resources`.
-|String, for example, `/<datacenter_name>/host/<cluster_name>/Resources/<resource_pool_name>/<optional_nested_resource_pool_name>`.
+a|String, for example, `/<datacenter_name>/host/<cluster_name>/Resources/<resource_pool_name>/<optional_nested_resource_pool_name>`.
 
-|`platform.vsphere.username`
+l|platform
+    vsphere
+      username
 |The user name to use to connect to the vCenter instance with. This user must have at least
 the roles and privileges that are required for
 link:https://github.com/vmware-archive/vsphere-storage-for-kubernetes/blob/master/documentation/vcp-roles.md[static or dynamic persistent volume provisioning]
 in vSphere.
 |String
 
-|`platform.vsphere.vCenter`
+l|platform
+    vsphere
+      vCenter
 |The fully-qualified hostname or IP address of a vCenter server.
 |String
 |====
 
-
 [id="installation-configuration-parameters-optional-vsphere_{context}"]
 == Optional VMware vSphere machine pool configuration parameters
 
 Optional VMware vSphere machine pool configuration parameters are described in the following table:
 
 .Optional VMware vSphere machine pool parameters
-[cols=".^2,.^3a,.^3a",options="header"]
+[cols=".^2a,.^3a,.^3a",options="header"]
 |====
 |Parameter|Description|Values
 
-|`platform.vsphere.clusterOSImage`
+l|platform
+    vsphere
+      clusterOSImage
 |The location from which the installation program downloads the {op-system-first} image. Before setting a path value for this parameter, ensure that the {op-system} image's version matches the version of {op-system} that you installed on your {product-title} cluster.
 |An HTTP or HTTPS URL, optionally with a SHA-256 checksum. For example, `\https://mirror.openshift.com/images/rhcos-<version>-vmware.<architecture>.ova`.
 
-|`platform.vsphere.osDisk.diskSizeGB`
+l|platform
+    vsphere
+      osDisk
+        diskSizeGB
 |The size of the disk in gigabytes.
 |Integer
 
-|`platform.vsphere.cpus`
+l|platform
+    vsphere
+      cpus
 |The total number of virtual processor cores to assign a virtual machine. The value of `platform.vsphere.cpus` must be a multiple of `platform.vsphere.coresPerSocket` value.
 |Integer
 
-|`platform.vsphere.coresPerSocket`
+l|platform
+    vsphere
+      coresPerSocket
 |The number of cores per socket in a virtual machine. The number of virtual sockets on the virtual machine is `platform.vsphere.cpus`/`platform.vsphere.coresPerSocket`. The default value for control plane nodes and worker nodes is `4` and `2`, respectively.
 |Integer
 
-|`platform.vsphere.memoryMB`
+l|platform
+    vsphere
+      memoryMB
 |The size of a virtual machine's memory in megabytes.
 |Integer
 |====

modules/installation-initializing-manual.adoc

@@ -26,7 +26,7 @@ ifeval::["{context}" == "installing-azure-stack-hub-user-infra"]
 :ash:
 endif::[]
 ifeval::["{context}" == "installing-restricted-networks-vsphere"]
-:restricted:
+:restricted-upi:
 endif::[]
 ifeval::["{context}" == "installing-restricted-networks-bare-metal"]
 :restricted:
@@ -65,7 +65,10 @@ ifeval::["{context}" == "installing-ibm-power-vs-private-cluster"]
 :ibm-power-vs-private:
 endif::[]
 ifeval::["{context}" == "installing-vsphere"]
-:three-node-cluster:
+:vsphere-upi-vsphere:
+endif::[]
+ifeval::["{context}" == "installing-vsphere-network-customizations"]
+:vsphere-upi:
 endif::[]
 
 :_content-type: PROCEDURE
@@ -75,6 +78,14 @@ endif::[]
 ifndef::aws-china,aws-gov,aws-secret,azure-gov,ash,aws-private,azure-private,gcp-private,gcp-shared,ash-default,ash-network,ibm-cloud-private,ibm-power-vs-private[]
 For user-provisioned installations of {product-title}, you manually generate your installation configuration file.
 endif::aws-china,aws-gov,aws-secret,azure-gov,ash,aws-private,azure-private,gcp-private,gcp-shared,ash-default,ash-network,ibm-cloud-private,ibm-power-vs-private[]
+ifdef::vsphere-upi,restricted-upi[]
+For user-provisioned installations of {product-title}, you manually generate your installation configuration file.
+
+[IMPORTANT]
+====
+The Cluster Cloud Controller Manager Operator performs a connectivity check on a provided hostname or IP address. Ensure that you specify a hostname or an IP address to a reachable vCenter server. If you provide metadata to a non-existent vCenter server, installation of the cluster fails at the bootstrap stage.
+====
+endif::vsphere-upi,restricted-upi[]
 ifdef::aws-china,aws-gov,aws-secret[]
 Installing the cluster requires that you manually generate the installation configuration file.
 //Made this update as part of feedback in PR3961. tl;dr Simply state you have to create the config file, instead of creating a number of conditions to explain why.
@@ -101,11 +112,11 @@ endif::aws-china,aws-secret[]
 * You have an SSH public key on your local machine to provide to the installation program. The key will be used for SSH authentication onto your cluster nodes for debugging and disaster recovery.
 * You have obtained the {product-title} installation program and the pull secret for your
 cluster.
-ifdef::restricted[]
+ifdef::restricted,restricted-upi[]
 * Obtain the `imageContentSources` section from the output of the command to
 mirror the repository.
 * Obtain the contents of the certificate for your mirror registry.
-endif::restricted[]
+endif::restricted,restricted-upi[]
 
 .Procedure
 
@@ -133,14 +144,14 @@ it in the `<installation_directory>`.
 ====
 You must name this configuration file `install-config.yaml`.
 ====
-ifdef::restricted[]
+ifdef::restricted,restricted-upi[]
 ** Unless you use a registry that {op-system} trusts by default, such as
 `docker.io`, you must provide the contents of the certificate for your mirror
 repository in the `additionalTrustBundle` section. In most cases, you must
 provide the certificate for your mirror.
 ** You must include the `imageContentSources` section from the output of the command to
 mirror the repository.
-endif::restricted[]
+endif::restricted,restricted-upi[]
 +
 
 ifndef::aws-china,aws-gov,aws-secret,azure-gov,ash,ash-default,ash-network,gcp-shared,ibm-cloud-private,ibm-power-vs-private[]
@@ -197,9 +208,9 @@ Make the following modifications:
 For more information about the parameters, see "Installation configuration parameters".
 endif::ash-default,ash-network[]
 
-ifdef::three-node-cluster[]
+ifdef::vsphere-upi-vsphere[]
 . If you are installing a three-node cluster, modify the `install-config.yaml` file by setting the `compute.replicas` parameter to `0`. This ensures that the cluster's control planes are schedulable. For more information, see "Installing a three-node cluster on {platform}".
-endif::three-node-cluster[]
+endif::vsphere-upi-vsphere[]
 
 . Back up the `install-config.yaml` file so that you can use it to install
 multiple clusters.
@@ -256,6 +267,9 @@ ifeval::["{context}" == "installing-ibm-power-vs-private-cluster"]
 :!ibm-power-vs-private:
 endif::[]
 ifeval::["{context}" == "installing-vsphere"]
-:!three-node-cluster:
+:vsphere-upi-vsphere:
+endif::[]
+ifeval::["{context}" == "installing-vsphere-network-customizations"]
+:vsphere-upi:
 endif::[]
 :!platform:

modules/installation-vsphere-config-yaml.adoc

@@ -165,6 +165,11 @@ If you must specify VMs across multiple datastores, use a `datastore` object to
 <11> Optional: For installer-provisioned infrastructure, the absolute path of an existing folder where the installation program creates the virtual machines, for example, `/<datacenter_name>/vm/<folder_name>/<subfolder_name>`. If you do not provide this value, the installation program creates a top-level folder in the datacenter virtual machine folder that is named with the infrastructure ID. If you are providing the infrastructure for the cluster and you do not want to use the default `StorageClass` object, named `thin`, you can omit the `folder` parameter from the `install-config.yaml` file.
 <12> The password associated with the vSphere user.
 <13> The fully-qualified hostname or IP address of the vCenter server.
++
+[IMPORTANT]
+====
+The Cluster Cloud Controller Manager Operator performs a connectivity check on a provided hostname or IP address. Ensure that you specify a hostname or an IP address to a reachable vCenter server. If you provide metadata to a non-existent vCenter server, installation of the cluster fails at the bootstrap stage.
+====
 <14> The vSphere disk provisioning method.
 ifndef::openshift-origin[]
 <15> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead.