Chapter 2. Create a cluster on Google Cloud with Workload Identity Federation authentication

Procedure

1. Log in to OpenShift Cluster Manager and click Create cluster on the OpenShift Dedicated card.

2. Under Billing model, configure the subscription type and infrastructure type.

   1. Select a subscription type. For information about OpenShift Dedicated subscription options, see Cluster subscriptions and registration in the OpenShift Cluster Manager documentation.
   2. Select the Customer cloud subscription infrastructure type.
   3. Click Next.
3. Select Run on Google Cloud.

4. Select Workload Identity Federation as the Authentication type.

   Note

   Workload Identity Federation (WIF) is Google Cloud’s recommended method of authentication for OpenShift Dedicated installation. It greatly improves a cluster’s resilience by using short-lived, least-privilege credentials and eliminates the need for static service account keys.

   1. Read and complete all the required prerequisites.
   2. Click the checkbox indicating that you have read and completed all the required prerequisites.
5. Select a configured WIF configuration from the WIF configuration drop-down list.
6. Click Next.

7. On the Details page, provide a name for your cluster and specify the cluster details:

   1. In the Cluster name field, enter a name for your cluster.

   2. Optional: Cluster creation generates a domain prefix as a subdomain for your provisioned cluster on openshiftapps.com. If the cluster name is less than or equal to 15 characters, that name is used for the domain prefix. If the cluster name is longer than 15 characters, the domain prefix is randomly generated as a 15-character string.

      To customize the subdomain prefix, select the Create custom domain prefix checkbox, and enter your domain prefix name in the Domain prefix field. The domain prefix cannot be longer than 15 characters, must be unique within your organization, and cannot be changed after cluster creation. If you plan to install the cluster into a Shared VPC and select a managed DNS zone in a later step, the DNS Zone list is filtered to show only zones that begin with this domain prefix; ensure the prefix matches the managed DNS zones you have created or intend to use.

   3. Select a cluster version from the Version drop-down menu.

      Note

      Workload Identity Federation (WIF) is only supported on OpenShift Dedicated version 4.17 and later.

   4. Select a channel from the Channel drop-down menu.

      Note

      Channel options include Stable-4.y (default option), Fast-4.y, and EUS-4.y. For more information about the Stable, Fast, and EUS channel options, see Understanding update channels and releases.

   5. Select a cloud provider region from the Region drop-down menu.
   6. Select a Single zone or Multi-zone configuration.

   7. Optional: Select Enable Secure Boot support for Shielded VMs to use Shielded VMs when installing your cluster. Once you create your cluster, the Enable Secure Boot support for Shielded VMs setting cannot be changed. For more information, see Shielded VMs.

      Important

      To successfully create a cluster, you must select Enable Secure Boot support for Shielded VMs if your organization has the policy constraint constraints/compute.requireShieldedVm enabled. For more information regarding Google Cloud organizational policy constraints, see Organization policy constraints.

      Important

      Enable Secure Boot support for Shielded VMs is not supported for OpenShift Dedicated on Google Cloud clusters created using bare-metal instance types. For more information, see Limitations in the Google Cloud documentation.

   8. Leave Enable user workload monitoring selected to monitor your own projects in isolation from Red Hat Site Reliability Engineer (SRE) platform metrics. This option is enabled by default.

8. Optional: Expand Advanced Encryption to make changes to encryption settings.

   1. Select Use custom KMS keys to use custom KMS keys. If you prefer not to use custom KMS keys, leave the default setting Use default KMS Keys.

   2. With Use Custom KMS keys selected:

      1. Select a key ring location from the Key ring location drop-down menu.
      2. Select a key ring from the Key ring drop-down menu.
      3. Select a key name from the Key name drop-down menu.
      4. Provide the KMS Service Account.

   3. Optional: Select Enable FIPS cryptography if you require your cluster to be FIPS validated.

      Note

      If Enable FIPS cryptography is selected, Enable additional etcd encryption is enabled by default and cannot be disabled. You can select Enable additional etcd encryption without selecting Enable FIPS cryptography.

   4. Optional: Select Enable additional etcd encryption if you require etcd key value encryption. With this option, the etcd key values are encrypted, but not the keys. This option is in addition to the control plane storage encryption that encrypts the etcd volumes in OpenShift Dedicated clusters by default.

      Note

      By enabling etcd encryption for the key values in etcd, you incur a performance overhead of approximately 20%. The overhead is a result of introducing this second layer of encryption, in addition to the default control plane storage encryption that encrypts the etcd volumes. Consider enabling etcd encryption only if you specifically require it for your use case.

