Merge pull request #81381 from adellape/olm-cco-gcp

adellape · web-flow · commit 68a22735a1af · 2024-09-25T23:33:00.000-06:00
OSDOCS-11905: Add GCP Workload Identity OLM/CCO docs
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -1960,6 +1960,8 @@ Topics:
       File: osdk-cco-aws-sts
     - Name: CCO-based workflow for OLM-managed Operators with Microsoft Entra Workload ID
       File: osdk-cco-azure
+    - Name: CCO-based workflow for OLM-managed Operators with GCP Workload Identity
+      File: osdk-cco-gcp
   - Name: Validating Operators using the scorecard
     File: osdk-scorecard
   - Name: Validating Operator bundles
diff --git a/authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc b/authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc
@@ -78,10 +78,9 @@ include::modules/cco-short-term-creds-format-gcp.adoc[leveloffset=+2]
 //OLM-managed Operator support for authentication with GCP Workload Identity
 include::modules/cco-short-term-creds-gcp-olm.adoc[leveloffset=+2]
 
-// Placeholder/guess for OLM link
-// [role="_additional-resources"]
-// .Additional resources
-// * xr3f:../../operators/operator_sdk/token_auth/osdk-cco-gcp.adoc#osdk-cco-gcp[CCO-based workflow for OLM-managed Operators with {gcp-wid-first}]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../operators/operator_sdk/token_auth/osdk-cco-gcp.adoc#osdk-cco-gcp[CCO-based workflow for OLM-managed Operators with {gcp-wid-first}]
 
 [id="cco-short-term-creds-azure_{context}"]
 == {entra-first}
diff --git a/modules/olm-installing-from-operatorhub-using-cli.adoc b/modules/olm-installing-from-operatorhub-using-cli.adoc
@@ -265,24 +265,31 @@ spec:
 <2> Set a specific version of an Operator CSV.
 ====
 
-.. For clusters on cloud providers with token authentication enabled, configure your `Subscription` object by following these steps:
+.. For clusters on cloud providers with token authentication enabled, such as {aws-first} {sts-first}, {entra-first}, or {gcp-wid-first}, configure your `Subscription` object by following these steps:
 
 ... Ensure the `Subscription` object is set to manual update approvals:
 +
+.Example `Subscription` object with manual update approvals
+[%collapsible]
+====
 [source,yaml]
 ----
 kind: Subscription
 # ...
 spec:
   installPlanApproval: Manual <1>
 ----
-<1> Subscriptions with automatic update approvals are not recommended because there might be permission changes to make prior to updating. Subscriptions with manual update approvals ensure that administrators have the opportunity to verify the permissions of the later version and take any necessary steps prior to update.
+<1> Subscriptions with automatic approvals for updates are not recommended because there might be permission changes to make before updating. Subscriptions with manual approvals for updates ensure that administrators have the opportunity to verify the permissions of the later version, take any necessary steps, and then update.
+====
 
 ... Include the relevant cloud provider-specific fields in the `Subscription` object's `config` section:
 +
 --
 * If the cluster is in AWS STS mode, include the following fields:
 +
+.Example `Subscription` object with {aws-short} {sts-short} variables
+[%collapsible]
+====
 [source,yaml]
 ----
 kind: Subscription
@@ -294,9 +301,13 @@ spec:
       value: "<role_arn>" <1>
 ----
 <1> Include the role ARN details.
+====
 
-* If the cluster is in {entra-first} mode, include the following fields:
+* If the cluster is in {entra-short} mode, include the following fields:
 +
+.Example `Subscription` object with {entra-short} variables
+[%collapsible]
+====
 [source,yaml]
 ----
 kind: Subscription
@@ -314,6 +325,41 @@ spec:
 <1> Include the client ID.
 <2> Include the tenant ID.
 <3> Include the subscription ID.
+====
+
+* If the cluster is in {gcp-wid-short} mode, include the following fields:
++
+.Example `Subscription` object with {gcp-wid-short} variables
+[%collapsible]
+====
+[source,yaml]
+----
+kind: Subscription
+# ...
+spec:
+ config:
+   env:
+   - name: AUDIENCE
+     value: "<audience_url>" <1>
+   - name: SERVICE_ACCOUNT_EMAIL
+     value: "<service_account_email>" <2>
+----
+
+where:
+
+`<audience>`:: Created in {gcp-short} by the administrator when they set up {gcp-wid-short}, the `AUDIENCE` value must be a preformatted URL in the following format:
++
+[source,text]
+----
+//iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_id>/providers/<provider_id>
+----
+`<service_account_email>`:: The `SERVICE_ACCOUNT_EMAIL` value is a {gcp-short} service account email that is impersonated during Operator operation, for example:
++
+[source,text]
+----
+<service_account_name>@<project_id>.iam.gserviceaccount.com
+----
+====
 --
 
 .. Create the `Subscription` object by running the following command:
