Chapter 1. Installing on AWS

Procedure

1. Identify your domain, or subdomain, and registrar. You can transfer an existing domain and registrar or obtain a new one through AWS or another source.

   Note

   If you purchase a new domain through AWS, it takes time for the relevant DNS changes to propagate. For more information about purchasing domains through AWS, see Registering Domain Names Using Amazon Route 53 in the AWS documentation.

2. If you are using an existing domain and registrar, migrate its DNS to AWS. See Making Amazon Route 53 the DNS Service for an Existing Domain in the AWS documentation.

3. Create a public hosted zone for your domain or subdomain. See Creating a Public Hosted Zone in the AWS documentation.

   Use an appropriate root domain, such as openshiftcorp.com, or subdomain, such as clusters.openshiftcorp.com.

4. Extract the new authoritative name servers from the hosted zone records. See Getting the Name Servers for a Public Hosted Zone in the AWS documentation.
5. Update the registrar records for the AWS Route 53 name servers that your domain uses. For example, if you registered your domain to a Route 53 service in a different accounts, see the following topic in the AWS documentation: Adding or Changing Name Servers or Glue Records.
6. If you are using a subdomain, add its delegation records to the parent domain. This gives Amazon Route 53 responsibility for the subdomain. Follow the delegation procedure outlined by the DNS provider of the parent domain. See Creating a subdomain that uses Amazon Route 53 as the DNS service without migrating the parent domain in the AWS documentation for an example high level procedure.

Procedure

1. Specify the IAM user name and select Programmatic access.

2. Attach the AdministratorAccess policy to ensure that the account has sufficient permission to create the cluster. This policy provides the cluster with the ability to grant credentials to each OpenShift Container Platform component. The cluster grants the components only the credentials that they require.

   Note

   While it is possible to create a policy that grants the all of the required AWS permissions and attach it to the user, this is not the preferred option. The cluster will not have the ability to grant additional credentials to individual components, so the same credentials are used by all components.

3. Optional: Add metadata to the user by attaching tags.
4. Confirm that the user name that you specified is granted the AdministratorAccess policy.

5. Record the access key ID and secret access key values. You must use these values when you configure your local machine to run the installation program.

   Important

   You cannot use a temporary session token that you generated while using a multi-factor authentication device to authenticate to AWS when you deploy a cluster. The cluster continues to use your current AWS credentials to create AWS resources for the entire life of the cluster, so you must use key-based, long-lived credentials.

Procedure

1. If you do not have an SSH key that is configured for password-less authentication on your computer, create one. For example, on a computer that uses a Linux operating system, run the following command:

   $ ssh-keygen -t ed25519 -N '' \
       -f <path>/<file_name> 1

   1

   Specify the path and file name, such as ~/.ssh/id_rsa, of the SSH key. Do not specify an existing SSH key, as it will be overwritten.

   Running this command generates an SSH key that does not require a password in the location that you specified.

2. Start the ssh-agent process as a background task:

   $ eval "$(ssh-agent -s)"
   
   Agent pid 31874

3. Add your SSH private key to the ssh-agent:

   $ ssh-add <path>/<file_name> 1
   
   Identity added: /home/<you>/<path>/<file_name> (<computer_name>)

   1

   Specify the path and file name for your SSH private key, such as ~/.ssh/id_rsa

Procedure

1. Access the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site. If you have a Red Hat account, log in with your credentials. If you do not, create an account.

2. Navigate to the page for your installation type, download the installation program for your operating system, and place the file in the directory where you will store the installation configuration files.

   Important

   The installation program creates several files on the computer that you use to install your cluster. You must keep both the installation program and the files that the installation program creates after you finish installing the cluster.

   Important

   Deleting the files created by the installation program does not remove your cluster, even if the cluster failed during installation. You must complete the OpenShift Container Platform uninstallation procedures outlined for your specific cloud provider to remove your cluster entirely.

3. Extract the installation program. For example, on a computer that uses a Linux operating system, run the following command:

   $ tar xvf <installation_program>.tar.gz