9. Click Next.
10. On the Machine pool page, select a Compute node instance type and a Compute node count. The number and types of nodes that are available depend on your OpenShift Dedicated subscription. If you are using multiple availability zones, the compute node count is per zone.

11. Optional: Expand Add node labels to add labels to your nodes. Click Add additional label to add more node labels.

    Important

    This step refers to labels within Kubernetes, not Google Cloud. For more information regarding Kubernetes labels, see Labels and Selectors.

12. Click Next.
13. In the Cluster privacy dialog, select Public or Private to use either public or private API endpoints and application routes for your cluster. If you select Private, Use Private Service Connect is selected by default, and cannot be disabled. Private Service Connect (PSC) is Google Cloud’s security-enhanced networking feature.

14. Optional: To install the cluster in an existing Google Cloud Virtual Private Cloud (VPC):

    1. Select Install into an existing VPC.

       Important

       Private Service Connect (PSC) is supported only with Install into an existing VPC.

    2. If you are installing into an existing VPC and you want to enable an HTTP or HTTPS proxy for your cluster, select Configure a cluster-wide proxy.

15. Accept the default application ingress settings, or to create your own custom settings, select Custom Settings. All of the custom settings are optional.

    1. In Route selector, enter a comma-separated list of key=value pairs to limit which routes this ingress exposes. Leave the field empty if all routes should remain eligible based on your other choices.
    2. In Excluded namespaces, enter a comma-separated list of namespace names whose routes must not use this ingress.

    3. In Exclude namespace selectors, specify one or more label selectors. For each selector, provide a label key and a comma-separated list of label values. The default Ingress Controller does not apply to namespaces whose labels satisfy any of the configured selectors.

       Important

       Do not include spaces around commas, for example, use finance,HR,legal, and not finance, HR, legal.

    4. Set Namespace ownership policy for route admission when namespaces share hostnames, for example, select Strict for restrictive admission.

    5. Set Wildcard policy to allow or disallow wildcard patterns in route hostnames, for example, select Disallowed to block wildcard host routes.

       For more information about custom application ingress settings, click on the information icon provided for each setting.

16. Click Next.

17. Optional: To install the cluster into a Google Cloud Shared VPC, follow these steps.

    Note

    Installing a new OpenShift Dedicated cluster into a VPC that was automatically created by the installer for a different cluster is not supported.

    1. Select Install into Google Cloud Shared VPC.

    2. Specify the Host project ID. If the specified host project ID is incorrect, cluster creation fails.

       Note

       In a typical Shared VPC deployment, the following Google Cloud roles are required on the project hosting the VPC:

       • roles/compute.networkAdmin
       • roles/compute.securityAdmin
       • roles/dns.admin

       You can significantly reduce these permissions by using a custom role with minimal permissions. For more information, see Configure reduced permissions for a Shared VPC host project on Google Cloud in the Additional resources section.

       If you use a managed DNS zone (by selecting a zone from the DNS Zone list), the roles/dns.admin role is not required on the host project.

    3. Optional. To use a pre-created DNS zone and reduce host project permissions, complete the following actions:

       1. View the provided CLI command instructions to create a zone if you have not already done so. For more information about creating a DNS zone using the ocm CLI, see Creating a managed DNS zone in the Additional resources section.
       2. Click the Refresh button to update the list of available zones.

       3. Select your preferred zone from the DNS Zone list. The list displays the zone ID alongside the Google Cloud project and managed zone ID for easy identification.

          Note

          A custom domain prefix must be specified on a previous step on the Details page before zones appear in the DNS Zone list. The DNS Zone list is filtered to show only zones that begin with the domain prefix you specified. The list may be empty if no matching DNS zones exist, or if the domain prefix was entered incorrectly. If the list is empty, verify your domain prefix and ensure you have created a managed DNS zone with a matching prefix.

          If no zone is selected, the installer will attempt to create one automatically, which requires higher-level permissions in the host project.

18. If you opted to install the cluster in an existing Google Cloud VPC, provide your VPC subnet settings and select Next. You must ensure that your VPC is configured to allow outbound internet access to the domains required for the OpenShift Dedicated service. This outbound access is required for the OpenShift Dedicated service to communicate with Red Hat’s management plane and SRE tooling via secure and encrypted endpoints over the public internet.

    Note

    If you are installing a cluster into a Shared VPC, the VPC name and subnets are shared from the host project.

19. Click Next.

