1. 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, ROSA 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.
2. 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.

3. 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 ROSA 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.
4. 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.
5. 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.
6. 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.

1. Within a user-defined project, a user creates a service account that includes an eks.amazonaws.com/role-arn annotation. The annotation points to the ARN of the AWS IAM role that you want your service account to assume.

2. When a pod is deployed in the same project using a configuration that references the annotated service account, the pod identity webhook mutates the pod. The mutation injects the following components into the pod without the need to specify them in your Pod or Deployment resource configurations:

   • An $AWS_ARN_ROLE environment variable that contains the ARN for the IAM role that has the permissions required to run AWS SDK operations.
   • An $AWS_WEB_IDENTITY_TOKEN_FILE environment variable that contains the full path in the pod to the OpenID Connect (OIDC) token for the service account. The full path is /var/run/secrets/eks.amazonaws.com/serviceaccount/token.
   • An aws-iam-token volume mounted on the mount point /var/run/secrets/eks.amazonaws.com/serviceaccount. An OIDC token file named token is contained in the volume.

3. 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

     The pod identity webhook applies the sts.amazonaws.com audience to the OIDC token by default.

   • The OIDC token has not expired.
   • The issuer value in the token contains the URL for the OIDC provider.
4. 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.
5. After successful authentication and authorization, temporary AWS STS credentials in the form of a 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.
6. When you run AWS SDK operations in the pod, the service account provides the temporary STS credentials to the AWS API to verify its identity.

Procedure

1. Create a file named trust-policy.json with the following JSON configuration:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "Federated": "<oidc_provider_arn>"
               },
               "Action": "sts:AssumeRoleWithWebIdentity",
               "Condition": {
                   "StringEquals": {
                       "<oidc_provider_name>:sub": "system:serviceaccount:<project_name>:<service_account_name>"
                   }
               }
           }
       ]
   }

   where, <oidc_provider_arn>

   Replace <oidc_provider_arn> with the ARN of your OIDC provider, for example, arn:aws:iam::<aws_account_id>:oidc-provider/rh-oidc.s3.us-east-1.amazonaws.com/1v3r0n44npxu4g58so46aeohduomfres. You can retrieve the ARN by using the rosa describe cluster CLI command.

   <oidc_provider_name>

   Replace <oidc_provider_name> with the name of your OIDC provider, for example rh-oidc.s3.us-east-1.amazonaws.com/1v3r0n44npxu4g58so46aeohduomfres.

   <project_name>:<service_account_name>

   Replace <project_name>:<service_account_name> with your project name and service account name, for example my-project:test-service-account. This action limits the role to the specified project and service account.

   Note

   Alternatively, you can limit the role to any service account within the specified project by using "<oidc_provider_name>:sub": "system:serviceaccount:<project_name>:*". If you supply the * wildcard, you must replace StringEquals with StringLike in the preceding line.

2. Create an AWS IAM role that uses the trust policy that is defined in the trust-policy.json file:

   $ aws iam create-role \
       --role-name <aws_iam_role_name> \
       --assume-role-policy-document file://trust-policy.json

   Replace <aws_iam_role_name> with the name of your IAM role, for example pod-identity-test-role and use the trust-policy.json file that you created in the preceding step.

   Example output

   ROLE    arn:aws:iam::<aws_account_id>:role/<aws_iam_role_name>        2022-09-28T12:03:17+00:00       /       AQWMS3TB4Z2N3SH7675JK   <aws_iam_role_name>
   ASSUMEROLEPOLICYDOCUMENT        2012-10-17
   STATEMENT       sts:AssumeRoleWithWebIdentity   Allow
   STRINGEQUALS    system:serviceaccount:<project_name>:<service_account_name>
   PRINCIPAL       <oidc_provider_arn>

   Retain the ARN for the role in the output. The format of the role ARN is arn:aws:iam::<aws_account_id>:role/<aws_iam_role_name>.

3. Attach any managed AWS permissions that are required when the service account runs AWS SDK operations in your pod. The policy in this example adds read-only access permissions to the IAM role.

   $ aws iam attach-role-policy \
       --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess \
       --role-name <aws_iam_role_name> 1

   Replace <aws_iam_role_name> with the name of the IAM role that you created in the preceding step.

4. Optional: Add custom attributes or a permissions boundary to the role. For more information, see Creating a role to delegate permissions to an AWS service in the AWS documentation.

Procedure

