Using manual mode with GCP Workload Identity

Manual mode with GCP Workload Identity is supported for Google Cloud Platform (GCP).

This credentials strategy is supported for only new OKD clusters and must be configured during installation. You cannot reconfigure an existing cluster that uses a different credentials strategy to use this feature.

In manual mode with GCP Workload Identity, the individual OKD cluster components can impersonate IAM service accounts using short-term, limited-privilege credentials.

Requests for new and refreshed credentials are automated by using an appropriately configured OpenID Connect (OIDC) identity provider, combined with IAM service accounts. OKD signs service account tokens that are trusted by GCP, and can be projected into a pod and used for authentication. Tokens are refreshed after one hour by default.

Using manual mode with GCP Workload Identity changes the content of the GCP credentials that are provided to individual OKD components.

GCP secret format

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   namespace: <target_namespace> (1)
  5.   name: <target_secret_name> (2)
  6. data:
  7.   service_account.json: <service_account> (3)
1The namespace for the component.
2The name of the component secret.
3The Base64 encoded service account.

Content of the Base64 encoded service_account.json file using long-lived credentials

  1. {
  2.    "type": "service_account", (1)
  3.    "project_id": "<project_id>",
  4.    "private_key_id": "<private_key_id>",
  5.    "private_key": "<private_key>", (2)
  6.    "client_email": "<client_email_address>",
  7.    "client_id": "<client_id>",
  8.    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  9.    "token_uri": "https://oauth2.googleapis.com/token",
  10.    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  11.    "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/<client_email_address>"
  12. }
1The credential type is service_account.
2The private RSA key that is used to authenticate to GCP. This key must be kept secure and is not rotated.

Content of the Base64 encoded service_account.json file using GCP Workload Identity

  1. {
  2.    "type": "external_account", (1)
  3.    "audience": "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/test-pool/providers/test-provider", (2)
  4.    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  5.    "token_url": "https://sts.googleapis.com/v1/token",
  6.    "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/<client_email_address>:generateAccessToken", (3)
  7.    "credential_source": {
  8.       "file": "<path_to_token>", (4)
  9.       "format": {
  10.          "type": "text"
  11.       }
  12.    }
  13. }
1The credential type is external_account.
2The target audience is the GCP Workload Identity provider.
3The resource URL of the service account that can be impersonated with these credentials.
4The path to the service account token inside the pod. By convention, this is /var/run/secrets/openshift/serviceaccount/token for OKD components.

Installing an OKD cluster configured for manual mode with GCP Workload Identity

To install a cluster that is configured to use the Cloud Credential Operator (CCO) in manual mode with GCP Workload Identity:

  1. Configure the Cloud Credential Operator utility.

  2. Create the required GCP resources.

  3. Run the OKD installer.

  4. Verify that the cluster is using short-lived credentials.

Because the cluster is operating in manual mode when using GCP Workload Identity, it is not able to create new credentials for components with the permissions that they require. When upgrading to a different minor version of OKD, there are often new GCP permission requirements. Before upgrading a cluster that is using GCP Workload Identity, the cluster administrator must manually ensure that the GCP permissions are sufficient for existing components and available to any new components.

Additional resources

Configuring the Cloud Credential Operator utility

To create and manage cloud credentials from outside of the cluster when the Cloud Credential Operator (CCO) is operating in manual mode, extract and prepare the CCO utility (ccoctl) binary.

The ccoctl utility is a Linux binary that must run in a Linux environment.

Prerequisites

  • You have access to an OKD account with cluster administrator access.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Obtain the OKD release image by running the following command:

    1. $ RELEASE_IMAGE=$(./openshift-install version | awk '/release image/ {print $3}')

  2. Obtain the CCO container image from the OKD release image by running the following command:

    1. $ CCO_IMAGE=$(oc adm release info --image-for='cloud-credential-operator' $RELEASE_IMAGE -a ~/.pull-secret)

    Ensure that the architecture of the $RELEASE_IMAGE matches the architecture of the environment in which you will use the ccoctl tool.

  3. Extract the ccoctl binary from the CCO container image within the OKD release image by running the following command:

    1. $ oc image extract $CCO_IMAGE --file="/usr/bin/ccoctl" -a ~/.pull-secret

  4. Change the permissions to make ccoctl executable by running the following command:

    1. $ chmod 775 ccoctl

Verification

  • To verify that ccoctl is ready to use, display the help file by running the following command:

    1. $ ccoctl --help

    Output of ccoctl --help:

    1. OpenShift credentials provisioning tool
    3. Usage:
    4.   ccoctl [command]
    6. Available Commands:
    7.   alibabacloud Manage credentials objects for alibaba cloud
    8.   aws          Manage credentials objects for AWS cloud
    9.   gcp          Manage credentials objects for Google cloud
    10.   help         Help about any command
    11.   ibmcloud     Manage credentials objects for IBM Cloud
    12.   nutanix      Manage credentials objects for Nutanix
    14. Flags:
    15.   -h, --help   help for ccoctl
    17. Use "ccoctl [command] --help" for more information about a command.

Creating GCP resources with the Cloud Credential Operator utility

You can use the ccoctl gcp create-all command to automate the creation of GCP resources.

By default, ccoctl creates objects in the directory in which the commands are run. To create the objects in a different directory, use the —output-dir flag. This procedure uses <path_to_ccoctl_output_dir> to refer to this directory.