20. If you opted to configure a cluster-wide proxy, provide your proxy configuration details on the Cluster-wide proxy page:

    1. Enter a value in at least one of the following fields:

       • Specify a valid HTTP proxy URL.
       • Specify a valid HTTPS proxy URL.
       • In the Additional trust bundle field, provide a PEM encoded X.509 certificate bundle. The bundle is added to the trusted certificate store for the cluster nodes. An additional trust bundle file is required if you use a TLS-inspecting proxy unless the identity certificate for the proxy is signed by an authority from the Red Hat Enterprise Linux CoreOS (RHCOS) trust bundle. This requirement applies regardless of whether the proxy is transparent or requires explicit configuration using the http-proxy and https-proxy arguments.

    2. Click Next.

       For more information about configuring a proxy with OpenShift Dedicated, see Configuring a cluster-wide proxy.

21. Accept the default application ingress settings, or to create your own custom settings, select Custom Settings. All of the custom settings are optional.

    1. In Route selector, enter a comma-separated list of key=value pairs to limit which routes this ingress exposes. Leave the field empty if all routes should remain eligible based on your other choices.
    2. In Excluded namespaces, enter a comma-separated list of namespace names whose routes must not use this ingress.

    3. In Exclude namespace selectors, specify one or more label selectors. For each selector, provide a label key and a comma-separated list of label values. The default Ingress Controller does not apply to namespaces whose labels satisfy any of the configured selectors.

       Important

       Do not include spaces around commas, for example, use finance,HR,legal, and not finance, HR, legal.

    4. Set Namespace ownership policy for route admission when namespaces share hostnames, for example, select Strict for restrictive admission.

    5. Set Wildcard policy to allow or disallow wildcard patterns in route hostnames, for example, select Disallowed to block wildcard host routes.

       For more information about custom application ingress settings, click the information icon provided for each setting.

22. In the CIDR ranges dialog, configure custom classless inter-domain routing (CIDR) ranges or use the defaults that are provided.

    Important

    CIDR configurations cannot be changed later. Confirm your selections with your network administrator before proceeding.

    If the cluster privacy is set to Private, you cannot access your cluster until you configure private connections in your cloud provider.

23. On the Cluster update strategy page, configure your update preferences:

    1. Choose a cluster update method:

       • Select Individual updates if you want to schedule each update individually. This is the default option.

       • Select Recurring updates to update your cluster on your preferred day and start time, when updates are available.

         Note

         You can review the end-of-life dates in the update lifecycle documentation for OpenShift Dedicated. For more information, see OpenShift Dedicated update life cycle.

    2. Provide administrator approval based on your cluster update method:

       • Individual updates: If you select an update version that requires approval, provide an administrator’s acknowledgment and click Approve and continue.
       • Recurring updates: If you selected recurring updates for your cluster, provide an administrator’s acknowledgment and click Approve and continue. OpenShift Cluster Manager does not start scheduled y-stream updates for minor versions without receiving an administrator’s acknowledgment.
    3. If you opted for recurring updates, select a preferred day of the week and upgrade start time in UTC from the drop-down menus.
    4. Optional: You can set a grace period for Node draining during cluster upgrades. A 1 hour grace period is set by default.

    5. Click Next.

       Note

       If critical security concerns significantly impact the security or stability of a cluster, Red Hat Site Reliability Engineering (SRE) might schedule automatic updates to the latest z-stream version that is not impacted. The updates are applied within 48 hours after customer notifications are provided. For a description of the critical impact security rating, see Understanding Red Hat security ratings.

24. Review the summary of your selections and click Create cluster to start the cluster installation. The installation takes approximately 30-40 minutes to complete.
25. Optional: On the Overview tab, you can enable the delete protection feature by selecting Enable, which is located directly under Delete Protection: Disabled. This will prevent your cluster from being deleted. To disable delete protection, select Disable. By default, clusters are created with the delete protection feature disabled.

Procedure