1. In your Red Hat OpenShift Service on AWS cluster, create a project:

   $ oc new-project <project_name>

   Replace <project_name> with the name of your project. The name must match the project name that you specified in your AWS IAM role configuration.

   Note

   You are automatically switched to the project when it is created.

2. Create a file named test-service-account.yaml with the following service account configuration:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: <service_account_name>
     namespace: <project_name>
     annotations:
       eks.amazonaws.com/role-arn: "<aws_iam_role_arn>"

   where, <service_account_name>

   Replace <service_account_name> with the name of your service account. The name must match the service account name that you specified in your AWS IAM role configuration.

   <project_name>

   Replace <project_name> with the name of your project. The name must match the project name that you specified in your AWS IAM role configuration.

   <aws_iam_role_arn>

   Specifies the ARN of the AWS IAM role that the service account assumes for use within your pod. Replace <aws_iam_role_arn> with the ARN for the AWS IAM role that you created for your service account. The format of the role ARN is arn:aws:iam::<aws_account_id>:role/<aws_iam_role_name>.

3. Create the service account in your project:

   $ oc create -f test-service-account.yaml

   Example output

   serviceaccount/<service_account_name> created

4. Review the details of the service account:

   $ oc describe serviceaccount <service_account_name>

   Replace <service_account_name> with the name of your service account.

   Example output

   Name:                <service_account_name>
   Namespace:           <project_name> 1
   Labels:              <none>
   Annotations:         eks.amazonaws.com/role-arn: <aws_iam_role_arn> 2
   Image pull secrets:  <service_account_name>-dockercfg-rnjkq
   Mountable secrets:   <service_account_name>-dockercfg-rnjkq
   Tokens:              <service_account_name>-token-4gbjp
   Events:              <none>

   where, <service_account_name>

   Specifies the name of the service account.

   <project_name>

   Specifies the project that contains the service account.

   <aws_iam_role_arn>

   Lists the annotation for the ARN of the AWS IAM role that the service account assumes.

Procedure

1. Add the following configuration to a file named Containerfile:

   FROM ubi9/ubi
   RUN dnf makecache && dnf install -y python3-pip && dnf clean all && pip3 install boto3>=1.15.0

   where, FROM ubi9/ubi

   Specifies the Red Hat Universal Base Image version 9 as the base image for the container image.

   RUN dnf makecache && dnf install -y python3-pip && dnf clean all && pip3 install boto3>=1.15.0

   Installs the AWS Boto3 SDK by using the pip package management system. In this example, AWS Boto3 SDK version 1.15.0 or later is installed.

2. From the directory that contains the file, build a container image named awsboto3sdk:

   $ podman build -t awsboto3sdk .

3. Log in to Quay.io:

   $ podman login quay.io

4. Tag the image in preparation for the upload to Quay.io:

   $ podman tag localhost/awsboto3sdk quay.io/<quay_username>/awsboto3sdk:latest

   Replace <quay_username> with your Quay.io username.

5. Push the tagged container image to Quay.io:

   $ podman push quay.io/<quay_username>/awsboto3sdk:latest

   Replace <quay_username> with your Quay.io username.

6. Make the Quay.io repository that contains the image public. This publishes the image so that it can be used to deploy a pod in your Red Hat OpenShift Service on AWS cluster:

   1. On https://quay.io/, navigate to the Repository Settings page for repository that contains the image.
   2. Click Make Public to make the repository publicly available.

Procedure

1. Create a file named awsboto3sdk-pod.yaml with the following pod configuration. In this example pod configuration, the sleep 100000 line keeps the pod running for 100000 seconds to enable verification testing in the pod directly. For detailed verification steps, see Verifying the assumed IAM role in your pod.

   apiVersion: v1
   kind: Pod
   metadata:
     namespace: <project_name>
     name: awsboto3sdk
   spec:
     securityContext:
       runAsNonRoot: true
       seccompProfile:
         type: RuntimeDefault
     serviceAccountName: <service_account_name>
     containers:
     - name: awsboto3sdk
       image: quay.io/<quay_username>/awsboto3sdk:latest
       command:
       - /bin/bash
       - "-c"
       - "sleep 100000"
       securityContext:
         allowPrivilegeEscalation: false
         capabilities:
           drop: [ALL]
     terminationGracePeriodSeconds: 0
     restartPolicy: Never

   where, <project_name>

   Replace <project_name> with the name of your project. The name must match the project name that you specified in your AWS IAM role configuration.

   <service_account_name>

   Replace <service_account_name> with the name of the service account that is configured to assume the AWS IAM role. The name must match the service account name that you specified in your AWS IAM role configuration.

   <quay_username>

   Replace <quay_username> with your Quay.io username to specify the location of your awsboto3sdk container image.

