openshift-docs/modules/installation-initializing-manual.adoc

// Module included in the following assemblies:
//
// * installing/installing_aws/installing-aws-government-region.adoc
// * installing/installing_aws/installing-aws-secret-region.adoc
// * installing/installing_aws/installing-aws-private.adoc
// * installing/installing_azure/installing-azure-government-region.adoc
// * installing/installing_azure/installing-azure-private.adoc
// * installing/installing_azure_stack_hub/installing-azure-stack-hub-user-infra.adoc
// * installing/installing_azure_stack_hub/installing-azure-stack-hub-default.adoc
// * installing/installing_bare_metal/upi/installing-bare-metal.adoc
// * installing/installing_gcp/installing-gcp-private.adoc
// * installing/installing_gcp/installing-gcp-shared-vpc.adoc
// * installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc
// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc
// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc
// * installing/installing_vsphere/installing-vsphere.adoc
// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc
// * installing/installing_ibm_z/installing-ibm-z.adoc
// * installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc
// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc
// * installing/installing_ibm_z/installing-restricted-networks-ibm-z-kvm.adoc
// * installing/installing_ibm_z/installing-ibm-z-lpar.adoc
// * installing/installing_ibm_z/installing-restricted-networks-ibm-z-lpar.adoc
// * installing/installing_azure_stack_hub/installing-azure-stack-hub-network-customizations.adoc
// * installing/installing_ibm_powervs/installing-ibm-power-vs-private-cluster.adoc

ifeval::["{context}" == "installing-azure-government-region"]
:azure-gov:
endif::[]
ifeval::["{context}" == "installing-azure-stack-hub-user-infra"]
:ash:
endif::[]
ifeval::["{context}" == "installing-vsphere"]
:vsphere-upi-vsphere:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-vsphere"]
:restricted-upi:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-bare-metal"]
:restricted:
endif::[]
ifeval::["{context}" == "installing-vsphere-network-customizations"]
:vsphere-upi:
endif::[]
ifeval::["{context}" == "installing-aws-china-region"]
:aws-china:
endif::[]
ifeval::["{context}" == "installing-aws-government-region"]
:aws-gov:
endif::[]
ifeval::["{context}" == "installing-aws-secret-region"]
:aws-secret:
endif::[]
ifeval::["{context}" == "installing-aws-private"]
:aws-private:
endif::[]
ifeval::["{context}" == "installing-azure-private"]
:azure-private:
endif::[]
ifeval::["{context}" == "installing-gcp-private"]
:gcp-private:
endif::[]
ifeval::["{context}" == "installing-gcp-shared-vpc"]
:gcp-shared:
endif::[]
ifeval::["{context}" == "installing-azure-stack-hub-default"]
:ash-default:
endif::[]
ifeval::["{context}" == "installing-azure-stack-hub-network-customizations"]
:ash-network:
endif::[]
ifeval::["{context}" == "installing-ibm-cloud-private"]
:ibm-cloud-private:
endif::[]
ifeval::["{context}" == "installing-ibm-power-vs-private-cluster"]
:ibm-power-vs-private:
endif::[]
ifeval::["{context}" == "installing-ibm-cloud-restricted"]
:ibm-cloud-restricted:
endif::[]

:_mod-docs-content-type: PROCEDURE
[id="installation-initializing-manual_{context}"]
= Manually creating the installation configuration file

[role="_abstract"]
To customise your {product-title} deployment and meet specific network requirements, manually create the installation configuration file. This ensures that the installation program uses your tailored settings rather than default values during the setup process.

ifdef::vsphere-upi,restricted-upi[]
[IMPORTANT]
====
The 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[]

.Prerequisites

ifdef::aws-china,aws-secret[]
* You have uploaded a custom RHCOS AMI.
endif::aws-china,aws-secret[]
ifndef::ibm-cloud-restricted[]
* You have an SSH public key on your local machine for use with the installation program. You can use the key for SSH authentication onto your cluster nodes for debugging and disaster recovery.
endif::ibm-cloud-restricted[]
* You have obtained the {product-title} installation program and the pull secret for your
cluster.
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,restricted-upi[]
ifdef::ibm-cloud-restricted[]
* You have the `imageContentSourcePolicy.yaml` file that was created when you mirrored your registry.
* You have obtained the contents of the certificate for your mirror registry.
endif::ibm-cloud-restricted[]