1. Based on your mode preference, run one of the following commands to create an OpenShift Dedicated cluster on Google Cloud with WIF configuration:

   In interactive mode, cluster attributes are displayed automatically as prompts during the creation of the cluster. Enter the values for those prompts based on specified requirements in the fields provided.

   In non-interactive mode, specify the values for specific parameters within the command.

   • Create a cluster in interactive mode by running the following command:

     $ ocm create cluster --interactive

     where:

     --interactive

     Specifies that the cluster is created in interactive mode. This mode prompts you to enter the required configuration options during cluster creation. If you do not include this parameter, the cluster is created in non-interactive mode by default.

     • Create a cluster in noninteractive mode by running the following command. The following example is made up of optional and required parameters and might differ from your noninteractive mode command. Parameters not identified as optional are required. For additional details about these and other parameters, run the ocm create cluster --help flag command in your terminal window.

       $ ocm create cluster <cluster_name> \
       --provider=gcp \
       --ccs=true \
       --wif-config <wif_name> \
       --dns-zone-id <dns_zone_id> \
       --region <gcp_region> \
       --subscription-type=marketplace-gcp \
       --marketplace-gcp-terms=true \
       --version <version> \
       --multi-az=true  \
       --enable-autoscaling=true \
       --min-replicas=3 \
       --max-replicas=6 \
       --secure-boot-for-shielded-vms=true
       --channel <channel_name>

       where:

     <cluster_name>

     Specifies the name of the cluster. Replace <cluster_name> with a name for your cluster.

     --provider=gcp

     Specifies the cloud provider for the cluster.

     --ccs=true

     Specifies that the cluster is a Customer Cloud Subscription (CCS) cluster.

     --wif-config <wif_name>

     Specifies the name of the WIF configuration to assign to the cluster. Replace <wif_name> with the name of your WIF configuration.

     --dns-zone-id <dns_zone_id>

     Optional. Specifies the DNS zone ID to use for the cluster. Replace <dns_zone_id> with the ID of your DNS zone. For more information about this parameter, see Creating a managed DNS zone in the Additional resources section.

     --region <gcp_region>

     Specifies the Google Cloud region where the new cluster will be deployed. Replace <gcp_region> with the required Google Cloud region.

     --subscription-type=marketplace-gcp

     Optional. Specifies the subscription billing model for the cluster.

     --marketplace-gcp-terms=true

     Confirms that you have accepted the Google Cloud Marketplace terms and agreements for the OpenShift Dedicated product listing. This parameter is required if you provided a value of marketplace-gcp for the subscription-type parameter.

     --version <version>

     Specifies the required OpenShift Dedicated version. This parameter is optional. However, if an OpenShift Dedicated version is specified, the version must also be supported by the assigned WIF configuration. If a version is specified that is not supported by the assigned WIF configuration, cluster creation will fail. If this occurs, update the assigned WIF configuration to the required version or create a new WIF configuration with the required version. If you do not specify a version, the cluster is created with the default version for the assigned WIF configuration.

     For more information about supported versions for WIF configurations, see "Create a Workload Identity Federation configuration".

     --multi-az=true

     Specifies that the cluster is deployed to multiple data centers. This parameter is optional.

     --enable-autoscaling=true

     Enables autoscaling of compute nodes. This parameter is optional.

     --min-replicas=3

     Specifies the minimum number of compute nodes. This parameter is optional.

     --max-replicas=6

     Specifies the maximum number of compute nodes. This parameter is optional.

     --secure-boot-for-shielded-vms=true

     Enables Secure Boot, which allows the use of Shielded VMs in the Google Cloud. This parameter is optional.

     --channel <channel_name>

     Specifies the name of the channel you want to assign the cluster to. Channel options include stable-4.y, fast-4.y, and eus-4.y. Replace <channel_name> with the required channel. This parameter is optional.

Procedure

1. To check the version of your ocm, run the following command:

   $ ocm version

2. Optional: If your ocm version is not the latest available, download and install the latest version from the Downloads page on OpenShift Cluster Manager.

3. Update a wif-config to a specific OpenShift Dedicated version by running the following command:

   $ ocm gcp update wif-config <wif_name> \
     --version <version> \
     --federated-project <gcp_project_id>

   where:

   <wif_name>

   The name of the WIF configuration you want to update.

   <version>

   Optional: The OpenShift Dedicated y-stream version you plan to update the cluster to. If you do not specify a version, the wif-config is updated to support the latest OpenShift Dedicated y-stream version and the last three OpenShift Dedicated supported y-stream versions (beginning with version 4.17).

   --federated-project <gcp_project_id>

   Optional: A flag to specify a new dedicated project where the workload identity pools and providers will be created and managed. If this flag is not included, the workload identity pools and providers will remain in the project associated with the cluster.

Procedure

1. Get the name and ID of your active WIF configurations by running the following command:

   $ ocm gcp list wif-configs

2. Determine if the WIF configuration you want to verify is configured correctly by running the following command, replacing <wif_config_name> and <wif_config_id> with the name and ID of your WIF configuration, respectively:

   $ ocm gcp verify wif-config <wif_config_name>|<wif_config_id>

   If a misconfiguration is found, the output provides details about the misconfiguration and recommends that you update the WIF configuration.

   Example output

   Error: verification failed with error: missing role 'compute.storageAdmin'.
   Running 'ocm gcp update wif-config' may fix errors related to cloud resource misconfiguration.
   exit status 1.