Chapter 6. Installing a cluster on Google Cloud 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 gcp as the platform to target.
      3. If you have not configured the service account key for your Google Cloud account on your computer, you must obtain it from Google Cloud and paste the contents of the file or enter the absolute path to the file.
      4. Select the project ID to provision the cluster in. The default value is specified by the service account that you configured.
      5. Select the region to deploy the cluster to.
      6. Select the base domain to deploy the cluster to. The base domain corresponds to the public DNS zone that you created for your cluster.
      7. 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 network and subnets for the VPC to install the cluster in under the parent

      platform.gcp

      field:

      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.

   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. Remove any existing Google Cloud credentials that do not use the service account key for the Google Cloud account that you configured for your cluster and that are stored in the following locations:

   • The

     GOOGLE_CREDENTIALS

     ,

     GOOGLE_CLOUD_KEYFILE_JSON

     , or

     GCLOUD_KEYFILE_JSON

     environment variables
   • The

     ~/.gcp/osServiceAccount.json

     file
   • The

     gcloud cli

     default credentials

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

3. Optional: You can reduce the number of permissions for the service account that you used to install the cluster.

   • If you assigned the

     Owner

     role to your service account, you can remove that role and replace it with the

     Viewer

     role.
   • If you included the

     Service Account Key Admin

     role, you can remove it.

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