diff --git a/modules/olm-installing-from-operatorhub-using-web-console.adoc b/modules/olm-installing-from-operatorhub-using-web-console.adoc
@@ -90,18 +90,20 @@ endif::[]
 .. For clusters on cloud providers with token authentication enabled:
 +
 --
-* If the cluster uses {aws-short} {sts-short} (*STS Mode* in the web console), enter the Amazon Resource Name (ARN) of the AWS IAM role of your service account in the *role ARN* field. To create the role's ARN, follow the procedure described in link:https://access.redhat.com/documentation/en-us/red_hat_openshift_service_on_aws/4/html/tutorials/cloud-experts-deploy-api-data-protection#prepare-aws-account_cloud-experts-deploy-api-data-protection[Preparing AWS account].
+* If the cluster uses {aws-short} {sts-full} (*STS Mode* in the web console), enter the Amazon Resource Name (ARN) of the AWS IAM role of your service account in the *role ARN* field. To create the role's ARN, follow the procedure described in link:https://access.redhat.com/documentation/en-us/red_hat_openshift_service_on_aws/4/html/tutorials/cloud-experts-deploy-api-data-protection#prepare-aws-account_cloud-experts-deploy-api-data-protection[Preparing AWS account].
 
-* If the cluster uses {entra-first} (*Workload Identity / Federated Identity Mode* in the web console), add the client ID, tenant ID, and subscription ID in the appropriate field.
+* If the cluster uses {entra-first} (*Workload Identity / Federated Identity Mode* in the web console), add the client ID, tenant ID, and subscription ID in the appropriate fields.
+
+* If the cluster uses {gcp-wid-first} (*{gcp-wid-short} / Federated Identity Mode* in the web console), add the project number, pool ID, provider ID, and service account email in the appropriate fields.
 --
 
 .. For *Update approval*, select either the *Automatic* or *Manual* approval strategy.
 +
 [IMPORTANT]
 ====
-If the web console shows that the cluster uses {aws-short} {sts-short} or {entra-first}, you must set *Update approval* to *Manual*.
+If the web console shows that the cluster uses {aws-short} {sts-short}, {entra-first}, or {gcp-wid-short}, you must set *Update approval* to *Manual*.
 
-Subscriptions with automatic update approvals are not recommended because there might be permission changes to make prior to updating. Subscriptions with manual update approvals ensure that administrators have the opportunity to verify the permissions of the later version and take any necessary steps prior to update.
+Subscriptions with automatic approvals for updates are not recommended because there might be permission changes to make before updating. Subscriptions with manual approvals for updates ensure that administrators have the opportunity to verify the permissions of the later version, take any necessary steps, and then update.
 ====
 
 . Click *Install* to make the Operator available to the selected namespaces on this {product-title} cluster:
diff --git a/modules/osdk-cco-aws-sts-enabling.adoc b/modules/osdk-cco-aws-sts-enabling.adoc
@@ -9,7 +9,7 @@
 
 As an Operator author designing your project to run on Operator Lifecycle Manager (OLM), you can enable your Operator to authenticate against AWS on STS-enabled {product-title} clusters by customizing your project to support the Cloud Credential Operator (CCO).
 
-With this method, the Operator is responsible for creating the `CredentialsRequest` object, which means the Operator requires RBAC permission to create these objects. Then, the Operator must be able to read the resulting `Secret` object.
+With this method, the Operator is responsible for and requires RBAC permissions for creating the `CredentialsRequest` object and reading the resulting `Secret` object.
 
 [NOTE]
 ====
@@ -206,7 +206,7 @@ Adding a `CredentialsRequest` object to the Operator bundle is not currently sup
 ====
 [source,go]
 ----
-// apply credentialsRequest on install
+// apply CredentialsRequest on install
 credReq := credreq.CredentialsRequestTemplate
 credReq.Spec.CloudTokenPath = webIdentityTokenPath
 
diff --git a/modules/osdk-cco-azure-enabling.adoc b/modules/osdk-cco-azure-enabling.adoc
@@ -8,7 +8,7 @@
 
 As an Operator author designing your project to run on Operator Lifecycle Manager (OLM), you can enable your Operator to authenticate against {entra-first}-enabled {product-title} clusters by customizing your project to support the Cloud Credential Operator (CCO).
 
-With this method, the Operator is responsible for creating the `CredentialsRequest` object, which means the Operator requires RBAC permission to create these objects. Then, the Operator must be able to read the resulting `Secret` object.
+With this method, the Operator is responsible for and requires RBAC permissions for creating the `CredentialsRequest` object and reading the resulting `Secret` object.
 
 [NOTE]
 ====
