openshift-docs/modules/installation-initializing.adoc

// Module included in the following assemblies:
//
// * installing/installing_aws/installing-aws-customizations.adoc
// * installing/installing_aws/installing-aws-network-customizations.adoc
// * installing/installing_aws/installing-aws-vpc.adoc
// * installing/installing_aws/installing-restricted-networks-aws-installer-provisioned.adoc
// * installing/installing_azure/installing-azure-customizations.adoc
// * installing/installing_azure/installing-azure-network-customizations
// * installing/installing_azure/installing-azure-vnet.adoc
// * installing/installing_azure/installing-azure-user-infra.adoc
// * installing/installing_gcp/installing-gcp-customizations.adoc
// * installing/installing_gcp/installing-gcp-network-customizations.adoc
// * installing/installing_gcp/installing-gcp-vpc.adoc
// * installing/installing_gcp/installing-gcp-user-infra.adoc
// * installing/installing_gcp/installing-restricted-networks-gcp.adoc
// * installing/installing_gcp/installing-restricted-networks-gcp-installer-provisioned.adoc
// * installing/installing_openstack/installing-openstack-installer-custom.adoc
// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc
// * installing/installing_openstack/installing-openstack-installer-restricted.adoc
// * installing/installing_openstack/installing-openstack-user-kuryr.adoc
// * installing/installing_openstack/installing-openstack-user.adoc
// * installing/installing_rhv/installing-rhv-customizations.adoc
// * installing/installing_vmc/installing-vmc-customizations.adoc
// * installing/installing_vmc/installing-vmc-network-customizations.adoc
// * installing/installing_vmc/installing-restricted-networks-vmc.adoc
// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc
// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc
// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc

// * installing/installing_gcp/installing-openstack-installer-restricted.adoc
// Consider also adding the installation-configuration-parameters.adoc module.
//YOU MUST SET AN IFEVAL FOR EACH NEW MODULE

