GCP Workload Identity

Author: jeana-redhat

_topic_maps/_topic_map.yml

@@ -952,8 +952,10 @@ Topics:
     File: cco-mode-passthrough
   - Name: Using manual mode
     File: cco-mode-manual
-  - Name: Using manual mode with STS
+  - Name: Using manual mode with AWS Secure Token Service
     File: cco-mode-sts
+  - Name: Using manual mode with GCP Workload Identity
+    File: cco-mode-gcp-workload-identity
 ---
 Name: Networking
 Dir: networking

authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc

@@ -26,7 +26,9 @@ Mint mode is the default and recommended best practice setting for the CCO to us
 
 * **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-manual.adoc#cco-mode-manual[Manual]**: In manual mode, a user manages cloud credentials instead of the CCO.
 
-** **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-mode-sts[Manual with AWS STS]**: In manual mode, you can configure an AWS cluster to use Amazon Web Services Secure Token Service (AWS STS). With this configuration, the CCO uses temporary credentials for different components.
+** **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-mode-sts[Manual with AWS Secure Token Service]**: In manual mode, you can configure an AWS cluster to use Amazon Web Services Secure Token Service (AWS STS). With this configuration, the CCO uses temporary credentials for different components.
+
+** **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#cco-mode-gcp-workload-identity[Manual with GCP Workload Identity]**: In manual mode, you can configure a GCP cluster to use GCP Workload Identity. With this configuration, the CCO uses temporary credentials for different components.
 
 .CCO mode support matrix
 [cols="<.^2,^.^1,^.^1,^.^1"]

authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc

@@ -0,0 +1,129 @@
+:_content-type: ASSEMBLY
+[id="cco-mode-gcp-workload-identity"]
+= Using manual mode with GCP Workload Identity
+include::_attributes/common-attributes.adoc[]
+:context: cco-mode-gcp-workload-identity
+
+toc::[]
+
+Manual mode with GCP Workload Identity is supported for Google Cloud Platform (GCP).
+
+In manual mode with GCP Workload Identity, the individual {product-title} 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. {product-title} 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.
+
+////
+to-do: GCP diagram from https://github.com/openshift/cloud-credential-operator/blob/master/docs/gcp_workload_identity_flow.png?raw=true
+
+.Workload Identity authentication flow
+image::<new_filename_for_gcp_workload_id.svg[Detailed authentication flow between GCP and the cluster when using GCP Workload Identity]
+//to-do: improve alt-text
+////
+
+Using manual mode with GCP Workload Identity changes the content of the GCP credentials that are provided to individual {product-title} components.
+
+.GCP secret format
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  namespace: <target_namespace> <1>
+  name: <target_secret_name> <2>
+data:
+  service_account.json: <service_account> <3>
+----
+<1> The namespace for the component.
+<2> The name of the component secret.
+<3> The Base64 encoded service account.
+
+.Content of the Base64 encoded `service_account.json` file using long-lived credentials
+
+[source,json]
+----
+{
+   "type": "service_account", <1>
+   "project_id": "<project_id>",
+   "private_key_id": "<private_key_id>",
+   "private_key": "<private_key>", <2>
+   "client_email": "<client_email_address>",
+   "client_id": "<client_id>",
+   "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+   "token_uri": "https://oauth2.googleapis.com/token",
+   "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+   "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/<client_email_address>"
+}
+----
+<1> The credential type is `service_account`.
+<2> The 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
+
+[source,json]
+----
+{
+   "type": "external_account", <1>
+   "audience": "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/test-pool/providers/test-provider", <2>
+   "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
+   "token_url": "https://sts.googleapis.com/v1/token",
+   "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/<client_email_address>:generateAccessToken", <3>
+   "credential_source": {
+      "file": "<path_to_token>", <4>
+      "format": {
+         "type": "text"
+      }
+   }
+}
+----
+<1> The credential type is `external_account`.
+<2> The target audience is the GCP Workload Identity provider.
+<3> The resource URL of the service account that can be impersonated with these credentials.
+<4> The path to the service account token inside the pod. By convention, this is `/var/run/secrets/openshift/serviceaccount/token` for {product-title} components.
+
+//Supertask: Installing an OCP cluster configured for manual mode with GCP Workload Identity
+[id="gcp-workload-identity-mode-installing"]
+== Installing an {product-title} 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:
+
+. xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#cco-ccoctl-configuring_cco-mode-gcp-workload-identity[Configure the Cloud Credential Operator utility].
+. xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#cco-ccoctl-creating-at-once_cco-mode-gcp-workload-identity[Create the required GCP resources].
+. xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#sts-mode-installing-manual-run-installer_cco-mode-gcp-workload-identity[Run the {product-title} installer].
+. xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#sts-mode-installing-verifying_cco-mode-gcp-workload-identity[Verify that the cluster is using short-lived credentials].
+
+////
+// Remove until upgrade is supported.
+[NOTE]
+====
+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 {product-title}, 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.
+====
+////
+
+//Task part 1: Configuring the Cloud Credential Operator utility
+include::modules/cco-ccoctl-configuring.adoc[leveloffset=+2]
+
+//Task part 2: Creating the required GCP resources all at once
+include::modules/cco-ccoctl-creating-at-once.adoc[leveloffset=+2]
+
+//Task part 3: Run the OCP installer
+include::modules/sts-mode-installing-manual-run-installer.adoc[leveloffset=+2]
+
+//Task part 4: Verify that the cluster is using short-lived credentials
+include::modules/sts-mode-installing-verifying.adoc[leveloffset=+2]
+
+////
+// No Upgrade in 4.10 but this should work exactly the same as AWS STS does.
+[id="gcp-workload-identity-mode-upgrading"]
+== Upgrading an {product-title} cluster configured for manual mode with GCP Workload Identity
+
+The release image for the version of {product-title} that you are upgrading to contains a version of the `ccoctl` binary and list of `CredentialsRequest` objects specific to that release.
+
+:context: sts-mode-upgrading
+
+include::modules/cco-ccoctl-configuring.adoc[leveloffset=+2]
+
+include::modules/cco-ccoctl-upgrading.adoc[leveloffset=+2]
+
+include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+2]
+////

