Chapter 9. Installing a cluster on Google Cloud Dedicated

Procedure

1. Confirm the following environment details with your GCD operating partner, such as Thales:

   • The region identifier for your GCD deployment, such as u-germany-northeast1.
   • The universe domain for your region, such as apis-berlin-build0.goog.
   • Your domain-scoped project ID, such as eu0:my-project.
   • Network connectivity requirements for your sovereign cloud region.

2. Obtain the GCD credential configuration file for your service account. The credential file must include the universe_domain field that corresponds to your GCD region.

   Verify that your credential file contains the universe_domain field by running the following command:

   $ cat <path_to_credentials>/credentials.json | grep universe_domain

   Example output

     "universe_domain": "apis-berlin-build0.goog"

3. Set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to the universe domain for your GCD region by running the following command:

   $ export GOOGLE_CLOUD_UNIVERSE_DOMAIN=<universe_domain>

   where:

   <universe_domain>

   Specifies the universe domain for your GCD region. For the Berlin region, use apis-berlin-build0.goog.

4. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your GCD credential file by running the following command:

   $ export GOOGLE_APPLICATION_CREDENTIALS=<path_to_credentials>/credentials.json

   where:

   <path_to_credentials>

   Specifies the path to the directory that contains your GCD credential file.

5. Verify that the required APIs are enabled in your GCD project:

   • Compute Engine API (compute.googleapis.com)
   • Cloud DNS API (dns.googleapis.com)
   • Cloud Storage API (storage.googleapis.com)
   • IAM API (iam.googleapis.com)
   • Service Usage API (serviceusage.googleapis.com)
   • Cloud Resource Manager API (cloudresourcemanager.googleapis.com)
   Note

   GCD uses the same API service names as public Google Cloud for enabling and disabling APIs. The service endpoints, however, use the GCD-specific domain.

6. Create a VPC network if one does not already exist by running the following command. GCD does not create a default VPC network for new projects.

   $ gcloud compute networks create <network_name> \
       --subnet-mode=custom \
       --project=<gcd_project_id>

   where:

   <network_name>

   Specifies the name of the VPC network to create.

   <gcd_project_id>

   Specifies your domain-scoped GCD project ID, such as eu0:my-project.

7. Configure a private DNS zone for your cluster’s base domain by running the following command. GCD supports only private DNS zones.

   $ gcloud dns managed-zones create <zone_name> \
       --dns-name=<base_domain> \
       --description="Private DNS zone for OpenShift" \
       --visibility=private \
       --networks=<network_name> \
       --project=<gcd_project_id>

   where:

   <zone_name>

   Specifies a name for the DNS zone.

   <base_domain>

   Specifies the base domain for your cluster.

   <network_name>

   Specifies the name of the VPC network you created.

   <gcd_project_id>

   Specifies your domain-scoped GCD project ID, such as eu0:my-project.