2. Deploy an awsboto3sdk pod:

   $ oc create -f awsboto3sdk-pod.yaml

   Example output

   pod/awsboto3sdk created

Procedure

1. Verify that the AWS environment variables, the volume mount, and the OIDC token volume are listed in the description of the deployed awsboto3sdk pod:

   $ oc describe pod awsboto3sdk

   Example output

   Name:         awsboto3sdk
   Namespace:    <project_name>
   ...
   Containers:
     awsboto3sdk:
       ...
       Environment:
         AWS_ROLE_ARN:                 <aws_iam_role_arn> 1
         AWS_WEB_IDENTITY_TOKEN_FILE:  /var/run/secrets/eks.amazonaws.com/serviceaccount/token 2
       Mounts:
         /var/run/secrets/eks.amazonaws.com/serviceaccount from aws-iam-token (ro) 3
   ...
   Volumes:
     aws-iam-token: 4
       Type:                    Projected (a volume that contains injected data from multiple sources)
       TokenExpirationSeconds:  86400
   ...

   where, <project_name>

   The name of your project.

   <aws_iam_role_arn>

   Lists the AWS_ROLE_ARN environment variable that was injected into the pod by the pod identity webhook. The variable contains the ARN of the AWS IAM role to be assumed by the service account.

   <aws_web_identity_token_file>

   Lists the AWS_WEB_IDENTITY_TOKEN_FILE environment variable that was injected into the pod by the pod identity webhook. The variable contains the full path of the OIDC token that is used to verify the service account identity.

   Mounts

   Lists the volume mounts for the pod. The aws-iam-token volume mount that was injected into the pod by the pod identity webhook is listed here.

   <aws-iam-token>

   Lists the aws-iam-token volume that is mounted onto the /var/run/secrets/eks.amazonaws.com/serviceaccount mount point. The volume contains the OIDC token that is used to authenticate the service account to assume the AWS IAM role.

2. Start an interactive terminal in the awsboto3sdk pod:

   $ oc exec -ti awsboto3sdk -- /bin/sh

3. In the interactive terminal for the pod, verify that the $AWS_ROLE_ARN environment variable was mutated into the pod by the pod identity webhook:

   $ echo $AWS_ROLE_ARN

   Example output

   arn:aws:iam::<aws_account_id>:role/<aws_iam_role_name>

   The output must specify the ARN for the AWS IAM role that has the permissions required to run AWS SDK operations.

4. In the interactive terminal for the pod, verify that the $AWS_WEB_IDENTITY_TOKEN_FILE environment variable was mutated into the pod by the pod identity webhook:

   $ echo $AWS_WEB_IDENTITY_TOKEN_FILE

   Example output

   /var/run/secrets/eks.amazonaws.com/serviceaccount/token

   The output must specify the full path in the pod to the OIDC token for the service account.

5. In the interactive terminal for the pod, verify that the aws-iam-token volume mount containing the OIDC token file was mounted by the pod identity webhook:

   $ mount | grep -is 'eks.amazonaws.com'

   Example output

   tmpfs on /run/secrets/eks.amazonaws.com/serviceaccount type tmpfs (ro,relatime,seclabel,size=13376888k)

6. In the interactive terminal for the pod, verify that an OIDC token file named token is present on the /var/run/secrets/eks.amazonaws.com/serviceaccount/ mount point:

   $ ls /var/run/secrets/eks.amazonaws.com/serviceaccount/token

   Example output

   /var/run/secrets/eks.amazonaws.com/serviceaccount/token 1

   The OIDC token file in the aws-iam-token volume that was mounted in the pod by the pod identity webhook. The token is used to authenticate the identity of the service account in AWS.

7. In the pod, verify that AWS Boto3 SDK operations run successfully:

   1. In the interactive terminal for the pod, start a Python 3 shell:

      $ python3

   2. In the Python 3 shell, import the boto3 module:

      >>> import boto3

   3. Create a variable that includes the Boto3 s3 service resource:

      >>> s3 = boto3.resource('s3')

   4. Print the names of all of the S3 buckets in your AWS account:

      >>> for bucket in s3.buckets.all():
      ...     print(bucket.name)
      ...

      Example output

      <bucket_name>
      <bucket_name>
      <bucket_name>
      ...

      If the service account successfully assumed the AWS IAM role, the output lists all of the S3 buckets that are available in your AWS account.