Merge pull request #64331 from bhardesty/osdocs-7640-sts-oidc-provider

EricPonvelle · web-flow · commit eb08487cb44d · 2023-09-07T16:45:28.000-04:00
OSDOCS-7640: Doc how service accounts assume AWS IAM roles
diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml
@@ -50,8 +50,8 @@ Topics:
       File: policy-responsibility-matrix
     - Name: Understanding process and security for OpenShift Dedicated
       File: policy-process-security
-#  - Name: SRE and service account access
-#    File: osd-sre-access
+#    - Name: SRE and service account access
+#      File: osd-sre-access
     - Name: About availability for OpenShift Dedicated
       File: policy-understand-availability
     - Name: Update life cycle
diff --git a/authentication/assuming-an-aws-iam-role-for-a-service-account.adoc b/authentication/assuming-an-aws-iam-role-for-a-service-account.adoc
@@ -11,11 +11,12 @@ toc::[]
 
 [role="_abstract"]
 ifdef::openshift-rosa[]
-{product-title} clusters that use the AWS Security Token Service (STS) include a pod identity webhook for use with pods that run in user-defined projects.
+In {product-title} clusters that use the AWS Security Token Service (STS), the OpenShift API server can be enabled to project signed service account tokens that can be used to assume an AWS Identity and Access Management (IAM) role in a pod. If the assumed IAM role has the required AWS permissions, the pods can authenticate against the AWS API using temporary STS credentials to perform AWS operations.
 endif::openshift-rosa[]
 
-You can use the pod identity webhook to enable a service account to automatically assume an AWS Identity and Access Management (IAM) role in your own pods. If the assumed IAM role has the required AWS permissions, the pods can run AWS SDK operations by using temporary STS credentials.
+You can use the pod identity webhook to project service account tokens to assume an AWS Identity and Access Management (IAM) role for your own workloads. If the assumed IAM role has the required AWS permissions, the pods can run AWS SDK operations by using temporary STS credentials.
 
+include::modules/how-service-accounts-assume-aws-iam-roles-in-sre-owned-projects.adoc[leveloffset=+1]
 include::modules/understanding-pod-identity-webhook-workflow-in-user-defined-projects.adoc[leveloffset=+1]
 include::modules/assuming-an-aws-iam-role-in-your-own-pods.adoc[leveloffset=+1]
 include::modules/setting-up-an-aws-iam-role-a-service-account.adoc[leveloffset=+2]