installing/installing_gcp/manually-creating-iam-gcp.adoc

@@ -13,7 +13,8 @@ include::modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc[level
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../post_installation_configuration/cluster-tasks.adoc#post-install-rotate-remove-cloud-creds[Rotating or removing cloud provider credentials].
+* xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#cco-mode-gcp-workload-identity[Using manual mode with GCP Workload Identity]
+* xref:../../post_installation_configuration/cluster-tasks.adoc#post-install-rotate-remove-cloud-creds[Rotating or removing cloud provider credentials]
 
 For a detailed description of all available CCO credential modes and their supported platforms, see xref:../../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc#about-cloud-credential-operator[About the Cloud Credential Operator].
 

installing/installing_gcp/uninstalling-cluster-gcp.adoc

@@ -9,3 +9,5 @@ toc::[]
 You can remove a cluster that you deployed to Google Cloud Platform (GCP).
 
 include::modules/installation-uninstall-clouds.adoc[leveloffset=+1]
+
+include::modules/cco-ccoctl-deleting-sts-resources.adoc[leveloffset=+1]

modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc

@@ -35,6 +35,13 @@ You can use the CCO utility (`ccoctl`) to configure the cluster to use the Amazo
 
 endif::aws[]
 
+ifdef::google-cloud-platform[]
+* *Use manual mode with GCP Workload Identity*:
++
+You can use the CCO utility (`ccoctl`) to configure the cluster to use manual mode with GCP Workload Identity. When the CCO utility is used to configure the cluster for GCP Workload Identity, it signs service account tokens that provide short-term, limited-privilege security credentials to components.
+
+endif::google-cloud-platform[]
+
 ifdef::aws,google-cloud-platform[]
 * *Manage cloud credentials manually*:
 +

modules/cco-ccoctl-configuring.adoc

@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
 // * authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc
+// * authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc
 // * installing/installing_ibm_cloud_public/configuring-iam-ibm-cloud.adoc
 // * installing/installing_alibaba/manually-creating-alibaba-ram.adoc
 
@@ -13,14 +14,18 @@ endif::[]
 ifeval::["{context}" == "manually-creating-alibaba-ram"]
 :alibabacloud:
 endif::[]
+ifeval::["{context}" == "cco-mode-gcp-workload-identity"]
+:google-cloud-platform:
+endif::[]
 
 :_content-type: PROCEDURE
 [id="cco-ccoctl-configuring_{context}"]
 = 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 
+To create and manage cloud credentials from outside of the cluster when the Cloud Credential Operator (CCO) is operating in
 ifdef::aws-sts[manual mode with STS,]
 ifdef::ibm-cloud[manual mode,]
+ifdef::google-cloud-platform[manual mode with GCP Workload Identity,]
 extract and prepare the CCO utility (`ccoctl`) binary.
 
 ifdef::alibabacloud[]
@@ -71,19 +76,10 @@ $ chmod 775 ccoctl
 
 * To verify that `ccoctl` is ready to use, display the help file:
 +
-ifndef::ibm-cloud[]
 [source,terminal]
 ----
 $ ccoctl --help
 ----
-endif::ibm-cloud[]
-ifdef::ibm-cloud[]
-[source,terminal]
-----
-$ ccoctl ibmcloud --help
-----
-endif::ibm-cloud[]
-ifndef::ibm-cloud[]
 +
 .Output of `ccoctl --help`:
 +
@@ -106,7 +102,6 @@ Flags:
 
 Use "ccoctl [command] --help" for more information about a command.
 ----
-endif::ibm-cloud[]
 
 ifeval::["{context}" == "cco-mode-sts"]
 :!aws-sts:
@@ -117,4 +112,6 @@ endif::[]
 ifeval::["{context}" == "manually-creating-alibaba-ram"]
 :!alibabacloud:
 endif::[]
-
+ifeval::["{context}" == "cco-mode-gcp-workload-identity"]
+:!google-cloud-platform:
+endif::[]