4. From the Pull Secret page on the Red Hat OpenShift Cluster Manager site, download your installation pull secret as a .txt file. This pull secret allows you to authenticate with the services that are provided by the included authorities, including Quay.io, which serves the container images for OpenShift Container Platform components.

Procedure

1. Run the installation program:

   $ ./openshift-install create cluster --dir=<installation_directory> \ 1
       --log-level=info 2

   1

   For <installation_directory>, specify the directory name to store the files that the installation program creates.

   2

   To view different installation details, specify warn, debug, or error instead of info.

   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 OpenShift Container Platform version.

   Provide values at the prompts:

   1. Optional: Select an SSH key to use to access your cluster machines.

      Note

      For production OpenShift Container Platform clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your ssh-agent process uses.

   2. Select aws as the platform to target.
   3. 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.
   4. Select the AWS region to deploy the cluster to.
   5. Select the base domain for the Route 53 service that you configured for your cluster.
   6. Enter a descriptive name for your cluster.
   7. Paste the pull secret that you obtained from the Pull Secret page on the Red Hat OpenShift Cluster Manager site.
   Note

   If the cloud provider account that you configured on your host does not have sufficient permissions to deploy the cluster, the installation process stops, and the missing permissions are displayed.

   When the cluster deployment completes, directions for accessing your cluster, including a link to its web console and credentials for the kubeadmin user, display in your terminal.

   Important

   The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending node-bootstrapper certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for Recovering from expired control plane certificates for more information.

   Important

   You must not delete the installation program or the files that the installation program creates. Both are required to delete the cluster.

2. Optional: Remove or disable the AdministratorAccess policy from the IAM account that you used to install the cluster.

Procedure

1. Export the kubeadmin credentials:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig 1

   1

   For <installation_directory>, specify the path to the directory that you stored the installation files in.

2. Verify you can run oc commands successfully using the exported configuration:

   $ oc whoami
   system:admin

Procedure

1. If you do not have an SSH key that is configured for password-less authentication on your computer, create one. For example, on a computer that uses a Linux operating system, run the following command:

   $ ssh-keygen -t ed25519 -N '' \
       -f <path>/<file_name> 1

   1

   Specify the path and file name, such as ~/.ssh/id_rsa, of the SSH key. Do not specify an existing SSH key, as it will be overwritten.

   Running this command generates an SSH key that does not require a password in the location that you specified.

2. Start the ssh-agent process as a background task:

   $ eval "$(ssh-agent -s)"
   
   Agent pid 31874

3. Add your SSH private key to the ssh-agent:

   $ ssh-add <path>/<file_name> 1
   
   Identity added: /home/<you>/<path>/<file_name> (<computer_name>)

   1

   Specify the path and file name for your SSH private key, such as ~/.ssh/id_rsa

Procedure

1. Access the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site. If you have a Red Hat account, log in with your credentials. If you do not, create an account.

2. Navigate to the page for your installation type, download the installation program for your operating system, and place the file in the directory where you will store the installation configuration files.

   Important

   The installation program creates several files on the computer that you use to install your cluster. You must keep both the installation program and the files that the installation program creates after you finish installing the cluster.

   Important

   Deleting the files created by the installation program does not remove your cluster, even if the cluster failed during installation. You must complete the OpenShift Container Platform uninstallation procedures outlined for your specific cloud provider to remove your cluster entirely.

3. Extract the installation program. For example, on a computer that uses a Linux operating system, run the following command:

   $ tar xvf <installation_program>.tar.gz

4. From the Pull Secret page on the Red Hat OpenShift Cluster Manager site, download your installation pull secret as a .txt file. This pull secret allows you to authenticate with the services that are provided by the included authorities, including Quay.io, which serves the container images for OpenShift Container Platform components.

Procedure

