Chapter 6. Installing a cluster on AWS in a restricted network

Procedure

1. If you do not have an existing SSH key pair on your local machine to use for authentication onto your cluster nodes, 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_ed25519, of the new SSH key. If you have an existing key pair, ensure your public key is in the your ~/.ssh directory.

   Note

   If you plan to install an OpenShift Container Platform cluster that uses the RHEL cryptographic libraries that have been submitted to NIST for FIPS 140-2/140-3 Validation on only the

   x86_64

   ,

   ppc64le

   , and

   s390x

   architectures, do not create a key that uses the

   ed25519

   algorithm. Instead, create a key that uses the

   rsa

   or

   ecdsa

   algorithm.

2. View the public SSH key:

   $ cat <path>/<file_name>.pub

   For example, run the following to view the

   ~/.ssh/id_ed25519.pub

   public key:

   $ cat ~/.ssh/id_ed25519.pub

3. Add the SSH private key identity to the SSH agent for your local user, if it has not already been added. SSH agent management of the key is required for password-less SSH authentication onto your cluster nodes, or if you want to use the

   ./openshift-install gather

   command.
   Note

   On some distributions, default SSH private key identities such as

   ~/.ssh/id_rsa

   and

   ~/.ssh/id_dsa

   are managed automatically.

   1. If the

      ssh-agent

      process is not already running for your local user, start it as a background task:

      $ eval "$(ssh-agent -s)"

      Example output

      Agent pid 31874

      Note

      If your cluster is in FIPS mode, only use FIPS-compliant algorithms to generate the SSH key. The key must be either RSA or ECDSA.

4. Add your SSH private key to the

   ssh-agent

   :

   $ ssh-add <path>/<file_name> 

   1

   1

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

   Example output

   Identity added: /home/<you>/<path>/<file_name> (<computer_name>)

Procedure

1. Create the

   install-config.yaml

   file.

   1. Change to the directory that contains the installation program and 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.

      When specifying the directory:

      • Verify that the directory has the

        execute

        permission. This permission is required to run Terraform binaries under the installation directory.

      • Use an empty directory. Some installation assets, such as bootstrap X.509 certificates, have short expiration intervals, therefore 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.

        Note

        Always delete the

        ~/.powervs

        directory to avoid reusing a stale configuration. Run the following command:

        $ rm -rf ~/.powervs

   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.

2. Edit the

   install-config.yaml

   file to give the additional information that is required for an installation in a restricted network.

   1. Update the

      pullSecret

      value to contain the authentication information for your registry:

      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.

   2. Add the

      additionalTrustBundle

      parameter and value.

      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.

   3. Define the subnets for the VPC to install the cluster in:

      subnets:
      - subnet-1
      - subnet-2
      - subnet-3

   4. Add the image content resources, which resemble the following YAML excerpt:

      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

      imageContentSources

      that you recorded during mirror registry creation.

   5. Optional: Set the publishing strategy to

      Internal

      :

      publish: Internal

      By setting this option, you create an internal Ingress Controller and a private load balancer.

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

4. 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. Change to the directory that contains the installation program and initialize the cluster deployment:

   $ ./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.

2. Optional: Remove or disable the

   AdministratorAccess

   policy from the IAM account that you used to install the cluster.
   Note

   The elevated permissions provided by the

   AdministratorAccess

   policy are required only during installation.

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

   Example output

   system:admin