Prerequisites

You must have:

  • Extracted and prepared the ccoctl binary.

Procedure

  1. Extract the list of CredentialsRequest objects from the OKD release image by running the following command:

    1. $ oc adm release extract \
    2. --credentials-requests \
    3. --cloud=gcp \
    4. --to=<path_to_directory_with_list_of_credentials_requests>/credrequests \ (1)
    5. quay.io/<path_to>/ocp-release:<version>
    1credrequests is the directory where the list of CredentialsRequest objects is stored. This command creates the directory if it does not exist.

    This command can take a few moments to run.

  2. If your cluster uses cluster capabilities to disable one or more optional components, delete the CredentialsRequest custom resources for any disabled components.

    Example credrequests directory contents for OKD 4.12 on GCP

    1. 0000_26_cloud-controller-manager-operator_16_credentialsrequest-gcp.yaml (1)
    2. 0000_30_machine-api-operator_00_credentials-request.yaml (2)
    3. 0000_50_cloud-credential-operator_05-gcp-ro-credentialsrequest.yaml (3)
    4. 0000_50_cluster-image-registry-operator_01-registry-credentials-request-gcs.yaml (4)
    5. 0000_50_cluster-ingress-operator_00-ingress-credentials-request.yaml (5)
    6. 0000_50_cluster-network-operator_02-cncc-credentials.yaml (6)
    7. 0000_50_cluster-storage-operator_03_credentials_request_gcp.yaml (7)
    1The Cloud Controller Manager Operator CR is required.
    2The Machine API Operator CR is required.
    3The Cloud Credential Operator CR is required.
    4The Image Registry Operator CR is required.
    5The Ingress Operator CR is required.
    6The Network Operator CR is required.
    7The Storage Operator CR is an optional component and might be disabled in your cluster.

  3. Use the ccoctl tool to process all CredentialsRequest objects in the credrequests directory:

    1. $ ccoctl gcp create-all \
    2. --name=<name> \
    3. --region=<gcp_region> \
    4. --project=<gcp_project_id> \
    5. --credentials-requests-dir=<path_to_directory_with_list_of_credentials_requests>/credrequests

    where:

    • <name> is the user-defined name for all created GCP resources used for tracking.

    • <gcp_region> is the GCP region in which cloud resources will be created.

    • <gcp_project_id> is the GCP project ID in which cloud resources will be created.

    • <path_to_directory_with_list_of_credentials_requests>/credrequests is the directory containing the files of CredentialsRequest manifests to create GCP service accounts.

    If your cluster uses Technology Preview features that are enabled by the TechPreviewNoUpgrade feature set, you must include the —enable-tech-preview parameter.

Verification

  • To verify that the OKD secrets are created, list the files in the <path_to_ccoctl_output_dir>/manifests directory:

    1. $ ls <path_to_ccoctl_output_dir>/manifests

You can verify that the IAM service accounts are created by querying GCP. For more information, refer to GCP documentation on listing IAM service accounts.

Running the installer

Prerequisites

  • Configure an account with the cloud platform that hosts your cluster.

  • Obtain the OKD release image.

Procedure

  1. Change to the directory that contains the installation program and create the install-config.yaml file:

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

    where <installation_directory> is the directory in which the installation program creates files.

  2. Edit the install-config.yaml configuration file so that it contains the credentialsMode parameter set to Manual.

    Example install-config.yaml configuration file

    1. apiVersion: v1
    2. baseDomain: cluster1.example.com
    3. credentialsMode: Manual (1)
    4. compute:
    5. - architecture: amd64
    6.   hyperthreading: Enabled
    1This line is added to set the credentialsMode parameter to Manual.

  3. Create the required OKD installation manifests:

    1. $ openshift-install create manifests

  4. Copy the manifests that ccoctl generated to the manifests directory that the installation program created:

    1. $ cp /<path_to_ccoctl_output_dir>/manifests/* ./manifests/

  5. Copy the private key that the ccoctl generated in the tls directory to the installation directory:

    1. $ cp -a /<path_to_ccoctl_output_dir>/tls .

  6. Run the OKD installer:

    1. $ ./openshift-install create cluster

Verifying the installation

  1. Connect to the OKD cluster.

  2. Verify that the cluster does not have root credentials:

    1. $ oc get secrets -n kube-system gcp-credentials

    The output should look similar to:

    1. Error from server (NotFound): secrets "gcp-credentials" not found

  3. Verify that the components are assuming the service accounts that are specified in the secret manifests, instead of using credentials that are created by the CCO:

    Example command with the Image Registry Operator

    1. $ oc get secrets -n openshift-image-registry installer-cloud-credentials -o json | jq -r '.data."service_account.json"' | base64 -d

    The output should show the role and web identity token that are used by the component and look similar to:

    Example output with the Image Registry Operator

    1. {
    2.    "type": "external_account", (1)
    3.    "audience": "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/test-pool/providers/test-provider",
    4.    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    5.    "token_url": "https://sts.googleapis.com/v1/token",
    6.    "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/<client-email-address>:generateAccessToken", (2)
    7.    "credential_source": {
    8.       "file": "/var/run/secrets/openshift/serviceaccount/token",
    9.       "format": {
    10.          "type": "text"
    11.       }
    12.    }
    13. }
    1The credential type is external_account.
    2The resource URL of the service account used by the Image Registry Operator.

Additional resources