8. Prepare a custom Red Hat Enterprise Linux CoreOS (RHCOS) image for your GCD project. The RHCOS image is not pre-published in GCD regions. You must upload your own image:

   1. Download the RHCOS image for your OpenShift Container Platform version from the RHCOS image mirror.

      Download the gcp.x86_64.tar.gz file for your version.

   2. Create a Cloud Storage bucket in your GCD project to store the image by running the following command:

      $ gcloud storage buckets create gs://<bucket_name> \
          --location=<gcd_region> \
          --project=<gcd_project_id>

      where:

      <bucket_name>

      Specifies a unique name for the storage bucket.

      <gcd_region>

      Specifies your GCD region name, such as u-germany-northeast1.

      <gcd_project_id>

      Specifies your domain-scoped GCD project ID, such as eu0:my-project.

      Note

      Cloud Storage in GCD is limited to single-region buckets. The bucket location must match your cluster region.

   3. Upload the RHCOS image to your Cloud Storage bucket by running the following command:

      $ gcloud storage cp rhcos-<version>-gcp.x86_64.tar.gz \
          gs://<bucket_name>/ \
          --project=<gcd_project_id>

      Replace <version> with the version you downloaded.

   4. Import the RHCOS image from Cloud Storage to create a Compute Engine image by running the following command:

      $ gcloud compute images create <image_name> \
          --source-uri=gs://<bucket_name>/rhcos-<version>-gcp.x86_64.tar.gz \
          --guest-os-features=GVNIC,UEFI_COMPATIBLE,VIRTIO_SCSI_MULTIQUEUE \
          --project=<gcd_project_id>

      where:

      <image_name>

      Specifies a name for the RHCOS image.

      --source-uri

      Specifies the Cloud Storage URI (gs://) where the image file was uploaded in the previous step. The gs:// URI must point to the Cloud Storage bucket in your GCD project.

      --guest-os-features

      Specifies the guest operating system features required for RHCOS images. You must enable the GVNIC, UEFI_COMPATIBLE, and VIRTIO_SCSI_MULTIQUEUE features for proper network, UEFI boot support, and disk I/O performance.

      <bucket_name>

      Specifies the name of the Cloud Storage bucket you created.

      <version>

      Specifies the RHCOS version you downloaded.

      <gcd_project_id>

      Specifies your domain-scoped GCD project ID, such as eu0:my-project.

   5. Note the image name and project ID. You must specify these values in the platform.gcp.defaultMachinePlatform.osImage fields of the install-config.yaml file.

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>

   Specifies 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>

   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. Go to the Cluster Type page on the Red Hat Hybrid Cloud Console. If you have a Red Hat account, log in with your credentials. If you do not, create an account.

   Tip

   You can also download the binaries for a specific OpenShift Container Platform release.

2. Select your infrastructure provider from the Run it yourself section of the page.
3. Select your host operating system and architecture from the dropdown menus under OpenShift Installer and click Download Installer.

4. Place the downloaded file in the directory where you want to 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 the installation program and the files that the installation program creates after you finish installing the cluster. Both of the files are required to delete the cluster.
   • Deleting the files created by the installation program does not remove your cluster, even if the cluster failed during installation. To remove your cluster, complete the OpenShift Container Platform uninstallation procedures for your specific cloud provider.

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

   $ tar -xvf openshift-install-linux.tar.gz

6. Download your installation pull secret from Red Hat OpenShift Cluster Manager. 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.

   Tip

   Alternatively, you can retrieve the installation program from the Red Hat Customer Portal, where you can specify a version of the installation program to download. However, you must have an active subscription to access this page.

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

2. Customize the provided sample install-config.yaml file template and save the file 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 many clusters.

   Important

   Back up the install-config.yaml file now, because the installation process consumes the file in the next step.

Procedure

1. Create an install-config.yaml file. You can generate a template file by running the following command or manually create the file:

   $ ./openshift-install create install-config --dir <installation_directory>

   Replace <installation_directory> with the name of the directory that contains the installation files for your cluster.

   Note

   You cannot select a GCD sovereign cloud region by using the guided terminal prompts. You must manually edit the install-config.yaml file to configure GCD-specific parameters.

2. Edit the install-config.yaml file to configure it for your GCD environment:

   Note

   The installation program automatically detects the GCD sovereign cloud environment based on the region and the domain-scoped project ID in your credential file. You do not need to manually configure API endpoints.

   1. Specify the GCD region:

      platform:
        gcp:
          region: <gcd_region_name>

   2. Configure the cluster for private networking:

      publish: Internal

      where:

      publish

      Specifies the cluster publishing strategy. For GCD, you must use Internal. Public clusters are not supported.

   3. Optional: If you need to provide a custom Red Hat Enterprise Linux CoreOS (RHCOS) image, add the compute platform image field:

      platform:
        gcp:
          defaultMachinePlatform:
            osImage:
              project: <project_id>
              name: <image_name>

      where:

      platform.gcp.defaultMachinePlatform.osImage.project

      Specifies the Google Cloud project ID where your custom RHCOS image is stored.

      platform.gcp.defaultMachinePlatform.osImage.name

      Specifies the name of your custom RHCOS image.

      Important

      You must specify a custom RHCOS image. The RHCOS image is not pre-published in GCD regions. If you do not provide the osImage.name and osImage.project fields, the installation fails.

   4. Optional: Configure Customer-Managed Encryption Keys (CMEK) if required for regulatory compliance:

      Important

      When you use CMEK with GCD, you must use regional keys. Global keys are not supported.

      platform:
        gcp:
          defaultMachinePlatform:
            osDisk:
              encryptionKey:
                kmsKey:
                  name: <regional_key_name>
                  keyRing: <key_ring_name>
                  location: <region_name>
                  projectID: <project_id>

      where:

      platform.gcp.defaultMachinePlatform.osDisk.encryptionKey.kmsKey.name

      Specifies a regional KMS key, not a global key.

   5. Configure storage to use hyperdisk-balanced storage:

      platform:
        gcp:
          defaultMachinePlatform:
            osDisk:
              diskType: hyperdisk-balanced

      where:

      platform.gcp.defaultMachinePlatform.osDisk.diskType

      Specifies the disk type for machine storage. GCD supports only hyperdisk-balanced storage. Other disk types are not available.

3. Back up the install-config.yaml file by running the following command:

   $ cp <installation_directory>/install-config.yaml <installation_directory>/install-config.yaml.backup

   Important

   The install-config.yaml file is consumed during the installation process. If you want to reuse the file, you must back it up.

4. Generate the Kubernetes manifests for the cluster by running the following command:

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

5. Deploy the OpenShift Container Platform cluster by running the following command:

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

   Note

   If you provided correct configuration values, the cluster creation process should complete successfully. However, the installation program might fail if it cannot validate your custom API endpoints or if there are connectivity issues with your GCD environment.

   When the cluster deployment is complete, the installation program displays information about accessing your cluster, including a link to the web console and credentials for the kubeadmin user.

   To verify that the cluster Operators are running, set the KUBECONFIG environment variable and check the cluster Operator status by running the following commands:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig

   $ oc get clusteroperators

   Verify that all cluster Operators show AVAILABLE=True, PROGRESSING=False, and DEGRADED=False.

Procedure

1. Export the kubeadmin credentials by running the following command:

   $ export KUBECONFIG=<installation_directory>/auth/kubeconfig

   where:

   <installation_directory>

   Specifies the path to the directory that stores the installation files.

2. Verify you can run oc commands successfully using the exported configuration by running the following command:

   $ oc whoami

   Example output

   system:admin