@@ -89,7 +89,7 @@ Adding a `CredentialsRequest` object to the Operator bundle is not currently sup
 ====
 [source,go]
 ----
-// apply credentialsRequest on install
+// apply CredentialsRequest on install
 credReqTemplate.Spec.AzureProviderSpec.AzureClientID = clientID
 credReqTemplate.Spec.AzureProviderSpec.AzureTenantID = tenantID
 credReqTemplate.Spec.AzureProviderSpec.AzureRegion = "centralus"
diff --git a/modules/osdk-cco-gcp-enabling.adoc b/modules/osdk-cco-gcp-enabling.adoc
@@ -0,0 +1,182 @@
+// Module included in the following assemblies:
+//
+// * operators/operator_sdk/osdk-token-auth/osdk-cco-gcp.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="osdk-cco-gcp-enabling_{context}"]
+= Enabling Operators to support CCO-based workflows with {gcp-wid-short}
+
+As an Operator author designing your project to run on Operator Lifecycle Manager (OLM), you can enable your Operator to authenticate against {gcp-wid-first} on {product-title} clusters by customizing your project to support the Cloud Credential Operator (CCO).
+
+With this method, the Operator is responsible for and requires RBAC permissions for creating the `CredentialsRequest` object and reading the resulting `Secret` object.
+
+[NOTE]
+====
+By default, pods related to the Operator deployment mount a `serviceAccountToken` volume so that the service account token can be referenced in the resulting `Secret` object.
+====
+
+.Prerequisities
+
+* {product-title} 4.17 or later
+* Cluster in *{gcp-wid-short} / Federated Identity* mode
+* OLM-based Operator project
+
+.Procedure
+
+. Update your Operator project's `ClusterServiceVersion` (CSV) object:
+
+.. Ensure Operator deployment in the CSV has the following `volumeMounts` and `volumes` fields so that the Operator can assume the role with web identity:
++
+.Example `volumeMounts` and `volumes` fields
+[%collapsible]
+====
+[source,yaml]
+----
+# ...
+      volumeMounts:
+  
+      - name: bound-sa-token
+        mountPath: /var/run/secrets/openshift/serviceaccount
+        readOnly: true
+      volumes:
+         # This service account token can be used to provide identity outside the cluster.
+         - name: bound-sa-token
+           projected:
+             sources:
+             - serviceAccountToken:
+               path: token
+               audience: openshift
+----
+====
+
+.. Ensure your Operator has RBAC permission to create `CredentialsRequests` objects:
++
+.Example `clusterPermissions` list
+[%collapsible]
+====
+[source,yaml]
+----
+# ...
+install:
+  spec:
+    clusterPermissions:
+    - rules:
+      - apiGroups:
+        - "cloudcredential.openshift.io"
+        resources:
+        - credentialsrequests
+        verbs:
+        - create
+        - delete
+        - get
+        - list
+        - patch
+        - update
+        - watch
+----
+====
+
+.. Add the following annotation to claim support for this method of CCO-based workflow with {gcp-wid-short}:
++
+[source,yaml]
+----
+# ...
+metadata:
+ annotations:
+   features.operators.openshift.io/token-auth-gcp: "true"
+----
+
+. Update your Operator project code:
+
+.. Get the `audience` and the `serviceAccountEmail` values from the environment variables set on the pod by the subscription config:
++
+[source,go]
+----
+ // Get ENV var
+   audience := os.Getenv("AUDIENCE")
+   serviceAccountEmail := os.Getenv("SERVICE_ACCOUNT_EMAIL")
+   gcpIdentityTokenFile := "/var/run/secrets/openshift/serviceaccount/token"
+----
+
+.. Ensure you have a `CredentialsRequest` object ready to be patched and applied.
++
+[NOTE]
+====
+Adding a `CredentialsRequest` object to the Operator bundle is not currently supported.
+====
+
+.. Add the {gcp-wid-short} variables to the credentials request and apply it during Operator initialization:
++
+.Example applying `CredentialsRequest` object during Operator initialization
+[%collapsible]
+====
+[source,go]
+----
+// apply CredentialsRequest on install
+   credReqTemplate.Spec.GCPProviderSpec.Audience = audience
+   credReqTemplate.Spec.GCPProviderSpec.ServiceAccountEmail = serviceAccountEmail
+   credReqTemplate.CloudTokenPath = gcpIdentityTokenFile
+
+
+   c := mgr.GetClient()
+   if err := c.Create(context.TODO(), credReq); err != nil {
+       if !errors.IsAlreadyExists(err) {
+           setupLog.Error(err, "unable to create CredRequest")
+           os.Exit(1)
+       }
+   }
+----
+====
+
+.. Ensure your Operator can wait for a `Secret` object to show up from the CCO, as shown in the following example, which is called along with the other items you are reconciling in your Operator:
++
+.Example wait for `Secret` object
+[%collapsible]
+====
+[source,go]
+----
+// WaitForSecret is a function that takes a Kubernetes client, a namespace, and a v1 "k8s.io/api/core/v1" name as arguments
+// It waits until the secret object with the given name exists in the given namespace
+// It returns the secret object or an error if the timeout is exceeded
+func WaitForSecret(client kubernetes.Interface, namespace, name string) (*v1.Secret, error) {
+  // set a timeout of 10 minutes
+  timeout := time.After(10 * time.Minute) <1>
+
+  // set a polling interval of 10 seconds
+  ticker := time.NewTicker(10 * time.Second)
+
+  // loop until the timeout or the secret is found
+  for {
+     select {
+     case <-timeout:
+        // timeout is exceeded, return an error
+        return nil, fmt.Errorf("timed out waiting for secret %s in namespace %s", name, namespace)
+// add to this error with a pointer to instructions for following a manual path to a Secret that will work
+     case <-ticker.C:
+        // polling interval is reached, try to get the secret
+        secret, err := client.CoreV1().Secrets(namespace).Get(context.Background(), name, metav1.GetOptions{})
+        if err != nil {
+           if errors.IsNotFound(err) {
+              // secret does not exist yet, continue waiting
+              continue
+           } else {
+              // some other error occurred, return it
+              return nil, err
+           }
+        } else {
+           // secret is found, return it
+           return secret, nil
+        }
+     }
+  }
+}
+----
+<1> The `timeout` value is based on an estimate of how fast the CCO might detect an added `CredentialsRequest` object and generate a `Secret` object. You might consider lowering the time or creating custom feedback for cluster administrators that could be wondering why the Operator is not yet accessing the cloud resources.
+====
+
+.. Read the `service_account.json` field from the secret and use it to authenticate your {gcp-short} client:
++
+[source,go]
+----
+service_account_json := secret.StringData["service_account.json"]
+----
diff --git a/operators/operator_sdk/token_auth/osdk-cco-aws-sts.adoc b/operators/operator_sdk/token_auth/osdk-cco-aws-sts.adoc
@@ -13,18 +13,18 @@ The JWT includes an Amazon Resource Name (ARN) for the `sts:AssumeRoleWithWebIde
 The Cloud Credential Operator (CCO) is a cluster Operator installed by default in {product-title} clusters running on cloud providers. For the purposes of STS, the CCO provides the following functions:
 
 * Detects when it is running on an STS-enabled cluster
-* Checks for the presence of fields in the `CredentialsRequest` object that provide the required information for granting Operators access to AWS resources
+* Checks the `CredentialsRequest` object for the presence of fields that provide the required information for granting Operators access to AWS resources
 
 The CCO performs this detection even when in manual mode. When properly configured, the CCO projects a `Secret` object with the required access information into the Operator namespace.
 
 Starting in {product-title} 4.14, the CCO can semi-automate this task through an expanded use of `CredentialsRequest` objects, which can request the creation of `Secrets` that contain the information required for STS workflows. Users can provide a role ARN when installing the Operator from either the web console or CLI.
 
 [NOTE]
 ====
-Subscriptions with automatic update approvals are not recommended because there might be permission changes to make prior to updating. Subscriptions with manual update approvals ensure that administrators have the opportunity to verify the permissions of the later version and take any necessary steps prior to update.
+Subscriptions with automatic approvals for updates are not recommended because there might be permission changes to make before updating. Subscriptions with manual approvals for updates ensure that administrators have the opportunity to verify the permissions of the later version, take any necessary steps, and then update.
 ====
 
-As an Operator author preparing an Operator for use alongside the updated CCO in {product-title} 4.14 or later, you should instruct users and add code to handle the divergence from earlier CCO versions, in addition to handling STS token authentication (if your Operator is not already STS-enabled). The recommended method is to provide a `CredentialsRequest` object with correctly filled STS-related fields and let the CCO create the `Secret` for you.
+As an Operator author preparing an Operator for use alongside the updated CCO in {product-title} 4.14 or later, you should instruct users and add code to handle the divergence from earlier CCO versions, in addition to handling STS token authentication (if your Operator is not already STS-enabled). The recommended method is to provide a `CredentialsRequest` object with the correctly filled {sts-short} fields and let the CCO create the `Secret` for you.
 
 [IMPORTANT]
 ====
diff --git a/operators/operator_sdk/token_auth/osdk-cco-azure.adoc b/operators/operator_sdk/token_auth/osdk-cco-azure.adoc
diff --git a/operators/operator_sdk/token_auth/osdk-cco-gcp.adoc b/operators/operator_sdk/token_auth/osdk-cco-gcp.adoc
diff --git a/operators/operator_sdk/token_auth/osdk-token-auth.adoc b/operators/operator_sdk/token_auth/osdk-token-auth.adoc
