OSDOCS-11383: GCP Workload ID webhook

jeana-redhat · jeana-redhat · commit b0a0dd05e132 · 2024-11-12T14:02:58.000-05:00
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -2571,6 +2571,8 @@ Topics:
     File: nodes-pods-secrets
   - Name: Providing sensitive data to pods by using an external secrets store
     File: nodes-pods-secrets-store
+  - Name: Authenticating pods with short-term credentials
+    File: nodes-pods-short-term-auth
   - Name: Creating and using config maps
     File: nodes-pods-configmaps
   - Name: Using Device Manager to make devices available to nodes
diff --git a/authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc b/authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc
@@ -57,6 +57,23 @@ include::modules/cco-short-term-creds-aws-olm.adoc[leveloffset=+2]
 .Additional resources
 * xref:../../operators/operator_sdk/token_auth/osdk-cco-aws-sts.adoc#osdk-cco-aws-sts[CCO-based workflow for OLM-managed Operators with {aws-short} {sts-short}]
 
+// Content stub for later addition:
+////
+// Application support for AWS STS service account tokens
+// Extra context so module can be reused within assembly (unset in module)
+:context: aws
+// Attributes used in module with cloud-specific values (unset in module)
+:cloud-auth-first: {aws-short} {sts-first}
+:cloud-auth-short: {aws-short} {sts-short}
+include::modules/cco-short-term-creds-workloads.adoc[leveloffset=+2] 
+
+[role="_additional-resources"]
+.Additional resources
+* xr3f:../../nodes/pods/nodes-pods-short-term-auth.adoc#nodes-pods-short-term-auth-configuring-aws_nodes-pods-short-term-auth[Configuring {aws-short} {sts-short} authentication for pods on {aws-short}]
+
+:context: cco-short-term-creds
+////
+
 [id="cco-short-term-creds-gcp_{context}"]
 == {gcp-wid-short}
 
@@ -82,6 +99,20 @@ include::modules/cco-short-term-creds-gcp-olm.adoc[leveloffset=+2]
 .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}]
 
+// Application support for GCP Workload Identity service account tokens
+// Extra context so module can be reused within assembly (unset in module)
+:context: gcp
+// Attributes used in module with cloud-specific values (unset in module)
+:cloud-auth-first: {gcp-wid-first}
+:cloud-auth-short: {gcp-wid-short}
+include::modules/cco-short-term-creds-workloads.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../nodes/pods/nodes-pods-short-term-auth.adoc#nodes-pods-short-term-auth-configuring-gcp_nodes-pods-short-term-auth[Configuring {gcp-wid-short} authentication for applications on {gcp-short}]
+
+:context: cco-short-term-creds
+
 [id="cco-short-term-creds-azure_{context}"]
 == {entra-first}
 
@@ -107,6 +138,23 @@ include::modules/cco-short-term-creds-azure-olm.adoc[leveloffset=+2]
 .Additional resources
 * xref:../../operators/operator_sdk/token_auth/osdk-cco-azure.adoc#osdk-cco-azure[CCO-based workflow for OLM-managed Operators with {entra-first}]
 
+// Content stub for later addition:
+////
+// Application support for Microsoft Entra Workload ID service account tokens
+// Extra context so module can be reused within assembly (unset in module)
+:context: azure
+// Attributes used in module with cloud-specific values (unset in module)
+:cloud-auth-first: {entra-first}
+:cloud-auth-short: {entra-short}
+include::modules/cco-short-term-creds-workloads.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xr3f:../../nodes/pods/nodes-pods-short-term-auth.adoc#nodes-pods-short-term-auth-configuring-azure_nodes-pods-short-term-auth[Configuring {entra-first} authentication for pods on {azure-short}]
+
+:context: cco-short-term-creds
+////
+
 [role="_additional-resources"]
 [id="additional-resources_{context}"]
 == Additional resources
