diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 5b8d9f8e27d9..f54304cb1e1b 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -2634,6 +2634,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 index ea9fbad0e6ac..6182e14bcaef 100644 --- 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 new file mode 100644 index 000000000000..741485617a9a --- /dev/null +++ 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: \ No newline at end of file diff --git a/modules/pod-short-term-auth-gcp-cloud-sa.adoc b/modules/pod-short-term-auth-gcp-cloud-sa.adoc new file mode 100644 index 000000000000..43aa3bebc16b --- /dev/null +++ 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]. \ No newline at end of file diff --git a/modules/pod-short-term-auth-gcp-cluster-sa.adoc b/modules/pod-short-term-auth-gcp-cluster-sa.adoc new file mode 100644 index 000000000000..0f24c5052186 --- /dev/null +++ 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 +---- + +. 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 -p '{"metadata": {"annotations": {"cloud.google.com/workload-identity-provider": "projects//locations/global/workloadIdentityPools//providers/"}}}' +---- ++ +Replace ``, ``, and `` with the values for your configuration. ++ +[NOTE] +==== +For ``, 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 -p '{"metadata": {"annotations": {"cloud.google.com/service-account-email": ""}}}' +---- ++ +Replace `` with the email address for the {gcp-short} service account. ++ +[TIP] +==== +{gcp-short} service account email addresses typically use the format `@.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 -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 --member "" --role "projects//roles/" +---- ++ +Replace `` 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 +---- ++ +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//locations/global/workloadIdentityPools//providers/" <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. +-- \ No newline at end of file diff --git a/modules/pod-short-term-auth-gcp-deploy-pod.adoc b/modules/pod-short-term-auth-gcp-deploy-pod.adoc new file mode 100644 index 000000000000..351a65af0fb4 --- /dev/null +++ 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: "" <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//locations/global/workloadIdentityPools/on-prem-kubernetes/providers/", + "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. +-- \ No newline at end of file diff --git a/nodes/pods/nodes-pods-short-term-auth.adoc b/nodes/pods/nodes-pods-short-term-auth.adoc new file mode 100644 index 000000000000..c8fc90d178f8 --- /dev/null +++ b/nodes/pods/nodes-pods-short-term-auth.adoc @@ -0,0 +1,130 @@ +:_mod-docs-content-type: ASSEMBLY +:context: nodes-pods-short-term-auth +[id="nodes-pods-short-term-auth"] += Authenticating pods with short-term credentials +include::_attributes/common-attributes.adoc[] + +toc::[] + +Some {product-title} clusters use xref:../../authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc#cco-short-term-creds[short-term security credentials for individual components] that are created and managed outside the cluster. +Applications in customer workloads on these clusters can authenticate by using the short-term authentication method that the cluster uses. + +[id="nodes-pods-short-term-auth-configuring_{context}"] +== Configuring short-term authentication for workloads + +To use this authentication method in your applications, you must complete the following steps: + +. Create a federated identity service account in the Identity and Access Management (IAM) settings for your cloud provider. + +. Create an {product-title} service account that can impersonate a service account for your cloud provider. + +. Configure any workloads related to your application to use the {product-title} service account. + +[id="nodes-pods-short-term-auth-prereqs_{context}"] +=== Environment and user access requirements + +To configure this authentication method, you must meet the following requirements: + +* Your cluster must use xref:../../authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc#cco-short-term-creds[short-term security credentials]. + +* You must have access to the {oc-first} as a user with the `cluster-admin` role. + +* In your cloud provider console, you must have access as a user with privileges to manage Identity and Access Management (IAM) and federated identity configurations. + +// Section to add with AWS and Azure content. Only documenting GCP at this time. +//// +[id="nodes-pods-short-term-auth-compatibility_{context}"] +=== Compatibility limitations + +This authentication method is only supported for {aws-first}, {gcp-first}, and {azure-full} clusters. +You can only authenticate workloads with short-term credentials by using the same authentication method as the cluster. + +.Supported configurations for workload authentication with short-term credentials +[cols="<.^h,^.^,^.^,^.^"] +|==== +|Cluster configuration |Workload authentication with {aws-short} {sts-short} |Workload authentication with {gcp-wid-short} |Workload authentication with {entra-first} + +|{aws-short} with {aws-short} {sts-short} +|*Supported* +|Unsupported +|Unsupported + +|{aws-short} without {aws-short} {sts-short} +|Unsupported +|Unsupported +|Unsupported + +|{gcp-short} with {gcp-wid-short} +|Unsupported +|*Supported* ^[1]^ +|Unsupported + +|{gcp-short} without {gcp-wid-short} +|Unsupported +|Unsupported +|Unsupported + +|{azure-short} with {entra-short} +|Unsupported +|Unsupported +|*Supported* + +|{azure-short} without {entra-short} +|Unsupported +|Unsupported +|Unsupported +|==== +1. With {product-title} version 4.17.4 or later. +//// + +// Content stub for later addition: +//// + +[id="nodes-pods-short-term-auth-configuring-aws_{context}"] +== Configuring {aws-short} {sts-short} authentication for applications on {aws-short} + +#Placeholder for {aws-short} {sts-short} version# + +To use short-term authentication for applications on an {aws-short} cluster that uses {sts-short} authentication, you must complete the following steps: + +. Configure access in {aws-short}. +. Create an {product-title} service account that can use this access. +. Deploy customer workloads that authenticate with {aws-short} {sts-short}. + +#Placeholder for {aws-short} {sts-short} version# +//// + +[id="nodes-pods-short-term-auth-configuring-gcp_{context}"] +== Configuring {gcp-wid-short} authentication for applications on {gcp-short} + +To use short-term authentication for applications on a {gcp-short} clusters that use {gcp-wid-short} authentication, you must complete the following steps: + +. xref:../../nodes/pods/nodes-pods-short-term-auth.adoc#pod-short-term-auth-gcp-cloud-sa_nodes-pods-short-term-auth[Configure access in {gcp-short}.] +. xref:../../nodes/pods/nodes-pods-short-term-auth.adoc#pod-short-term-auth-gcp-cluster-sa_nodes-pods-short-term-auth[Create an {product-title} service account that can use this access.] +. xref:../../nodes/pods/nodes-pods-short-term-auth.adoc#pod-short-term-auth-gcp-deploy-pod_nodes-pods-short-term-auth[Deploy customer workloads that authenticate with {gcp-wid-short}.] + +// Creating a federated {gcp-short} service account +include::modules/pod-short-term-auth-gcp-cloud-sa.adoc[leveloffset=+2] + +// Creating an {product-title} service account for {gcp-short} +include::modules/pod-short-term-auth-gcp-cluster-sa.adoc[leveloffset=+2] + +// Deploying a pod that authenticates with {gcp-wid-short} +include::modules/pod-short-term-auth-gcp-deploy-pod.adoc[leveloffset=+2] + + +// Content stub for later addition: +//// +[id="nodes-pods-short-term-auth-configuring-azure_{context}"] +== Configuring {entra-first} authentication for applications on {azure-short} + +#Placeholder for {entra-short} version# + +To use short-term authentication for applications on an {azure-short} cluster that uses {entra-short} authentication, you must complete the following steps: + +. Configure access in {azure-short}. +. Create an {product-title} service account that can use this access. +. Deploy customer workloads that authenticate with {entra-short}. + +#Placeholder for {entra-short} version# +//// \ No newline at end of file