1. Create the install-config.yaml file.

   1. Run the following command:

      $ ./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 OpenShift Container Platform version.

   2. At the prompts, provide the configuration details for your cloud:

      1. Optional: Select an SSH key to use to access your cluster machines.

         Note

         For production OpenShift Container Platform clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your ssh-agent process uses.

      2. Select AWS as the platform to target.
      3. 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.
      4. Select the AWS region to deploy the cluster to.
      5. Select the base domain for the Route 53 service that you configured for your cluster.
      6. Enter a descriptive name for your cluster.
      7. Paste the pull secret that you obtained from the Pull Secret page on the Red Hat OpenShift Cluster Manager site.
2. Modify the install-config.yaml file. You can find more information about the available parameters in the Installation configuration parameters section.

3. 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.

Procedure

1. Run the installation program:

   $ ./openshift-install create cluster --dir=<installation_directory> \ 1
       --log-level=info 2

   1

   For <installation_directory>, specify the location of your customized ./install-config.yaml file.

   2

   To view different installation details, specify warn, debug, or error instead of info.

   Note

   If the cloud provider account that you configured on your host does not have sufficient permissions to deploy the cluster, the installation process stops, and the missing permissions are displayed.

   When the cluster deployment completes, directions for accessing your cluster, including a link to its web console and credentials for the kubeadmin user, display in your terminal.

   Important

   The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending node-bootstrapper certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for Recovering from expired control plane certificates for more information.

   Important

   You must not delete the installation program or the files that the installation program creates. Both are required to delete the cluster.

2. Optional: Remove or disable the AdministratorAccess policy from the IAM account that you used to install the cluster.

Procedure

1. Export the kubeadmin credentials:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig 1

   1

   For <installation_directory>, specify the path to the directory that you stored the installation files in.

2. Verify you can run oc commands successfully using the exported configuration:

   $ oc whoami
   system:admin

Procedure

1. If you do not have an SSH key that is configured for password-less authentication on your computer, create one. For example, on a computer that uses a Linux operating system, run the following command:

   $ ssh-keygen -t ed25519 -N '' \
       -f <path>/<file_name> 1

   1

   Specify the path and file name, such as ~/.ssh/id_rsa, of the SSH key. Do not specify an existing SSH key, as it will be overwritten.

   Running this command generates an SSH key that does not require a password in the location that you specified.

2. Start the ssh-agent process as a background task:

   $ eval "$(ssh-agent -s)"
   
   Agent pid 31874

3. Add your SSH private key to the ssh-agent:

   $ ssh-add <path>/<file_name> 1
   
   Identity added: /home/<you>/<path>/<file_name> (<computer_name>)

   1

   Specify the path and file name for your SSH private key, such as ~/.ssh/id_rsa

Procedure

1. Access the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site. If you have a Red Hat account, log in with your credentials. If you do not, create an account.

2. Navigate to the page for your installation type, download the installation program for your operating system, and place the file in the directory where you will store the installation configuration files.

   Important

   The installation program creates several files on the computer that you use to install your cluster. You must keep both the installation program and the files that the installation program creates after you finish installing the cluster.

   Important

   Deleting the files created by the installation program does not remove your cluster, even if the cluster failed during installation. You must complete the OpenShift Container Platform uninstallation procedures outlined for your specific cloud provider to remove your cluster entirely.

3. Extract the installation program. For example, on a computer that uses a Linux operating system, run the following command:

   $ tar xvf <installation_program>.tar.gz

4. From the Pull Secret page on the Red Hat OpenShift Cluster Manager site, download your installation pull secret as a .txt file. This pull secret allows you to authenticate with the services that are provided by the included authorities, including Quay.io, which serves the container images for OpenShift Container Platform components.

Procedure

1. Create the install-config.yaml file.

   1. Run the following command:

      $ ./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 OpenShift Container Platform version.

   2. At the prompts, provide the configuration details for your cloud:

      1. Optional: Select an SSH key to use to access your cluster machines.

         Note

         For production OpenShift Container Platform clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your ssh-agent process uses.

      2. Select AWS as the platform to target.
      3. 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.
      4. Select the AWS region to deploy the cluster to.
      5. Select the base domain for the Route 53 service that you configured for your cluster.
      6. Enter a descriptive name for your cluster.
      7. Paste the pull secret that you obtained from the Pull Secret page on the Red Hat OpenShift Cluster Manager site.