diff --git a/modules/cco-short-term-creds-workloads.adoc b/modules/cco-short-term-creds-workloads.adoc
@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="cco-short-term-creds-workloads_{context}"]
+= Application support for {cloud-auth-short} service account tokens
+
+Applications in customer workloads on {product-title} clusters that use {cloud-auth-first} can authenticate by using {cloud-auth-short}.
+To use this authentication method with your applications, you must complete configuration steps on the cloud provider console and your {product-title} cluster.
+
+// Unsetting attributes defined in authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc above include:: line
+:!context:
+:!cloud-auth-first:
+:!cloud-auth-full:
+:!cloud-auth-short:
diff --git a/modules/pod-short-term-auth-gcp-cloud-sa.adoc b/modules/pod-short-term-auth-gcp-cloud-sa.adoc
@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * nodes/pods/nodes-pods-short-term-auth.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[discrete]
+[id="pod-short-term-auth-gcp-cloud-sa_{context}"]
+= Creating a federated {gcp-short} service account
+
+You can use the Google Cloud console to create a workload identity pool and provider and allow an {product-title} service account to impersonate a {gcp-short} service account.
+
+.Prerequisites
+
+* Your {gcp-short} cluster is running {product-title} version 4.17.4 or later and uses {gcp-wid-short}.
+
+* You have access to the Google Cloud console as a user with privileges to manage Identity and Access Management (IAM) and workload identity configurations.
+
+* You have created a Google Cloud project to use with your application.
+
+.Procedure
+
+. In the IAM configuration for your Google Cloud project, identify the identity pool and provider that the cluster uses for {gcp-wid-short} authentication.
+
+. Grant permission for external identities to impersonate a {gcp-short} service account. 
+With these permissions, an {product-title} service account can work as a federated workload identity.
++
+For more information, see {gcp-short} documentation about link:https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#service-account-impersonation[allowing your external workload to access Google Cloud resources].
diff --git a/modules/pod-short-term-auth-gcp-cluster-sa.adoc b/modules/pod-short-term-auth-gcp-cluster-sa.adoc
@@ -0,0 +1,110 @@
+// Module included in the following assemblies:
+//
+// * nodes/pods/nodes-pods-short-term-auth.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[discrete]
+[id="pod-short-term-auth-gcp-cluster-sa_{context}"]
+= Creating an {product-title} service account for {gcp-short}
+
+You create an {product-title} service account and annotate it to impersonate a {gcp-short} service account.
+
+.Prerequisites
+
+* Your {gcp-short} cluster is running {product-title} version 4.17.4 or later and uses {gcp-wid-short}.
+
+* You have created a federated {gcp-short} service account.
+
+* You have access to the {oc-first} as a user with the `cluster-admin` role.
+
+* You have access to the Google Cloud CLI (`gcloud`) as a user with privileges to manage Identity and Access Management (IAM) and workload identity configurations.
+
+.Procedure
+
+. Create an {product-title} service account to use for {gcp-wid-short} pod authentication by running the following command:
++
+[source,terminal]
+----
+$ oc create serviceaccount <service_account_name>
+----
+
+. Annotate the service account with the identity provider and {gcp-short} service account to impersonate by running the following command:
++
+[source,terminal]
+----
+$ oc patch serviceaccount <service_account_name> -p '{"metadata": {"annotations": {"cloud.google.com/workload-identity-provider": "projects/<project_number>/locations/global/workloadIdentityPools/<identity_pool>/providers/<identity_provider>"}}}'
+----
++
+Replace `<project_number>`, `<identity_pool>`, and `<identity_provider>` with the values for your configuration.
++
+[NOTE]
+====
+For `<project_number>`, specify the Google Cloud project number, not the project ID.
+====
+
+. Annotate the service account with the email address for the {gcp-short} service account by running the following command:
++
+[source,terminal]
+----
+$ oc patch serviceaccount <service_account_name> -p '{"metadata": {"annotations": {"cloud.google.com/service-account-email": "<service_account_email>"}}}'
+----
++
+Replace `<service_account_email>` with the email address for the {gcp-short} service account.
++
+[TIP]
+====
+{gcp-short} service account email addresses typically use the format `<service_account_name>@<project_id>.iam.gserviceaccount.com`
+====
+
+. Annotate the service account to use the `direct` external credentials configuration injection mode by running the following command:
++
+[source,terminal]
+----
+$ oc patch serviceaccount <service_account_name> -p '{"metadata": {"annotations": {"cloud.google.com/injection-mode": "direct"}}}'
+----
++
+In this mode, the Workload Identity Federation webhook controller directly generates the {gcp-short} external credentials configuration and injects them into the pod.
+
+. Use the Google Cloud CLI (`gcloud`) to specify the permissions for the workload by running the following command:
++
+[source,terminal]
+----
+$ gcloud projects add-iam-policy-binding <project_id> --member "<service_account_email>" --role "projects/<project_id>/roles/<role_for_workload_permissions>"
+----
++
+Replace `<role_for_workload_permissions>` with the role for the workload. 
+Specify a role that grants the permissions that your workload requires.
+
+.Verification
+
+* To verify the service account configuration, inspect the `ServiceAccount` manifest by running the following command:
++
+[source,terminal]
+----
+$ oc get serviceaccount <service_account_name>
+----
++
+In the following example, the `service-a/app-x` {product-title} service account can impersonate a {gcp-short} service account called `app-x`:
++
+.Example output
+--
+[source,yaml]
+----
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: app-x
+  namespace: service-a
+  annotations: 
+    cloud.google.com/workload-identity-provider: "projects/<project_number>/locations/global/workloadIdentityPools/<identity_pool>/providers/<identity_provider>" <1>
+    cloud.google.com/service-account-email: "app-x@project.iam.googleapis.com"
+    cloud.google.com/audience: "sts.googleapis.com" <2>
+    cloud.google.com/token-expiration: "86400" <3>
+    cloud.google.com/gcloud-run-as-user: "1000"
+    cloud.google.com/injection-mode: "direct" <4>
+----
+<1> The workload identity provider for the service account of the cluster.
+<2> The allowed audience for the workload identity provider.
+<3> The token expiration time period in seconds.
+<4> The `direct` external credentials configuration injection mode.
+--
diff --git a/modules/pod-short-term-auth-gcp-deploy-pod.adoc b/modules/pod-short-term-auth-gcp-deploy-pod.adoc
@@ -0,0 +1,150 @@
+// Module included in the following assemblies:
+//
+// * nodes/pods/nodes-pods-short-term-auth.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[discrete]
+[id="pod-short-term-auth-gcp-deploy-pod_{context}"]
+= Deploying customer workloads that authenticate with {gcp-wid-short}
+
+To use short-term authentication in your application, you must configure its related pods to use the {product-title} service account.
+Use of the {product-title} service account triggers the webhook to mutate the pods so they can impersonate the {gcp-short} service account.
+
+The following example demonstrates how to deploy a pod that uses the {product-title} service account and verify the configuration.
+
+.Prerequisites
+
+* Your {gcp-short} cluster is running {product-title} version 4.17.4 or later and uses {gcp-wid-short}.
+
+* You have created a federated {gcp-short} service account.
+
+* You have created an {product-title} service account for {gcp-short}.
+
+.Procedure
+
+. To create a pod that authenticates with {gcp-wid-short}, create a deployment YAML file similar to the following example:
++
+.Sample deployment
+[source,yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ubi9
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: ubi9
+  template:
+    metadata:
+      labels:
+        app: ubi9
+    spec:
+      serviceAccountName: "<service_account_name>" <1>
+      containers:
+        - name: ubi
+          image: 'registry.access.redhat.com/ubi9/ubi-micro:latest'
+          command:
+            - /bin/sh
+            - '-c'
+            - |
+              sleep infinity
+----
+<1> Specify the name of the {product-title} service account.
+
+. Apply the deployment file by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f deployment.yaml
+----
+
+.Verification
+
+* To verify that a pod is using short-term authentication, run the following command:
++
+[source,terminal]
+----
+$ oc get pods -o json | jq -r '.items[0].spec.containers[0].env[] | select(.name=="GOOGLE_APPLICATION_CREDENTIALS")'
+----
++
+.Example output
+[source,terminal]
+----
+{   "name": "GOOGLE_APPLICATION_CREDENTIALS",   "value": "/var/run/secrets/workload-identity/federation.json" } 
+----
++
+The presence of the `GOOGLE_APPLICATION_CREDENTIALS` environment variable indicates a pod that authenticates with {gcp-wid-short}.
+
+* To verify additional configuration details, examine the pod specification.
+The following example pod specifications show the environment variables and volume fields that the webhook mutates.
++
+--
+.Example pod specification with the `direct` injection mode:
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  name: app-x-pod
+  namespace: service-a
+annotations:
+  cloud.google.com/skip-containers: "init-first,sidecar"
+  cloud.google.com/external-credentials-json: |- <1>
+    {
+      "type": "external_account",
+      "audience": "//iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/on-prem-kubernetes/providers/<identity_provider>",
+      "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/app-x@project.iam.gserviceaccount.com:generateAccessToken",
+      "credential_source": {
+        "file": "/var/run/secrets/sts.googleapis.com/serviceaccount/token",
+        "format": {
+          "type": "text"
+        }
+      }
+    }
+spec:
+  serviceAccountName: app-x
+  initContainers:
+  - name: init-first
+    image: container-image:version
+  containers:
+  - name: sidecar
+    image: container-image:version
+  - name: container-name
+    image: container-image:version
+    env: <2>
+    - name: GOOGLE_APPLICATION_CREDENTIALS
+      value: /var/run/secrets/gcloud/config/federation.json
+    - name: CLOUDSDK_COMPUTE_REGION
+      value: asia-northeast1
+    volumeMounts:
+    - name: gcp-iam-token
+      readOnly: true
+      mountPath: /var/run/secrets/sts.googleapis.com/serviceaccount
+    - mountPath: /var/run/secrets/gcloud/config
+      name: external-credential-config
+      readOnly: true
+  volumes:
+  - name: gcp-iam-token
+    projected:
+      sources:
+      - serviceAccountToken:
+          audience: sts.googleapis.com
+          expirationSeconds: 86400
+          path: token
+  - downwardAPI:
+      defaultMode: 288
+      items:
+      - fieldRef:
+          apiVersion: v1
+          fieldPath: metadata.annotations['cloud.google.com/external-credentials-json']
+        path: federation.json
+    name: external-credential-config
+----
+<1> The external credentials configuration generated by the webhook controller.
+The Kubernetes `downwardAPI` volume mounts the configuration into the container filesystem. 
+<2> The webhook-injected environment variables for token-based authentication.
+--
diff --git a/nodes/pods/nodes-pods-short-term-auth.adoc b/nodes/pods/nodes-pods-short-term-auth.adoc
