diff --git a/_topic_map.yml b/_topic_map.yml index 85ae0f0a3417..cecac2aac72a 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -244,11 +244,17 @@ Topics: Dir: installing_vsphere Topics: - Name: Installing a cluster on vSphere + File: installing-vsphere-installer-provisioned + - Name: Installing a cluster on vSphere with customizations + File: installing-vsphere-installer-provisioned-customizations + - Name: Installing a cluster on vSphere with user-provisioned infrastructure File: installing-vsphere - - Name: Installing a cluster on vSphere with network customizations + - Name: Installing a cluster on vSphere with user-provisioned infrastructure and network customizations File: installing-vsphere-network-customizations - - Name: Restricted network vSphere installation + - Name: Restricted network vSphere installation with user-provisioned infrastructure File: installing-restricted-networks-vsphere + - Name: Uninstalling a cluster on vSphere that uses installer-provisioned infrastructure + File: uninstalling-cluster-vsphere-installer-provisioned - Name: Troubleshooting installation issues File: installing-troubleshooting - Name: Support for FIPS cryptography diff --git a/installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc b/installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc new file mode 100644 index 000000000000..912ffda84826 --- /dev/null +++ b/installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc @@ -0,0 +1,67 @@ +[id="installing-vsphere-installer-provisioned-customizations"] += Installing a cluster on vSphere with customizations +include::modules/common-attributes.adoc[] +:context: installing-vsphere-installer-provisioned-customizations + +toc::[] + +In {product-title} version {product-version}, you can install a cluster on your +VMware vSphere instance by using installer-provisioned infrastructure. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster. + +.Prerequisites + +* Provision +xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] +for your cluster. To deploy a private image registry, your storage must provide +ReadWriteMany access modes. +* Review details about the +xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] +processes. +* If you use a firewall, you must +xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. ++ +[NOTE] +==== +Be sure to also review this site list if you are configuring a proxy. +==== + +include::modules/cluster-entitlements.adoc[leveloffset=+1] + +include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] + +include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1] + +include::modules/ssh-agent-using.adoc[leveloffset=+1] + +include::modules/installation-obtaining-installer.adoc[leveloffset=+1] + +include::modules/installation-adding-vcenter-root-certificates.adoc[leveloffset=+1] + +include::modules/installation-initializing.adoc[leveloffset=+1] + +include::modules/installation-configuration-parameters.adoc[leveloffset=+2] + +include::modules/installation-installer-provisioned-vsphere-config-yaml.adoc[leveloffset=+2] + +include::modules/installation-launching-installer.adoc[leveloffset=+1] + +include::modules/cli-installing-cli.adoc[leveloffset=+1] + +include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] + +[id="installing-vsphere-installer-provisioned-customizations-registry"] +== Creating registry storage +After you install the cluster, you must create storage for the registry Operator. + +include::modules/registry-removed.adoc[leveloffset=+2] + +include::modules/installation-registry-storage-config.adoc[leveloffset=+2] + +include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] + +.Next steps + +* xref:../../installing/install_config/customizations.adoc#customizations[Customize your cluster]. +* If necessary, you can +xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. +* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. diff --git a/installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc b/installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc new file mode 100644 index 000000000000..52a941268556 --- /dev/null +++ b/installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc @@ -0,0 +1,62 @@ +[id="installing-vsphere-installer-provisioned"] += Installing a cluster on vSphere +include::modules/common-attributes.adoc[] +:context: installing-vsphere-installer-provisioned + +toc::[] + +In {product-title} version {product-version}, you can install a cluster on your +VMware vSphere instance by using installer-provisioned infrastructure. + +.Prerequisites + +* Provision +xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] +for your cluster. To deploy a private image registry, your storage must provide +ReadWriteMany access modes. +* Review details about the +xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] +processes. +* If you use a firewall, you must +xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. ++ +[NOTE] +==== +Be sure to also review this site list if you are configuring a proxy. +==== + +include::modules/cluster-entitlements.adoc[leveloffset=+1] + +include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] + +include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1] + +include::modules/ssh-agent-using.adoc[leveloffset=+1] + +include::modules/installation-obtaining-installer.adoc[leveloffset=+1] + +include::modules/installation-adding-vcenter-root-certificates.adoc[leveloffset=+1] + +include::modules/installation-launching-installer.adoc[leveloffset=+1] + +include::modules/cli-installing-cli.adoc[leveloffset=+1] + +include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] + +[id="installing-vsphere-installer-provisioned-registry"] +== Creating registry storage +After you install the cluster, you must create storage for the registry Operator. + +include::modules/registry-removed.adoc[leveloffset=+2] + +include::modules/installation-registry-storage-config.adoc[leveloffset=+2] + +include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] + + +.Next steps + +* xref:../../installing/install_config/customizations.adoc#customizations[Customize your cluster]. +* If necessary, you can +xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. +* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. diff --git a/installing/installing_vsphere/uninstalling-cluster-vsphere-installer-provisioned.adoc b/installing/installing_vsphere/uninstalling-cluster-vsphere-installer-provisioned.adoc new file mode 100644 index 000000000000..c91d87acdc00 --- /dev/null +++ b/installing/installing_vsphere/uninstalling-cluster-vsphere-installer-provisioned.adoc @@ -0,0 +1,10 @@ +[id="uninstalling-cluster-vsphere-installer-provisioned"] += Uninstalling a cluster on vSphere that uses installer-provisioned infrastructure +include::modules/common-attributes.adoc[] +:context: uninstalling-cluster-vsphere-installer-provisioned + +toc::[] + +You can remove a cluster that you deployed in your VMware vSphere instance by using installer-provisioned infrastructure. + +include::modules/installation-uninstall-clouds.adoc[leveloffset=+1] diff --git a/modules/cli-installing-cli.adoc b/modules/cli-installing-cli.adoc index 2daa9a87282c..7992ea44f2a2 100644 --- a/modules/cli-installing-cli.adoc +++ b/modules/cli-installing-cli.adoc @@ -20,6 +20,8 @@ // * installing/installing_gcp/installing-gcp-user-infra.adoc // * installing/install_config/installing-restricted-networks-preparations.adoc // * installing/installing_vsphere/installing-vsphere.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc // * installing/installing_ibm_z/installing-ibm-z.adoc // * openshift_images/samples-operator-alt-registry.adoc // * installing/installing_rhv/installing-rhv-customizations.adoc diff --git a/modules/cli-logging-in-kubeadmin.adoc b/modules/cli-logging-in-kubeadmin.adoc index 8374f2163b52..82321e8a3abf 100644 --- a/modules/cli-logging-in-kubeadmin.adoc +++ b/modules/cli-logging-in-kubeadmin.adoc @@ -26,6 +26,8 @@ // * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc // * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc // * installing/installing_vsphere/installing-vsphere.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc // * installing/installing_ibm_z/installing-ibm-z.adoc // * installing/installing_rhv/installing-rhv-customizations.adoc // * installing/installing_rhv/installing-rhv-default.adoc diff --git a/modules/cluster-entitlements.adoc b/modules/cluster-entitlements.adoc index 2122577a41f4..3b98c6265889 100644 --- a/modules/cluster-entitlements.adoc +++ b/modules/cluster-entitlements.adoc @@ -24,6 +24,8 @@ // * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc // * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc // * installing/installing_vsphere/installing-vsphere.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc // * installing/installing_ibm_z/installing-ibm-z.adoc ifeval::["{context}" == "installing-restricted-networks-bare-metal"] diff --git a/modules/installation-adding-vcenter-root-certificates.adoc b/modules/installation-adding-vcenter-root-certificates.adoc new file mode 100644 index 000000000000..ada03a64c88f --- /dev/null +++ b/modules/installation-adding-vcenter-root-certificates.adoc @@ -0,0 +1,51 @@ +// Module included in the following assemblies: +// +// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc + +[id="installation-adding-vcenter-root-certificates_{context}"] += Adding vCenter root CA certificates to your system trust + +Because the installation program requires access to your vCenter's API, you must add your vCenter's trusted root CA certificates to your system trust before you install an {product-title} cluster. + +.Procedure + +. From the vCenter home page, download the vCenter's root CA certificates. Click *Download trusted root CA certificates* in the vSphere Web Services SDK section. The `/certs/download.zip` file downloads. + +. Extract the compressed file that contains the vCenter root CA certificates. The contents of the compressed file resemble the following file structure: ++ +---- +certs +├── lin +│ ├── 108f4d17.0 +│ ├── 108f4d17.r1 +│ ├── 7e757f6a.0 +│ ├── 8e4f8471.0 +│ └── 8e4f8471.r0 +├── mac +│ ├── 108f4d17.0 +│ ├── 108f4d17.r1 +│ ├── 7e757f6a.0 +│ ├── 8e4f8471.0 +│ └── 8e4f8471.r0 +└── win + ├── 108f4d17.0.crt + ├── 108f4d17.r1.crl + ├── 7e757f6a.0.crt + ├── 8e4f8471.0.crt + └── 8e4f8471.r0.crl + +3 directories, 15 files +---- + +. Add the files for your operating system to the system trust. For example, on a Fedora operating system, run the following command: ++ +---- +# cp certs/lin/* /etc/pki/ca-trust/source/anchors +---- + +. Update your system trust. For example, on a Fedora operating system, run the following command: ++ +---- +# update-ca-trust extract +---- diff --git a/modules/installation-configuration-parameters.adoc b/modules/installation-configuration-parameters.adoc index 51216cbacf37..45eb5f06b618 100644 --- a/modules/installation-configuration-parameters.adoc +++ b/modules/installation-configuration-parameters.adoc @@ -17,6 +17,7 @@ // * installing/installing_openstack/installing-openstack-user.adoc // * installing/installing_openstack/installing-openstack-user-kuryr.adoc // * installing/installing_rhv/installing-rhv-custom.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc ifeval::["{context}" == "installing-aws-customizations"] :aws: @@ -70,6 +71,9 @@ ifeval::["{context}" == "installing-openstack-user-kuryr"] :osp: :osp-kuryr: endif::[] +ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] +:vsphere: +endif::[] [id="installation-configuration-parameters_{context}"] @@ -103,16 +107,16 @@ uses the `.` format. |`controlPlane.platform` |The cloud provider to host the control plane machines. This parameter value must match the `compute.platform` parameter value. -|`aws`, `azure`, `gcp`, `openstack`, or `{}` +|`aws`, `azure`, `gcp`, `openstack`, `vsphere`, or `{}` |`compute.platform` |The cloud provider to host the worker machines. This parameter value must match the `controlPlane.platform` parameter value. -|`aws`, `azure`, `gcp`, `openstack`, or `{}` +|`aws`, `azure`, `gcp`, `openstack`, `vsphere`, or `{}` |`metadata.name` |The name of your cluster. -|A string that contains uppercase or lowercase letters, such as `dev`. +|A string that contains lowercase letters, hyphens (-), or periods (.), such as `dev`. ifdef::osp[] The string must be 14 characters or fewer long. endif::osp[] @@ -120,7 +124,7 @@ endif::osp[] |`platform..region` |The region to deploy your cluster in. |A valid region for your cloud, such as `us-east-1` for AWS, `centralus` -for Azure. {rh-openstack-first} does not use this parameter. +for Azure. {rh-openstack-first} and vSphere do not use this parameter. |`pullSecret` |The pull secret that you obtained from the @@ -332,7 +336,7 @@ ifdef::osp[] |A list of IP addresses as strings. For example, `["8.8.8.8", "192.168.1.12"]`. |`platform.openstack.defaultMachinePlatform` -|The default machine pool platform configuration. +| _Optional_. The default machine pool platform configuration. | [source,json] ---- @@ -344,6 +348,7 @@ ifdef::osp[] } } ---- +|==== |`platform.openstack.machinesSubnet` |The UUID of a {rh-openstack} subnet that the cluster's nodes use. Nodes and VIP ports are created on this subnet. @@ -354,9 +359,6 @@ If you deploy to a custom subnet, you cannot specify an external DNS server to t |A UUID as a string, for example `fa806b2f-ac49-4bce-b9db-124bc64209bf`. -|==== - - endif::osp[] ifdef::azure[] @@ -449,6 +451,80 @@ link:https://yaml.org/spec/1.2/spec.html#sequence//[YAML sequence]. endif::gcp[] +ifdef::vsphere[] +.Additional VMware vSphere cluster parameters +[cols=".^2,.^3a,.^3a",options="header"] +|==== +|Parameter|Description|Values + +|`platform.vsphere.vCenter` +|The fully-qualified host name or IP address of the vCenter server. +|String + +|`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://vmware.github.io/vsphere-storage-for-kubernetes/documentation/vcp-roles.html[static or dynamic persistent volume provisioning] +in vSphere. +|String. + +|`platform.vsphere.password` +|The password for the vCenter user name. +|String. + +|`platform.vsphere.datacenter` +|The name of the datacenter to use in the vCenter instance. +|String. + +|`platform.vsphere.defaultDatastore` +|The name of the default datastore to use for provisioning volumes. +|String. + +|`platform.vsphere.folder` +|_Optional_. The absolute path of an existing folder where the installation program creates the virtual machines. create VMs. If you do not provide this value, the installation program creates a folder that is named with the cluster ID is created in the datacenter virtual machine folder. +|String, for example, `//vm//`. + +|`platform.vsphere.network` +|The network in the vCenter instance that contains the virtual IP addresses and DNS records that you configured. +|String. + +|`platform.vsphere.cluster` +|The vCenter cluster to install the {product-title} cluster in. +|String. + +|`platform.vsphere.apiVIP` +|The virtual IP address that you configured for control plane API access. +|An IP address, for example `128.0.0.1`. + +|`platform.vsphere.ingressVIP` +|The virtual IP address that you configured for cluster ingress. +|An IP address, for example `128.0.0.1`. +|==== + +.Optional VMware vSphere machine pool parameters +[cols=".^2,.^3a,.^3a",options="header"] +|==== +|Parameter|Description|Values + +|`platform.vsphere.osDisk.diskSizeGB` +|The size of the disk in gigabytes. +|Integer. + +|`platform.vsphere.cpus` +|The total number of virtual processor cores to assign a virtual machine. +|Integer. + +|`platform.vsphere.coresPerSocket` +|The number of cores per socket in a virtual machine. The number of vCPUs on the virtual machine is will be `platform.vsphere.cpus`/`platform.vsphere.coresPerSocket`. The default value is `1` +|Integer. + +|`platform.vsphere.memoryMB` +|The size of a virtual machine's memory in megabytes.. +|Integer. +|==== + +endif::vsphere[] + ifeval::["{context}" == "installing-aws-customizations"] :!aws: endif::[] @@ -501,3 +577,6 @@ ifeval::["{context}" == "installing-openstack-user-kuryr"] :!osp: :!osp-kuryr: endif::[] +ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] +:!vsphere: +endif::[] diff --git a/modules/installation-initializing.adoc b/modules/installation-initializing.adoc index cba063a3a96e..994b20f70e10 100644 --- a/modules/installation-initializing.adoc +++ b/modules/installation-initializing.adoc @@ -20,6 +20,7 @@ // * installing/installing_openstack/installing-openstack-installer-user.adoc // * installing/installing_rhv/installing-rhv-customizations.adoc // * installing/installing_rhv/installing-rhv-default.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc // Consider also adding the installation-configuration-parameters.adoc module. //YOU MUST SET AN IFEVAL FOR EACH NEW MODULE @@ -79,6 +80,9 @@ endif::[] ifeval::["{context}" == "installing-rhv-default"] :rhv: endif::[] +ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] +:vsphere: +endif::[] [id="installation-initializing_{context}"] = Creating the installation configuration file @@ -99,6 +103,9 @@ endif::osp[] ifdef::rhv[] {rh-virtualization-first}. endif::rhv[] +ifdef::vsphere[] +VMware vSphere. +endif::vsphere[] .Prerequisites @@ -187,9 +194,26 @@ and compute nodes. ... Select the base domain to deploy the cluster to. All DNS records will be sub-domains of this base and will also include the cluster name. endif::osp[] +ifdef::vsphere[] +... Select *vsphere* as the platform to target. +... Specify the name of your vCenter instance. +... Specify the user name and password for the vCenter account that has the required permissions to create the cluster. ++ +The installation program connects to your vCenter instance. +... Select the datacenter in your vCenter instance to connect to. +... Select the default vCenter datastore to use. +... Select the vCenter cluster to install the {product-title} cluster in. +... Select the network in the vCenter instance that contains the virtual IP addresses and DNS records that you configured. +... Enter the virtual IP address that you configured for control plane API access. +... Enter the virtual IP address that you configured for cluster ingress. +... Enter the base domain. This base domain must be the same one that you used in the DNS records that you configured. +endif::vsphere[] ifndef::osp[] ifndef::rhv[] ... Enter a descriptive name for your cluster. +ifdef::vsphere[] +The cluster name must be the same one that you used in the DNS records that you configured. +endif::vsphere[] endif::rhv[] endif::osp[] ifdef::osp[] @@ -347,3 +371,6 @@ endif::[] ifeval::["{context}" == "installing-rhv-default"] :!rhv: endif::[] +ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] +:!vsphere: +endif::[] diff --git a/modules/installation-installer-provisioned-vsphere-config-yaml.adoc b/modules/installation-installer-provisioned-vsphere-config-yaml.adoc new file mode 100644 index 000000000000..987ab31ccd01 --- /dev/null +++ b/modules/installation-installer-provisioned-vsphere-config-yaml.adoc @@ -0,0 +1,80 @@ +// Module included in the following assemblies: +// +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc + +[id="installation-installer-provisioned-vsphere-config-yaml_{context}"] += Sample `install-config.yaml` file for an installer-provisioned VMware vSphere cluster + +You can customize the `install-config.yaml` file to specify more details about +your {product-title} cluster's platform or modify the values of the required +parameters. + +[source,yaml] +---- +apiVersion: v1 +baseDomain: example.com <1> +compute: <2> +- hyperthreading: Enabled <3> + name: worker + replicas: 3 + platform: + vsphere: <4> + cpus: 2 + coresPerSocket: 2 + memoryMB: 8196 + osDisk: + diskSizeGB: 120 +controlPlane: <2> + hyperthreading: Enabled <3> + name: master + replicas: 3 + platform: + vsphere: <4> + cpus: 4 + coresPerSocket: 2 + memoryMB: 16384 + osDisk: + diskSizeGB: 120 +metadata: + name: cluster <5> +platform: + vsphere: + vcenter: your.vcenter.server + username: username + password: password + datacenter: datacenter + defaultDatastore: datastore + folder: folder + network: VM_Network + cluster: vsphere_cluster_name + apiVIP: api_vip + ingressVIP: ingress_vip +fips: false +pullSecret: '{"auths":{"": {"auth": "","email": "you@example.com"}}}' +sshKey: 'ssh-ed25519 AAAA...' +---- +<1> The base domain of the cluster. All DNS records must be sub-domains of this +base and include the cluster name. +<2> The `controlPlane` section is a single mapping, but the compute section is a +sequence of mappings. To meet the requirements of the different data structures, +the first line of the `compute` section must begin with a hyphen, `-`, and the +first line of the `controlPlane` section must not. Although both sections +currently define a single machine pool, it is possible that future versions +of {product-title} will support defining multiple compute pools during +installation. Only one control plane pool is used. +<3> Whether to enable or disable simultaneous multithreading, or +`hyperthreading`. By default, simultaneous multithreading is enabled +to increase the performance of your machines' cores. You can disable it by +setting the parameter value to `Disabled`. If you disable simultaneous +multithreading in some cluster machines, you must disable it in all cluster +machines. ++ +[IMPORTANT] +==== +If you disable simultaneous multithreading, ensure that your capacity planning +accounts for the dramatically decreased machine performance. +Your machines must use at least 8 CPUs and 32 GB of RAM if you disable +simultaneous multithreading. +==== +<4> Optional: Provide additional configuration for the machine pool parameters for the compute and control plane machines. +<5> The cluster name that you specified in your DNS records. diff --git a/modules/installation-launching-installer.adoc b/modules/installation-launching-installer.adoc index 87e4114df632..0a4dc1b69d54 100644 --- a/modules/installation-launching-installer.adoc +++ b/modules/installation-launching-installer.adoc @@ -18,6 +18,8 @@ // * installing/installing_openstack/installing-openstack-installer.adoc // * installing/installing_rhv/installing-rhv-customizations.adoc // * installing/installing_rhv/installing-rhv-default.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc // If you use this module in any other assembly, you must update the ifeval // statements. @@ -84,6 +86,14 @@ ifeval::["{context}" == "installing-rhv-default"] :no-config: :rhv: endif::[] +ifeval::["{context}" == "installing-vsphere-installer-provisioned"] +:no-config: +:vsphere: +endif::[] +ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] +:custom-config: +:vsphere: +endif::[] [id="installation-launching-installer_{context}"] = Deploying the cluster @@ -97,7 +107,7 @@ You can run the `create cluster` command of the installation program only once, .Prerequisites -ifndef::osp,rhv[* Configure an account with the cloud platform that hosts your cluster.] +ifndef::osp,rhv,vsphere[* Configure an account with the cloud platform that hosts your cluster.] * Obtain the {product-title} installation program and the pull secret for your cluster. @@ -212,7 +222,24 @@ and compute nodes. .. Select the base domain to deploy the cluster to. All DNS records will be sub-domains of this base and will also include the cluster name. endif::osp[] +ifdef::vsphere[] +.. Select *vsphere* as the platform to target. +.. Specify the name of your vCenter instance. +.. Specify the user name and password for the vCenter account that has the required permissions to create the cluster. ++ +The installation program connects to your vCenter instance. +.. Select the datacenter in your vCenter instance to connect to. +.. Select the default vCenter datastore to use. +.. Select the vCenter cluster to install the {product-title} cluster in. +.. Select the network in the vCenter instance that contains the virtual IP addresses and DNS records that you configured. +.. Enter the virtual IP address that you configured for control plane API access. +.. Enter the virtual IP address that you configured for cluster ingress. +.. Enter the base domain. This base domain must be the same one that you used in the DNS records that you configured. +endif::vsphere[] .. Enter a descriptive name for your cluster. +ifdef::vsphere[] +The cluster name must be the same one that you used in the DNS records that you configured. +endif::vsphere[] ifdef::azure[] + [IMPORTANT] @@ -385,3 +412,11 @@ ifeval::["{context}" == "installing-rhv-default"] :!no-config: :!rhv: endif::[] +ifeval::["{context}" == "installing-vsphere-installer-provisioned"] +:!no-config: +:!vsphere: +endif::[] +ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] +:!custom-config: +:!vsphere: +endif::[] diff --git a/modules/installation-obtaining-installer.adoc b/modules/installation-obtaining-installer.adoc index 7a814a8804cd..1c1a95a71135 100644 --- a/modules/installation-obtaining-installer.adoc +++ b/modules/installation-obtaining-installer.adoc @@ -20,6 +20,8 @@ // * installing/installing_openstack/installing-openstack-installer-kuryr.adoc // * installing/installing_openstack/installing-openstack-installer.adoc // * installing/installing_vsphere/installing-vsphere.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc // * installing/installing_ibm_z/installing-ibm-z.adoc // * installing/installing_rhv/installing-rhv-default.adoc // * installing/installing_rhv/installing-rhv-customizations.adoc diff --git a/modules/installation-uninstall-clouds.adoc b/modules/installation-uninstall-clouds.adoc index 6b0b8f64e262..50b8f124beaa 100644 --- a/modules/installation-uninstall-clouds.adoc +++ b/modules/installation-uninstall-clouds.adoc @@ -5,6 +5,7 @@ // * installing/installing_gcp/uninstalling-cluster-gcp.adoc // * installing/installing_osp/uninstalling-cluster-openstack.adoc // * installing/installing_rhv/uninstalling-cluster-rhv.adoc +// * installing/installing_vsphere/uninstalling-cluster-vsphere-installer-provisioned.adoc [id="installation-uninstall-clouds_{context}"] = Removing a cluster that uses installer-provisioned infrastructure diff --git a/modules/installation-user-infra-generate-k8s-manifest-ignition.adoc b/modules/installation-user-infra-generate-k8s-manifest-ignition.adoc index b54d333f6b08..e514f6cb319e 100644 --- a/modules/installation-user-infra-generate-k8s-manifest-ignition.adoc +++ b/modules/installation-user-infra-generate-k8s-manifest-ignition.adoc @@ -46,6 +46,12 @@ endif::[] ifeval::["{context}" == "installing-openstack-user-kuryr"] :osp: endif::[] +ifeval::["{context}" == "installing-vsphere"] +:vsphere: +endif::[] +ifeval::["{context}" == "installing-restricted-networks-vsphere"] +:vsphere: +endif::[] [id="installation-user-infra-generate-k8s-manifest-ignition_{context}"] = Creating the Kubernetes manifest and Ignition config files @@ -111,7 +117,7 @@ Because you create and manage the worker machines yourself, you do not need to initialize these machines. endif::aws,azure,gcp[] -ifdef::osp[] +ifdef::osp,vsphere[] . Remove the Kubernetes manifest files that define the control plane machines and compute machineSets: + ---- @@ -122,7 +128,7 @@ Because you create and manage these resources yourself, you do not have to initialize them. + * You can preserve the MachineSet files to create compute machines by using the machine API, but you must update references to them to match your environment. -endif::osp[] +endif::osp,vsphere[] ifdef::baremetal,baremetal-restricted[] [WARNING] @@ -246,3 +252,9 @@ endif::[] ifeval::["{context}" == "installing-openstack-user-kuryr"] :!osp: endif::[] +ifeval::["{context}" == "installing-vsphere"] +:!vsphere: +endif::[] +ifeval::["{context}" == "installing-restricted-networks-vsphere"] +:!vsphere: +endif::[] diff --git a/modules/installation-vsphere-config-yaml.adoc b/modules/installation-vsphere-config-yaml.adoc index 865825667063..78474c0bf984 100644 --- a/modules/installation-vsphere-config-yaml.adoc +++ b/modules/installation-vsphere-config-yaml.adoc @@ -2,6 +2,7 @@ // // * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc // * installing/installing_vsphere/installing-vsphere.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc ifeval::["{context}" == "installing-restricted-networks-vsphere"] :restricted: diff --git a/modules/installation-vsphere-infrastructure.adoc b/modules/installation-vsphere-infrastructure.adoc index dbf1b4451957..2a2384713598 100644 --- a/modules/installation-vsphere-infrastructure.adoc +++ b/modules/installation-vsphere-infrastructure.adoc @@ -2,6 +2,8 @@ // // * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc // * installing/installing_vsphere/installing-vsphere.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc [id="installation-vsphere-infrastructure_{context}"] = VMware vSphere infrastructure requirements @@ -40,5 +42,5 @@ You must ensure that the time on your ESXi hosts is synchronized before you inst [IMPORTANT] ==== - A limitation of using VPC is that the Storage Distributed Resource Scheduler (SDRS) is not supported. See link:https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/faqs.html[vSphere Storage for Kubernetes FAQs] in the VMware documentation. + A limitation of using VPC is that the Storage Distributed Resource Scheduler (SDRS) is not supported. See link:https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/faqs.html[vSphere Storage for Kubernetes FAQs] in the VMware documentation. ==== diff --git a/modules/installation-vsphere-installer-infra-requirements.adoc b/modules/installation-vsphere-installer-infra-requirements.adoc new file mode 100644 index 000000000000..ed33fabcf7b9 --- /dev/null +++ b/modules/installation-vsphere-installer-infra-requirements.adoc @@ -0,0 +1,109 @@ +// Module included in the following assemblies: +// +// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc + +[id="installation-vsphere-installer-infra-requirements_{context}"] += vCenter requirements + +Before you install an {product-title} cluster on your vCenter that uses infrastructure that the installer provisions, you must prepare your environment. + +[discrete] +[id="installation-vsphere-installer-infra-requirements-account_{context}"] +== Required vCenter account privileges + +To install an {product-title} cluster in a vCenter, the installation program requires access to an account with privileges to read and create the required resources. Using an account that has administrative privileges is the simplest way to access all of the necessary permissions. + +A user requires the following privileges to install an {product-title} cluster: + +* Datastore +** *Allocate space* +* Folder +** *Create folder* +** *Delete folder* +* vSphere Tagging +** All privileges +* Network +** *Assign network* +* Resource +** *Assign virtual machine to resource pool* +* Profile-driven storage +** All privileges +* vApp +** All privileges +* Virtual machine +** All privileges + +For more information about creating an account with only the required privileges, see link: https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.security.doc/GUID-5372F580-5C23-4E9C-8A4E-EF1B4DD9033E.html[vSphere Permissions and User Management Tasks] in the vSphere documentation. + +[discrete] +[id="installation-vsphere-installer-infra-requirements-resources_{context}"] +== Cluster resources + +When you deploy an {product-title} cluster that uses installer-provisioned infrastructure, the installation program must be able to create several resources in your vCenter instance. + +A standard {product-title} installation creates the following vCenter resources: + +* 1 Folder +* 1 Tag category +* 1 Tag +* Virtual machines: +** 1 template +** 1 temporary bootstrap node +** 3 control plane nodes +** 3 compute machines + +Although these resources use 856 GB of storage, the bootstrap node is destroyed during the cluster installation process. A minimum of 800 GB of storage is required to use a standard cluster. + +If you deploy more compute machines, the {product-title} cluster will use more storage. + +[discrete] +[id="installation-vsphere-installer-infra-requirements-limits_{context}"] +== Cluster limits + +Available resources vary between clusters. The number of possible clusters within a vCenter is limited primarily by available storage space and any limitations on the number of required resources. Be sure to consider both limitations to the vCenter resources that the cluster creates and the resources that you require to deploy a cluster, such as IP addresses and networks. + +[discrete] +[id="installation-vsphere-installer-infra-requirements-networking_{context}"] +== Networking requirements + +In addition to using DHCP for the network, you must create the following networking resources before you install the {product-title} cluster: + +[discrete] +[id="installation-vsphere-installer-infra-requirements-_{context}"] +=== Required IP Addresses + +An installer-provisioned vSphere installation requires two static IP addresses: + +* The **API** address is used to access the cluster API. +* The **Ingress** address is used for cluster ingress traffic. + +You must provide these IP addresses to the installation program when you install the {product-title} cluster. + +[discrete] +[id="installation-vsphere-installer-infra-requirements-dns-records_{context}"] +=== DNS records + +You must create DNS records for two static IP addresses in the appropriate DNS server for the vCenter instance that hosts your {product-title} cluster. In each record, `` is the cluster name and `` is the cluster base domain that you specify when you install the cluster. A complete DNS record takes the form: `...`. + +.Required DNS records +[cols="1a,5a,3a",options="header"] +|=== + +|Component +|Record +|Description + +|API VIP +|`api...` +|This DNS A/AAAA or CNAME record must point to the load balancer +for the control plane machines. This record must be resolvable by both clients +external to the cluster and from all the nodes within the cluster. + +|Ingress VIP +|`*.apps...` +|A wildcard DNS A/AAAA or CNAME record that points to the load balancer that targets the +machines that run the Ingress router pods, which are the worker nodes by +default. This record must be resolvable by both clients external to the cluster +and from all the nodes within the cluster. +|=== diff --git a/modules/nw-modifying-operator-install-config.adoc b/modules/nw-modifying-operator-install-config.adoc index d44be18e6859..0506e9aee204 100644 --- a/modules/nw-modifying-operator-install-config.adoc +++ b/modules/nw-modifying-operator-install-config.adoc @@ -11,6 +11,7 @@ ifeval::["{context}" == "installing-bare-metal-network-customizations"] endif::[] ifeval::["{context}" == "installing-vsphere-network-customizations"] :ignition-config: +:vsphere: endif::[] [id="modifying-nwoperator-config-startup_{context}"] @@ -75,10 +76,10 @@ kind: Network metadata: name: cluster spec: <1> - clusterNetwork: + clusterNetwork: - cidr: 10.128.0.0/14 hostPrefix: 23 - serviceNetwork: + serviceNetwork: - 172.30.0.0/16 defaultNetwork: type: OpenShiftSDN @@ -98,9 +99,23 @@ specify only the parameters that you want to change. installation program deletes the `manifests/` directory when creating the cluster. +ifdef::vsphere[] +. Remove the Kubernetes manifest files that define the control plane machines and compute machineSets: ++ +---- +$ rm -f openshift/99_openshift-cluster-api_master-machines-*.yaml openshift/99_openshift-cluster-api_worker-machineset-*.yaml +---- ++ +Because you create and manage these resources yourself, you do not have +to initialize them. ++ +* You can preserve the MachineSet files to create compute machines by using the machine API, but you must update references to them to match your environment. +endif::vsphere[] + ifeval::["{context}" == "installing-bare-metal-network-customizations"] :!ignition-config: endif::[] ifeval::["{context}" == "installing-vsphere-network-customizations"] :!ignition-config: +:!vsphere: endif::[] diff --git a/modules/ssh-agent-using.adoc b/modules/ssh-agent-using.adoc index 06c8ada3a4e4..56628527ae4c 100644 --- a/modules/ssh-agent-using.adoc +++ b/modules/ssh-agent-using.adoc @@ -23,6 +23,8 @@ // * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc // * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc // * installing/installing_vsphere/installing-vsphere.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc // * installing/installing_ibm_z/installing-ibm-z.adoc ifeval::["{context}" == "installing-restricted-networks-vsphere"]