2. Modify the install-config.yaml file. You can find more information about the available parameters in the Installation configuration parameters section.

3. 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.

Procedure

1. Use the following command to create manifests:

   $ ./openshift-install create manifests --dir=<installation_directory> 1

   1

   For <installation_directory>, specify the name of the directory that contains the install-config.yaml file for your cluster.

2. Create a file that is named cluster-network-03-config.yml in the <installation_directory>/manifests/ directory:

   $ touch <installation_directory>/manifests/cluster-network-03-config.yml 1

   1

   For <installation_directory>, specify the directory name that contains the manifests/ directory for your cluster.

   After creating the file, several network configuration files are in the manifests/ directory, as shown:

   $ ls <installation_directory>/manifests/cluster-network-*

   Example output

   cluster-network-01-crd.yml
   cluster-network-02-config.yml
   cluster-network-03-config.yml

3. Open the cluster-network-03-config.yml file in an editor and enter a CR that describes the Operator configuration you want:

   apiVersion: operator.openshift.io/v1
   kind: Network
   metadata:
     name: cluster
   spec: 1
     clusterNetwork:
     - cidr: 10.128.0.0/14
       hostPrefix: 23
     serviceNetwork:
     - 172.30.0.0/16
     defaultNetwork:
       type: OpenShiftSDN
       openshiftSDNConfig:
         mode: NetworkPolicy
         mtu: 1450
         vxlanPort: 4789

   1

   The parameters for the spec parameter are only an example. Specify your configuration for the Cluster Network Operator in the CR.

   The CNO provides default values for the parameters in the CR, so you must specify only the parameters that you want to change.

4. Save the cluster-network-03-config.yml file and quit the text editor.
5. Optional: Back up the manifests/cluster-network-03-config.yml file. The installation program deletes the manifests/ directory when creating the cluster.

Procedure

1. Run the installation program:

   $ ./openshift-install create cluster --dir=<installation_directory> \ 1
       --log-level=info 2

   1

   For <installation_directory>, specify the location of your customized ./install-config.yaml file.

   2

   To view different installation details, specify warn, debug, or error instead of info.

   Note

   If the cloud provider account that you configured on your host does not have sufficient permissions to deploy the cluster, the installation process stops, and the missing permissions are displayed.

   When the cluster deployment completes, directions for accessing your cluster, including a link to its web console and credentials for the kubeadmin user, display in your terminal.

   Important

   The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending node-bootstrapper certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for Recovering from expired control plane certificates for more information.

   Important

   You must not delete the installation program or the files that the installation program creates. Both are required to delete the cluster.

2. Optional: Remove or disable the AdministratorAccess policy from the IAM account that you used to install the cluster.

Procedure

1. Export the kubeadmin credentials:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig 1

   1

   For <installation_directory>, specify the path to the directory that you stored the installation files in.

2. Verify you can run oc commands successfully using the exported configuration:

   $ oc whoami
   system:admin

Procedure

1. If you do not have an SSH key that is configured for password-less authentication on your computer, create one. For example, on a computer that uses a Linux operating system, run the following command:

   $ ssh-keygen -t ed25519 -N '' \
       -f <path>/<file_name> 1

   1

   Specify the path and file name, such as ~/.ssh/id_rsa, of the SSH key. Do not specify an existing SSH key, as it will be overwritten.

   Running this command generates an SSH key that does not require a password in the location that you specified.

2. Start the ssh-agent process as a background task:

   $ eval "$(ssh-agent -s)"
   
   Agent pid 31874

3. Add your SSH private key to the ssh-agent:

   $ ssh-add <path>/<file_name> 1
   
   Identity added: /home/<you>/<path>/<file_name> (<computer_name>)

   1

   Specify the path and file name for your SSH private key, such as ~/.ssh/id_rsa

Procedure

1. Access the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site. If you have a Red Hat account, log in with your credentials. If you do not, create an account.