diff --git a/modules/how-service-accounts-assume-aws-iam-roles-in-sre-owned-projects.adoc b/modules/how-service-accounts-assume-aws-iam-roles-in-sre-owned-projects.adoc
@@ -0,0 +1,52 @@
+// Module included in the following assemblies:
+//
+// * authentication/assuming-an-aws-iam-role-for-a-service-account.adoc
+// * rosa_architecture/rosa_policy_service_definition/rosa-sre-access.adoc
+
+:_content-type: CONCEPT
+[id="how-service-accounts-assume-aws-iam-roles-in-sre-owned-projects_{context}"]
+= How service accounts assume AWS IAM roles in SRE owned projects
+
+When you install a {product-title} cluster that uses the AWS Security Token Service (STS), cluster-specific Operator AWS Identity and Access Management (IAM) roles are created. These IAM roles permit the {product-title} cluster Operators to run core OpenShift functionality.
+
+Cluster Operators use service accounts to assume IAM roles. When a service account assumes an IAM role, temporary STS credentials are provided for the service account to use in the cluster Operator's pod. If the assumed role has the necessary AWS privileges, the service account can run AWS SDK operations in the pod.
+
+[discrete]
+[id="workflow-for-assuming-aws-iam-roles-in-sre-owned-projects_{context}"]
+== Workflow for assuming AWS IAM roles in SRE owned projects
+
+// The following diagram illustrates the workflow by which the service accounts for cluster Operators assume IAM roles:
+//
+// .Workflow for assuming AWS IAM roles in SRE-owned projects 
+// TODO: Add diagram.
+
+The workflow has the following stages:
+
+. Within each project that a cluster Operator runs, the Operator's deployment spec has a volume mount for the projected service account token, and a secret containing AWS credential configuration for the pod. The token is audience-bound and time-bound. Every hour, {product-title} generates a new token, and the AWS SDK reads the mounted secret containing the AWS credential configuration. This configuration has a path to the mounted token and the AWS IAM Role ARN. The secret's credential configuration includes the following:
+
+** An `$AWS_ARN_ROLE` variable that has the ARN for the IAM role that has the permissions required to run AWS SDK operations.
+
+** An `$AWS_WEB_IDENTITY_TOKEN_FILE` variable that has the full path in the pod to the OpenID Connect (OIDC) token for the service account. The full path is `/var/run/secrets/openshift/serviceaccount/token`.
+
+. When a cluster Operator needs to assume an AWS IAM role to access an AWS service (such as EC2), the AWS SDK client code running on the Operator invokes the `AssumeRoleWithWebIdentity` API call.
+
+. The OIDC token is passed from the pod to the OIDC provider. The provider authenticates the service account identity if the following requirements are met:
+
+** The identity signature is valid and signed by the private key.
+
+** The `sts.amazonaws.com` audience is listed in the OIDC token and matches the audience configured in the OIDC provider.
++
+[NOTE]
+====
+In {product-title} with STS clusters, the OIDC provider is created during install and set as the service account issuer by default. The `sts.amazonaws.com` audience is set by default in the OIDC provider.
+====
+
+** The OIDC token has not expired.
+
+** The issuer value in the token has the URL for the OIDC provider.
+
+. If the project and service account are in the scope of the trust policy for the IAM role that is being assumed, then authorization succeeds.
+
+. After successful authentication and authorization, temporary AWS STS credentials in the form of an AWS access token, secret key, and session token are passed to the pod for use by the service account. By using the credentials, the service account is temporarily granted the AWS permissions enabled in the IAM role.
+
+. When the cluster Operator runs, the Operator that is using the AWS SDK in the pod consumes the secret that has the path to the projected service account and AWS IAM Role ARN to authenticate against the OIDC provider. The OIDC provider returns temporary STS credentials for authentication against the AWS API.
diff --git a/modules/understanding-pod-identity-webhook-workflow-in-user-defined-projects.adoc b/modules/understanding-pod-identity-webhook-workflow-in-user-defined-projects.adoc
@@ -3,8 +3,8 @@
 // * authentication/assuming-an-aws-iam-role-for-a-service-account.adoc
 
 :_content-type: CONCEPT
-[id="understanding-pod-identity-webhook-workflow-in-user-defined-projects_{context}"]
-= Understanding the pod identity webhook workflow in user-defined projects
+[id="how-service-accounts-assume-aws-iam-roles-in-user-defined-projects_{context}"]
+= How service accounts assume AWS IAM roles in user-defined projects
 
 When you install a {product-title} cluster 
 ifdef::openshift-rosa[]
diff --git a/osd_architecture/osd_policy/osd-sre-access.adoc b/osd_architecture/osd_policy/osd-sre-access.adoc
@@ -1,7 +1,7 @@
-////
 :_content-type: ASSEMBLY
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: osd-sre-access
 [id="osd-sre-access"]
 = SRE and service account access
-////
+
+include::modules/how-service-accounts-assume-aws-iam-roles-in-sre-owned-projects.adoc[leveloffset=+1]
diff --git a/rosa_architecture/rosa_policy_service_definition/rosa-sre-access.adoc b/rosa_architecture/rosa_policy_service_definition/rosa-sre-access.adoc
@@ -8,3 +8,10 @@ Red Hat site reliability engineering (SRE) access to ROSA clusters is outlined t
 
 include::modules/rosa-policy-identity-access-management.adoc[leveloffset=+1]
 include::modules/rosa-sre-access-privatelink-vpc.adoc[leveloffset=+1]
+include::modules/how-service-accounts-assume-aws-iam-roles-in-sre-owned-projects.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* For more information about the AWS IAM roles used by the cluster Operators, see xref:../../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-operator-roles_rosa-sts-about-iam-resources[Cluster-specific Operator IAM role reference].
+* For more information about the policies and permissions that the cluster Operators require, see xref:../../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies-creation-methods_rosa-sts-about-iam-resources[Methods of account-wide role creation].