.Procedure

. Create an installation directory to store your required installation assets in:
+
[source,terminal]
----
$ mkdir <installation_directory>
----
+
[IMPORTANT]
====
You must create a directory. Some installation assets, such as 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.
====

. Customize the provided sample `install-config.yaml` file template and save the file in the `<installation_directory>`.
ifdef::ibm-cloud-restricted[]
+
[NOTE]
====
You must name this configuration file `install-config.yaml`.
====
+
When customizing the sample template, be sure to provide the 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. The certificate file can be an existing, trusted certificate authority, or the self-signed certificate that you generated for the mirror registry.
+
.. Define the network and subnets for the VPC to install the cluster in under the parent `platform.ibmcloud` field:
+
[source,yaml]
----
vpcName: <existing_vpc>
controlPlaneSubnets: <control_plane_subnet>
computeSubnets: <compute_subnet>
----
+
For `platform.ibmcloud.vpcName`, specify the name for the existing {ibm-cloud-title} Virtual Private Cloud (VPC) network. For `platform.ibmcloud.controlPlaneSubnets` and `platform.ibmcloud.computeSubnets`, specify the existing subnets to deploy the control plane machines and compute machines, respectively.
+
.. Add the image content resources, which resemble the following YAML excerpt:
+
[source,yaml]
----
imageContentSources:
- mirrors:
  - <mirror_host_name>:5000/<repo_name>/release
  source: quay.io/openshift-release-dev/ocp-release
- mirrors:
  - <mirror_host_name>:5000/<repo_name>/release
  source: registry.redhat.io/ocp/release
----
+
For these values, use the `imageContentSourcePolicy.yaml` file that was created when you mirrored the registry.
+
.. If network restrictions limit the use of public endpoints to access the required {ibm-cloud-name} services, add the `serviceEndpoints` stanza to `platform.ibmcloud` to specify an alternate service endpoint.
+
[NOTE]
====
You can specify only one alternate service endpoint for each service.
====
+
.Example of using alternate services endpoints
[source,yaml]
----
# ...
serviceEndpoints:
  - name: IAM
    url: <iam_alternate_endpoint_url>
  - name: VPC
    url: <vpc_alternate_endpoint_url>
  - name: ResourceController
    url: <resource_controller_alternate_endpoint_url>
  - name: ResourceManager
    url: <resource_manager_alternate_endpoint_url>
  - name: DNSServices
    url: <dns_services_alternate_endpoint_url>
  - name: COS
    url: <cos_alternate_endpoint_url>
  - name: GlobalSearch
    url: <global_search_alternate_endpoint_url>
  - name: GlobalTagging
    url: <global_tagging_alternate_endpoint_url>
# ...
----
+
.. Optional: Set the publishing strategy to `Internal`:
+
[source,yaml]
----
publish: Internal
----
+
By setting this option, you create an internal Ingress Controller and a private load balancer.
+
[NOTE]
====
If you use the default value of `External`, your network must be able to access the public endpoint for {ibm-cloud-name} Internet Services (CIS). CIS is not enabled for Virtual Private Endpoints.
====
endif::ibm-cloud-restricted[]
ifndef::ibm-cloud-restricted[]
+
[NOTE]
====
You must name this configuration file `install-config.yaml`.
====
endif::ibm-cloud-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.
+
[IMPORTANT]
====
** The `ImageContentSourcePolicy` file is generated as an output of `oc mirror` after the mirroring process is finished.
** The `oc mirror` command generates an `ImageContentSourcePolicy` file which contains the YAML needed to define `ImageContentSourcePolicy`.
Copy the text from this file and paste it into your `install-config.yaml` file.
** You must run the 'oc mirror' command twice. The first time you run the `oc mirror` command, you get a full `ImageContentSourcePolicy` file. The second time you run the `oc mirror` command, you only get the difference between the first and second run.
Because of this behavior, you must always keep a backup of these files in case you need to merge them into one complete `ImageContentSourcePolicy` file. Keeping a backup of these two output files ensures that you have a complete `ImageContentSourcePolicy` file.
====
endif::restricted,restricted-upi[]