ifeval::["{context}" == "installing-aws-customizations"]
:aws:
endif::[]
ifeval::["{context}" == "installing-aws-network-customizations"]
:aws:
endif::[]
ifeval::["{context}" == "installing-aws-vpc"]
:aws:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-aws-installer-provisioned"]
:aws:
:restricted:
endif::[]
ifeval::["{context}" == "installing-azure-customizations"]
:azure:
endif::[]
ifeval::["{context}" == "installing-azure-network-customizations"]
:azure:
endif::[]
ifeval::["{context}" == "installing-azure-vnet"]
:azure:
endif::[]
ifeval::["{context}" == "installing-azure-user-infra"]
:azure:
:azure-user-infra:
endif::[]
ifeval::["{context}" == "installing-gcp-customizations"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-vpc"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-network-customizations"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-user-infra"]
:gcp:
:gcp-user-infra:
endif::[]
ifeval::["{context}" == "installing-gcp-user-infra-vpc"]
:gcp:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-gcp"]
:gcp:
:restricted:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-gcp-installer-provisioned"]
:gcp:
:restricted:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-custom"]
:osp:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-kuryr"]
:osp:
endif::[]
ifeval::["{context}" == "installing-openstack-user"]
:osp:
:osp-user:
endif::[]
ifeval::["{context}" == "installing-openstack-user-kuryr"]
:osp:
:osp-user:
endif::[]
ifeval::["{context}" == "installing-openstack-user-sr-iov"]
:osp:
:osp-user:
endif::[]
ifeval::["{context}" == "installing-openstack-user-sr-iov-kuryr"]
:osp:
:osp-user:
endif::[]
ifeval::["{context}" == "installing-rhv-customizations"]
:rhv:
endif::[]
ifeval::["{context}" == "installing-rhv-default"]
:rhv:
endif::[]
ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"]
:vsphere:
endif::[]
ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"]
:vsphere:
endif::[]
ifeval::["{context}" == "installing-vmc-customizations"]
:vsphere:
endif::[]
ifeval::["{context}" == "installing-vmc-network-customizations"]
:vsphere:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-restricted"]
:osp:
:restricted:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"]
:vsphere:
:restricted:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-vmc"]
:vsphere:
:restricted:
endif::[]

[id="installation-initializing_{context}"]
= Creating the installation configuration file

You can customize the {product-title} cluster you install on
ifdef::aws[]
Amazon Web Services (AWS).
endif::aws[]
ifdef::azure[]
Microsoft Azure.
endif::azure[]
ifdef::gcp[]
Google Cloud Platform (GCP).
endif::gcp[]
ifdef::osp[]
{rh-openstack-first}.
endif::osp[]
ifdef::vsphere,vmc[]
VMware vSphere.
endif::vsphere,vmc[]
ifdef::rhv[]
{rh-virtualization-first}.
endif::rhv[]

.Prerequisites

* Obtain the {product-title} installation program and the pull secret for your cluster.
ifdef::restricted[]
For a restricted network installation, these files are on your mirror host.
* Have the `imageContentSources` values that were generated during mirror registry creation.
* Obtain the contents of the certificate for your mirror registry.
ifndef::aws,gcp[]
* Retrieve a {op-system-first} image and upload it to an accessible location.
endif::aws,gcp[]
endif::restricted[]
* Obtain service principal permissions at the subscription level.

.Procedure

. Create the `install-config.yaml` file.
+
.. Change to the directory that contains the installation program and run the following command:
+
[source,terminal]
----
$ ./openshift-install create install-config --dir <installation_directory> <1>
----
<1> For `<installation_directory>`, specify the directory name to store the
files that the installation program creates.
+
[IMPORTANT]
====
Specify an empty directory. Some installation assets, like bootstrap X.509
certificates have short expiration intervals, so you must not reuse an
installation directory. If you want to reuse individual files from another
cluster installation, you can copy them into your directory. However, the file
names for the installation assets might change between releases. Use caution
when copying installation files from an earlier {product-title} version.
====
ifndef::rhv[]
.. At the prompts, provide the configuration details for your cloud:
... Optional: Select an SSH key to use to access your cluster machines.
+
[NOTE]
====
For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses.
====
endif::rhv[]
ifdef::aws[]
... Select *AWS* as the platform to target.
... If you do not have an Amazon Web Services (AWS) profile stored on your computer, enter the AWS
access key ID and secret access key for the user that you configured to run the
installation program.
... Select the AWS region to deploy the cluster to.
... Select the base domain for the Route 53 service that you configured for your cluster.
endif::aws[]
ifdef::azure[]
... Select *azure* as the platform to target.
... If you do not have a Microsoft Azure profile stored on your computer, specify the
following Azure parameter values for your subscription and service principal:
**** *azure subscription id*: The subscription ID to use for the cluster.
Specify the `id` value in your account output.
**** *azure tenant id*: The tenant ID. Specify the `tenantId` value in your
account output.
**** *azure service principal client id*: The value of the `appId` parameter
for the service principal.
**** *azure service principal client secret*: The value of the `password`
parameter for the service principal.
... Select the region to deploy the cluster to.
... Select the base domain to deploy the cluster to. The base domain corresponds
to the Azure DNS Zone that you created for your cluster.
endif::azure[]
ifdef::gcp[]
... Select *gcp* as the platform to target.
... If you have not configured the service account key for your GCP account on
your computer, you must obtain it from GCP and paste the contents of the file
or enter the absolute path to the file.
... Select the project ID to provision the cluster in. The default value is
specified by the service account that you configured.
... Select the region to deploy the cluster to.
... Select the base domain to deploy the cluster to. The base domain corresponds
to the public DNS zone that you created for your cluster.
endif::gcp[]
ifdef::osp[]
... Select *openstack* as the platform to target.
... Specify the {rh-openstack-first} external network name to use for installing the cluster.
... Specify the floating IP address to use for external access to the OpenShift API.
... Specify a {rh-openstack} flavor with at least 16 GB RAM to use for control plane
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,vmc[]
... 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. The installation program uses the root resource pool of the vSphere cluster as the default resource pool.
... 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,vmc[]
ifndef::osp[]
ifndef::rhv[]
... Enter a descriptive name for your cluster.
ifdef::vsphere,vmc[]
The cluster name must be the same one that you used in the DNS records that you configured.
endif::vsphere,vmc[]
endif::rhv[]
endif::osp[]
ifdef::osp[]
... Enter a name for your cluster. The name must be 14 or fewer characters long.
endif::osp[]
ifdef::azure[]
+
[IMPORTANT]
====
All Azure resources that are available through public endpoints are subject to
resource name restrictions, and you cannot create resources that use certain
terms. For a list of terms that Azure restricts, see
link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-reserved-resource-name[Resolve reserved resource name errors]
in the Azure documentation.
====
endif::azure[]
ifdef::rhv[]
.. Respond to the installation program prompts.
... For `SSH Public Key`, select a password-less public key, such as `~/.ssh/id_rsa.pub`. This key authenticates connections with the new {product-title} cluster.
+
[NOTE]
====
For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, select an SSH key that your `ssh-agent` process uses.
====
... For `Platform`, select `ovirt`.
... For `Enter oVirt's API endpoint URL`, enter the URL of the {rh-virtualization} API using this format:
+
[source,terminal]
----
https://<engine-fqdn>/ovirt-engine/api <1>
----
<1> For `<engine-fqdn>`, specify the fully qualified domain name of the {rh-virtualization} environment.
+
For example:
+
ifndef::openshift-origin[]
[source,terminal]
----
$ curl -k -u ocpadmin@internal:pw123 \
https://rhv-env.virtlab.example.com/ovirt-engine/api
----
endif::openshift-origin[]
ifdef::openshift-origin[]
[source,terminal]
----
$ curl -k -u ocpadmin@internal:pw123 \
https://ovirtlab.example.com/ovirt-engine/api
----
endif::openshift-origin[]
+
... For `Is the oVirt CA trusted locally?`, enter `Yes`, because you have already set up a CA certificate. Otherwise, enter `No`.

... For `oVirt's CA bundle`, if you entered `Yes` for the preceding question, copy the certificate content from `/etc/pki/ca-trust/source/anchors/ca.pem` and paste it here. Then, press `Enter` twice. Otherwise, if you entered `No` for the preceding question, this question does not appear.
... For `oVirt engine username`, enter the user name and profile of the {rh-virtualization} administrator using this format:
+
[source,terminal]
----
<username>@<profile> <1>
----
<1> For `<username>`, specify the user name of an {rh-virtualization} administrator. For `<profile>`, specify the login profile, which you can get by going to the {rh-virtualization} Administration Portal login page and reviewing the *Profile* dropdown list. Together, the user name and profile should look similar to this example:
+
[source,terminal]
----
ocpadmin@internal
----
+
... For `oVirt engine password`, enter the {rh-virtualization} admin password.
... For `oVirt cluster`, select the cluster for installing {product-title}.
... For `oVirt storage domain`, select the storage domain for installing {product-title}.
... For `oVirt network`, select a virtual network that has access to the {rh-virtualization} {rh-virtualization-engine-name} REST API.
... For `Internal API Virtual IP`, enter the static IP address you set aside for the cluster's REST API.
... For `Ingress virtual IP`, enter the static IP address you reserved for the wildcard apps domain.
... For `Base Domain`, enter the base domain of the {product-title} cluster. If this cluster is exposed to the outside world, this must be a valid domain recognized by DNS infrastructure. For example, enter: `virtlab.example.com`
... For `Cluster Name`, enter the name of the cluster. For example, `my-cluster`. Use cluster name from the externally registered/resolvable DNS entries you created for the {product-title} REST API and apps domain names. The installation program also gives this name to the cluster in the {rh-virtualization} environment.
... For `Pull Secret`, copy the pull secret from the `pull-secret.txt` file you downloaded earlier and paste it here. You can also get a copy of the same pull secret from the link:https://console.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {console-redhat-com} site.
endif::rhv[]
ifndef::rhv[]
... Paste the pull secret that you obtained from the
link:https://console.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {console-redhat-com} site.
ifdef::openshift-origin[]
This field is optional.
endif::[]
endif::rhv[]
ifdef::gcp-user-infra,azure-user-infra[]
.. Optional: If you do not want the cluster to provision compute machines, empty
the compute pool by editing the resulting `install-config.yaml` file to set
`replicas` to `0` for the `compute` pool:
+
[source,yaml]
----
compute:
- hyperthreading: Enabled
  name: worker
  platform: {}
  replicas: 0 <1>
----
<1> Set to `0`.
endif::[]

ifndef::restricted[]
. Modify the `install-config.yaml` file. You can find more information about
the available parameters in the "Installation configuration parameters" section.

ifdef::rhv[]
+
[NOTE]
====
If you have any intermediate CA certificates on the {rh-virtualization-engine-name}, verify that the certificates appear in the `ovirt-config.yaml` file and the `install-config.yaml` file. If they do not appear, add them as follows:

. In the `~/.ovirt/ovirt-config.yaml` file:
+
[source,yaml]
----
[ovirt_ca_bundle]: |
     -----BEGIN CERTIFICATE-----
     <MY_TRUSTED_CA>
     -----END CERTIFICATE-----
     -----BEGIN CERTIFICATE-----
     <INTERMEDIATE_CA>
     -----END CERTIFICATE-----
----
. In the `install-config.yaml` file:
+
[source,yaml]
----
[additionalTrustBundle]: |
     -----BEGIN CERTIFICATE-----
     <MY_TRUSTED_CA>
     -----END CERTIFICATE-----
     -----BEGIN CERTIFICATE-----
     <INTERMEDIATE_CA>
     -----END CERTIFICATE-----
----
====
endif::rhv[]
endif::restricted[]

ifdef::osp+restricted[]
. In the `install-config.yaml` file, set the value of `platform.openstack.clusterOSImage` to the image location or name. For example:
+
[source,yaml]
----
platform:
  openstack:
      clusterOSImage: http://mirror.example.com/images/rhcos-43.81.201912131630.0-openstack.x86_64.qcow2.gz?sha256=ffebbd68e8a1f2a245ca19522c16c86f67f9ac8e4e0c1f0a812b068b16f7265d
----
endif::osp+restricted[]
ifdef::vsphere+restricted[]
. In the `install-config.yaml` file, set the value of `platform.vsphere.clusterOSImage` to the image location or name. For example:
+
[source,yaml]
----
platform:
  vsphere:
      clusterOSImage: http://mirror.example.com/images/rhcos-43.81.201912131630.0-vmware.x86_64.ova?sha256=ffebbd68e8a1f2a245ca19522c16c86f67f9ac8e4e0c1f0a812b068b16f7265d
----
endif::vsphere+restricted[]
ifdef::restricted[]
. Edit the `install-config.yaml` file to provide the additional information that
is required for an installation in a restricted network.
.. Update the `pullSecret` value to contain the authentication information for
your registry:
+
[source,yaml]
----
pullSecret: '{"auths":{"<mirror_host_name>:5000": {"auth": "<credentials>","email": "you@example.com"}}}'
----
+
For `<mirror_host_name>`, specify the registry domain name
that you specified in the certificate for your mirror registry, and for
`<credentials>`, specify the base64-encoded user name and password for
your mirror registry.
.. Add the `additionalTrustBundle` parameter and value.
+
[source,yaml]
----
additionalTrustBundle: |
  -----BEGIN CERTIFICATE-----
  ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
  -----END CERTIFICATE-----
----
+
The value must be the contents of the certificate file that you used for your mirror registry, which can be an existing, trusted certificate authority or the self-signed certificate that you generated for the mirror registry.

ifdef::aws+restricted[]
.. Define the subnets for the VPC to install the cluster in:
+
[source,yaml]
----
subnets:
- subnet-1
- subnet-2
- subnet-3
----
endif::aws+restricted[]
ifdef::gcp+restricted[]
.. Define the network and subnets for the VPC to install the cluster in under the parent `platform.gcp` field:
+
[source,yaml]
----
network: <existing_vpc>
controlPlaneSubnet: <control_plane_subnet>
computeSubnet: <compute_subnet>
----
+
For `platform.gcp.network`, specify the name for the existing Google VPC. For `platform.gcp.controlPlaneSubnet` and `platform.gcp.computeSubnet`, specify the existing subnets to deploy the control plane machines and compute machines, respectively.
endif::gcp+restricted[]

.. Add the image content resources, which look like this excerpt:
+
[source,yaml]
----
imageContentSources:
- mirrors:
  - <mirror_host_name>:5000/<repo_name>/release
  source: quay.example.com/openshift-release-dev/ocp-release
- mirrors:
  - <mirror_host_name>:5000/<repo_name>/release
  source: registry.example.com/ocp/release
----
+
To complete these values, use the `imageContentSources` that you recorded during mirror registry creation.

. Make any other modifications to the `install-config.yaml` file that you require. You can find more information about
the available parameters in the *Installation configuration parameters* section.
endif::restricted[]

. Back up the `install-config.yaml` file so that you can use
it to install multiple clusters.
+
[IMPORTANT]
====
The `install-config.yaml` file is consumed during the installation process. If
you want to reuse the file, you must back it up now.
====

ifdef::osp-user[You now have the file `install-config.yaml` in the directory that you specified.]

ifeval::["{context}" == "installing-aws-customizations"]
:!aws:
endif::[]
ifeval::["{context}" == "installing-aws-network-customizations"]
:!aws:
endif::[]
ifeval::["{context}" == "installing-aws-vpc"]
:!aws:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-aws-installer-provisioned"]
:!aws:
:!restricted:
endif::[]
ifeval::["{context}" == "installing-azure-customizations"]
:!azure:
endif::[]
ifeval::["{context}" == "installing-azure-network-customizations"]
:!azure:
endif::[]
ifeval::["{context}" == "installing-azure-vnet"]
:!azure:
endif::[]
ifeval::["{context}" == "installing-azure-user-infra"]
:!azure:
:!azure-user-infra:
endif::[]
ifeval::["{context}" == "installing-gcp-customizations"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-network-customizations"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-vpc"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-gcp-user-infra"]
:!gcp:
:!gcp-user-infra:
endif::[]
ifeval::["{context}" == "installing-gcp-user-infra-vpc"]
:!gcp:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-gcp"]
:!gcp:
:!restricted:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-gcp-installer-provisioned"]
:!gcp:
:!restricted:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-custom"]
:!osp:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-kuryr"]
:!osp:
endif::[]
ifeval::["{context}" == "installing-openstack-user"]
:!osp:
:!osp-user:
endif::[]
ifeval::["{context}" == "installing-openstack-user-kuryr"]
:!osp:
:!osp-user:
endif::[]
ifeval::["{context}" == "installing-openstack-user-sr-iov"]
:!osp:
:!osp-user:
endif::[]
ifeval::["{context}" == "installing-openstack-user-sr-iov-kuryr"]
:!osp:
:!osp-user:
endif::[]
ifeval::["{context}" == "installing-rhv-customizations"]
:!rhv:
endif::[]
ifeval::["{context}" == "installing-rhv-default"]
:!rhv:
endif::[]
ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"]
:!vsphere:
endif::[]
ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"]
:!vsphere:
endif::[]
ifeval::["{context}" == "installing-vmc-customizations"]
:!vsphere:
endif::[]
ifeval::["{context}" == "installing-vmc-network-customizations"]
:!vsphere:
endif::[]
ifeval::["{context}" == "installing-openstack-installer-restricted"]
:!osp:
:!restricted:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"]
:!vsphere:
:!restricted:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-vmc"]
:!vsphere:
:!restricted:
endif::[]