2. Navigate to the page for your installation type, download the installation program for your operating system, and place the file in the directory where you will store the installation configuration files.

   Important

   The installation program creates several files on the computer that you use to install your cluster. You must keep both the installation program and the files that the installation program creates after you finish installing the cluster.

   Important

   Deleting the files created by the installation program does not remove your cluster, even if the cluster failed during installation. You must complete the OpenShift Container Platform uninstallation procedures outlined for your specific cloud provider to remove your cluster entirely.

3. Extract the installation program. For example, on a computer that uses a Linux operating system, run the following command:

   $ tar xvf <installation_program>.tar.gz

4. From the Pull Secret page on the Red Hat OpenShift Cluster Manager site, download your installation pull secret as a .txt file. This pull secret allows you to authenticate with the services that are provided by the included authorities, including Quay.io, which serves the container images for OpenShift Container Platform components.

Procedure

1. Create the install-config.yaml file.

   1. Run the following command:

      $ ./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 OpenShift Container Platform version.

   2. At the prompts, provide the configuration details for your cloud:

      1. Optional: Select an SSH key to use to access your cluster machines.

         Note

         For production OpenShift Container Platform clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your ssh-agent process uses.

      2. Select AWS as the platform to target.
      3. 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.
      4. Select the AWS region to deploy the cluster to.
      5. Select the base domain for the Route 53 service that you configured for your cluster.
      6. Enter a descriptive name for your cluster.
      7. Paste the pull secret that you obtained from the Pull Secret page on the Red Hat OpenShift Cluster Manager site.
2. Modify the install-config.yaml file. You can find more information about the available parameters in the Installation configuration parameters section.

3. 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.

Procedure

1. Run the installation program:

   $ ./openshift-install create cluster --dir=<installation_directory> \ 1
       --log-level=info 2

   1

   For <installation_directory>, specify the location of your customized ./install-config.yaml file.

   2

   To view different installation details, specify warn, debug, or error instead of info.

   Note

   If the cloud provider account that you configured on your host does not have sufficient permissions to deploy the cluster, the installation process stops, and the missing permissions are displayed.

   When the cluster deployment completes, directions for accessing your cluster, including a link to its web console and credentials for the kubeadmin user, display in your terminal.

   Important

   The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending node-bootstrapper certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for Recovering from expired control plane certificates for more information.

   Important

   You must not delete the installation program or the files that the installation program creates. Both are required to delete the cluster.

2. Optional: Remove or disable the AdministratorAccess policy from the IAM account that you used to install the cluster.

Procedure

1. Export the kubeadmin credentials:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig 1

   1

   For <installation_directory>, specify the path to the directory that you stored the installation files in.

2. Verify you can run oc commands successfully using the exported configuration:

   $ oc whoami
   system:admin

Procedure

1. If you do not have an SSH key that is configured for password-less authentication on your computer, create one. For example, on a computer that uses a Linux operating system, run the following command:

   $ ssh-keygen -t ed25519 -N '' \
       -f <path>/<file_name> 1

   1

   Specify the path and file name, such as ~/.ssh/id_rsa, of the SSH key. Do not specify an existing SSH key, as it will be overwritten.

   Running this command generates an SSH key that does not require a password in the location that you specified.

2. Start the ssh-agent process as a background task:

   $ eval "$(ssh-agent -s)"
   
   Agent pid 31874

3. Add your SSH private key to the ssh-agent:

   $ ssh-add <path>/<file_name> 1
   
   Identity added: /home/<you>/<path>/<file_name> (<computer_name>)

   1

   Specify the path and file name for your SSH private key, such as ~/.ssh/id_rsa

Procedure

1. Access the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site. If you have a Red Hat account, log in with your credentials. If you do not, create an account.

2. Navigate to the page for your installation type, download the installation program for your operating system, and place the file in the directory where you will store the installation configuration files.

   Important

   The installation program creates several files on the computer that you use to install your cluster. You must keep both the installation program and the files that the installation program creates after you finish installing the cluster.

   Important

   Deleting the files created by the installation program does not remove your cluster, even if the cluster failed during installation. You must complete the OpenShift Container Platform uninstallation procedures outlined for your specific cloud provider to remove your cluster entirely.

3. Extract the installation program. For example, on a computer that uses a Linux operating system, run the following command:

   $ tar xvf <installation_program>.tar.gz

4. From the Pull Secret page on the Red Hat OpenShift Cluster Manager site, download your installation pull secret as a .txt file. This pull secret allows you to authenticate with the services that are provided by the included authorities, including Quay.io, which serves the container images for OpenShift Container Platform components.

Procedure

1. Create an installation directory to store your required installation assets in:

   $ mkdir <installation_directory>

   Important

   You must create a 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 OpenShift Container Platform version.

2. Customize the following install-config.yaml file template and save it in the <installation_directory>.

   Note

   You must name this configuration file install-config.yaml.

3. 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 next step of the installation process. You must back it up now.

Procedure

1. Run the installation program:

   $ ./openshift-install create cluster --dir=<installation_directory> \ 1
       --log-level=info 2

   1

   For <installation_directory>, specify the

   2

   To view different installation details, specify warn, debug, or error instead of info.

   Note

   If the cloud provider account that you configured on your host does not have sufficient permissions to deploy the cluster, the installation process stops, and the missing permissions are displayed.

   When the cluster deployment completes, directions for accessing your cluster, including a link to its web console and credentials for the kubeadmin user, display in your terminal.

   Important

   The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending node-bootstrapper certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for Recovering from expired control plane certificates for more information.

   Important

   You must not delete the installation program or the files that the installation program creates. Both are required to delete the cluster.

Procedure

1. Export the kubeadmin credentials:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig 1

   1

   For <installation_directory>, specify the path to the directory that you stored the installation files in.

2. Verify you can run oc commands successfully using the exported configuration:

   $ oc whoami
   system:admin

Procedure

1. Access the Infrastructure Provider page on the Red Hat OpenShift Cluster Manager site. If you have a Red Hat account, log in with your credentials. If you do not, create an account.

2. Navigate to the page for your installation type, download the installation program for your operating system, and place the file in the directory where you will store the installation configuration files.

   Important

   The installation program creates several files on the computer that you use to install your cluster. You must keep both the installation program and the files that the installation program creates after you finish installing the cluster.

   Important

   Deleting the files created by the installation program does not remove your cluster, even if the cluster failed during installation. You must complete the OpenShift Container Platform uninstallation procedures outlined for your specific cloud provider to remove your cluster entirely.

3. Extract the installation program. For example, on a computer that uses a Linux operating system, run the following command:

   $ tar xvf <installation_program>.tar.gz

4. From the Pull Secret page on the Red Hat OpenShift Cluster Manager site, download your installation pull secret as a .txt file. This pull secret allows you to authenticate with the services that are provided by the included authorities, including Quay.io, which serves the container images for OpenShift Container Platform components.

Procedure

1. If you do not have an SSH key that is configured for password-less authentication on your computer, create one. For example, on a computer that uses a Linux operating system, run the following command:

   $ ssh-keygen -t ed25519 -N '' \
       -f <path>/<file_name> 1

   1

   Specify the path and file name, such as ~/.ssh/id_rsa, of the SSH key. Do not specify an existing SSH key, as it will be overwritten.

   Running this command generates an SSH key that does not require a password in the location that you specified.

2. Start the ssh-agent process as a background task:

   $ eval "$(ssh-agent -s)"
   
   Agent pid 31874

3. Add your SSH private key to the ssh-agent:

   $ ssh-add <path>/<file_name> 1
   
   Identity added: /home/<you>/<path>/<file_name> (<computer_name>)

   1

   Specify the path and file name for your SSH private key, such as ~/.ssh/id_rsa

Procedure

1. Create a JSON file that contains the parameter values that the template requires:

   [
     {
       "ParameterKey": "VpcCidr", 1
       "ParameterValue": "10.0.0.0/16" 2
     },
     {
       "ParameterKey": "AvailabilityZoneCount", 3
       "ParameterValue": "1" 4
     },
     {
       "ParameterKey": "SubnetBits", 5
       "ParameterValue": "12" 6
     }
   ]

   1

   The CIDR block for the VPC.

   2

   Specify a CIDR block in the format x.x.x.x/16-24.

   3

   The number of availability zones to deploy the VPC in.

   4

   Specify an integer between 1 and 3.

   5

   The size of each subnet in each availability zone.

   6

   Specify an integer between 5 and 13, where 5 is /27 and 13 is /19.

2. Copy the template from the CloudFormation template for the VPC section of this topic and save it as a YAML file on your computer. This template describes the VPC that your cluster requires.

3. Launch the template:

   Important

   You must enter the command on a single line.

   $ aws cloudformation create-stack --stack-name <name> 1
        --template-body file://<template>.yaml 2
        --parameters file://<parameters>.json 3

   1

   <name> is the name for the CloudFormation stack, such as cluster-vpc. You need the name of this stack if you remove the cluster.

   2

   <template> is the relative path to and name of the CloudFormation template YAML file that you saved.

   3

   <parameters> is the relative path to and name of the CloudFormation parameters JSON file.

4. Confirm that the template components exist:

   $ aws cloudformation describe-stacks --stack-name <name>

   After the StackStatus displays CREATE_COMPLETE, the output displays values for the following parameters. You must provide these parameter values to the other CloudFormation templates that you run to create your cluster:

   VpcId	The ID of your VPC.
   PublicSubnetIds	The IDs of the new public subnets.
   PrivateSubnetIds	The IDs of the new private subnets.

Procedure

1. Obtain the Hosted Zone ID for the Route 53 zone that you specified in the install-config.yaml file for your cluster. You can obtain this ID from the AWS console or by running the following command:

   Important

   You must enter the command on a single line.

   $ aws route53 list-hosted-zones-by-name |
        jq --arg name "<route53_domain>." \ 1
        -r '.HostedZones | .[] | select(.Name=="\($name)") | .Id'

   1

   For the <route53_domain>, specify the Route 53 base domain that you used when you generated the install-config.yaml file for the cluster.

2. Create a JSON file that contains the parameter values that the template requires:

   [
     {
       "ParameterKey": "ClusterName", 1
       "ParameterValue": "mycluster" 2
     },
     {
       "ParameterKey": "InfrastructureName", 3
       "ParameterValue": "mycluster-<random_string>" 4
     },
     {
       "ParameterKey": "HostedZoneId", 5
       "ParameterValue": "<random_string>" 6
     },
     {
       "ParameterKey": "HostedZoneName", 7
       "ParameterValue": "example.com" 8
     },
     {
       "ParameterKey": "PublicSubnets", 9
       "ParameterValue": "subnet-<random_string>" 10
     },
     {
       "ParameterKey": "PrivateSubnets", 11
       "ParameterValue": "subnet-<random_string>" 12
     },
     {
       "ParameterKey": "VpcId", 13
       "ParameterValue": "vpc-<random_string>" 14
     }
   ]

   1

   A short, representative cluster name to use for host names, etc.

   2

   Specify the cluster name that you used when you generated the install-config.yaml file for the cluster.

   3

   The name for your cluster infrastructure that is encoded in your Ignition config files for the cluster.

   4

   Specify the infrastructure name that you extracted from the Ignition config file metadata, which has the format <cluster-name>-<random-string>.

   5

   The Route 53 public zone ID to register the targets with.

   6

   Specify the Route 53 public zone ID, which as a format similar to Z21IXYZABCZ2A4. You can obtain this value from the AWS console.

   7

   The Route 53 zone to register the targets with.

   8

   Specify the Route 53 base domain that you used when you generated the install-config.yaml file for the cluster. Do not include the trailing period (.) that is displayed in the AWS console.

   9

   The public subnets that you created for your VPC.

   10

   Specify the PublicSubnetIds value from the output of the CloudFormation template for the VPC.

   11

   The private subnets that you created for your VPC.

   12

   Specify the PrivateSubnetIds value from the output of the CloudFormation template for the VPC.

   13

   The VPC that you created for the cluster.

   14

   Specify the VpcId value from the output of the CloudFormation template for the VPC.

3. Copy the template from the CloudFormation template for the network and load balancers section of this topic and save it as a YAML file on your computer. This template describes the networking and load balancing objects that your cluster requires.

4. Launch the template:

   Important

   You must enter the command on a single line.

   $ aws cloudformation create-stack --stack-name <name> 1
        --template-body file://<template>.yaml 2
        --parameters file://<parameters>.json 3
        --capabilities CAPABILITY_NAMED_IAM

   1

   <name> is the name for the CloudFormation stack, such as cluster-dns. You need the name of this stack if you remove the cluster.

   2

   <template> is the relative path to and name of the CloudFormation template YAML file that you saved.

   3

   <parameters> is the relative path to and name of the CloudFormation parameters JSON file.

5. Confirm that the template components exist:

   $ aws cloudformation describe-stacks --stack-name <name>

   After the StackStatus displays CREATE_COMPLETE, the output displays values for the following parameters. You must provide these parameter values to the other CloudFormation templates that you run to create your cluster:

   PrivateHostedZoneId	Hosted zone ID for the private DNS.
   ExternalApiLoadBalancerName	Full name of the external API load balancer.
   InternalApiLoadBalancerName	Full name of the internal API load balancer.
   ApiServerDnsName	Full host name of the API server.
   RegisterNlbIpTargetsLambda	Lambda ARN useful to help register/deregister IP targets for these load balancers.
   ExternalApiTargetGroupArn	ARN of external API target group.
   InternalApiTargetGroupArn	ARN of internal API target group.
   InternalServiceTargetGroupArn	ARN of internal service target group.

Procedure

1. Create a JSON file that contains the parameter values that the template requires:

   [
     {
       "ParameterKey": "InfrastructureName", 1
       "ParameterValue": "mycluster-<random_string>" 2
     },
     {
       "ParameterKey": "VpcCidr", 3
       "ParameterValue": "10.0.0.0/16" 4
     },
     {
       "ParameterKey": "PrivateSubnets", 5
       "ParameterValue": "subnet-<random_string>" 6
     },
     {
       "ParameterKey": "VpcId", 7
       "ParameterValue": "vpc-<random_string>" 8
     }
   ]

   1

   The name for your cluster infrastructure that is encoded in your Ignition config files for the cluster.

   2

   Specify the infrastructure name that you extracted from the Ignition config file metadata, which has the format <cluster-name>-<random-string>.

   3

   The CIDR block for the VPC.

   4

   Specify the CIDR block parameter that you used for the VPC that you defined in the form x.x.x.x/16-24.

   5

   The private subnets that you created for your VPC.

   6

   Specify the PrivateSubnetIds value from the output of the CloudFormation template for the VPC.

   7

   The VPC that you created for the cluster.

   8

   Specify the VpcId value from the output of the CloudFormation template for the VPC.

2. Copy the template from the CloudFormation template for security objects section of this topic and save it as a YAML file on your computer. This template describes the security groups and roles that your cluster requires.

3. Launch the template:

   Important

   You must enter the command on a single line.

   $ aws cloudformation create-stack --stack-name <name> 1
        --template-body file://<template>.yaml 2
        --parameters file://<parameters>.json 3
        --capabilities CAPABILITY_NAMED_IAM

   1

   <name> is the name for the CloudFormation stack, such as cluster-sec. You need the name of this stack if you remove the cluster.

   2

   <template> is the relative path to and name of the CloudFormation template YAML file that you saved.

   3

   <parameters> is the relative path to and name of the CloudFormation parameters JSON file.

4. Confirm that the template components exist:

   $ aws cloudformation describe-stacks --stack-name <name>

   After the StackStatus displays CREATE_COMPLETE, the output displays values for the following parameters. You must provide these parameter values to the other CloudFormation templates that you run to create your cluster:

   MasterSecurityGroupId	Master Security Group ID
   WorkerSecurityGroupId	Worker Security Group ID
   MasterInstanceProfile	Master IAM Instance Profile
   WorkerInstanceProfile	Worker IAM Instance Profile