ifdef::ash[]
+
Make the following modifications for Azure Stack Hub:
+
.. Set the `replicas` parameter to `0` for the `compute` pool:
+
[source,yaml]
----
compute:
- hyperthreading: Enabled
  name: worker
  platform: {}
  replicas: 0
----
* `replicas`: Set to `0`.
+
The compute machines will be provisioned manually later.
+
.. Update the `platform.azure` section of the `install-config.yaml` file to configure your Azure Stack Hub configuration:
+
[source,yaml]
----
platform:
  azure:
    armEndpoint: <azurestack_arm_endpoint>
    baseDomainResourceGroupName: <resource_group>
    cloudName: AzureStackCloud
    region: <azurestack_region>
----
+
where:
+
`<azurestack_arm_endpoint>`:: Specifies the Azure Resource Manager endpoint of your Azure Stack Hub environment, like `\https://management.local.azurestack.external`.
`<resource_group>`:: Specifies the name of the resource group that contains the DNS zone for your base domain.
`cloudName`:: Specifies the Azure Stack Hub environment, which is used to configure the Azure SDK with the appropriate Azure API endpoints.
`region`:: Specifies the name of your Azure Stack Hub region.
endif::ash[]

ifdef::ash-default,ash-network[]
+
Make the following modifications:
+
.. Specify the required installation parameters.
+
.. Update the `platform.azure` section to specify the parameters that are specific to Azure Stack Hub.
+
.. Optional: Update one or more of the default configuration parameters to customize the installation.
+
For more information about the parameters, see "Installation configuration parameters".
endif::ash-default,ash-network[]

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::vsphere-upi-vsphere[]

. Back up the `install-config.yaml` file so that you can use it to install many clusters.
+
[IMPORTANT]
====
Back up the `install-config.yaml` file now, because the installation process consumes the file in the next step.
====

ifeval::["{context}" == "installing-azure-government-region"]
:!azure-gov:
endif::[]
ifeval::["{context}" == "installing-azure-stack-hub-user-infra"]
:!ash:
endif::[]
ifeval::["{context}" == "installing-vsphere"]
:!vsphere-upi-vsphere:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-vsphere"]
:!restricted-upi:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-bare-metal"]
:!restricted:
endif::[]
ifeval::["{context}" == "installing-vsphere-network-customizations"]
:!vsphere-upi:
endif::[]
ifeval::["{context}" == "installing-aws-china-region"]
:!aws-china:
endif::[]
ifeval::["{context}" == "installing-aws-government-region"]
:!aws-gov:
endif::[]
ifeval::["{context}" == "installing-aws-secret-region"]
:!aws-secret:
endif::[]
ifeval::["{context}" == "installing-aws-private"]
:!aws-private:
endif::[]
ifeval::["{context}" == "installing-azure-private"]
:!azure-private:
endif::[]
ifeval::["{context}" == "installing-gcp-private"]
:!gcp-private:
endif::[]
ifeval::["{context}" == "installing-gcp-shared-vpc"]
:!gcp-shared:
endif::[]
ifeval::["{context}" == "installing-azure-stack-hub-default"]
:!ash-default:
endif::[]
ifeval::["{context}" == "installing-azure-stack-hub-network-customizations"]
:!ash-network:
endif::[]
ifeval::["{context}" == "installing-ibm-cloud-private"]
:!ibm-cloud-private:
endif::[]
ifeval::["{context}" == "installing-ibm-power-vs-private-cluster"]
:!ibm-power-vs-private:
endif::[]
ifeval::["{context}" == "installing-ibm-cloud-restricted"]
:!ibm-cloud-restricted:
endif::[]
:!platform: