Red Hat OpenShift Container Platform

About assuming AWS IAM roles in your own pods

You can enable a service account to assume an AWS Identity and Access Management (IAM) role in a pod deployed in a user-defined project.

You can create the required resources, including an AWS IAM role, a service account, a container image that includes an AWS SDK, and a pod deployed by using the image. In the example, the AWS Boto3 SDK for Python is used. You can also verify that the pod identity webhook mutates the AWS environment variables, the volume mount, and the token volume into your pod. Additionally, you can check that the service account assumes the AWS IAM role in your pod and can successfully run AWS SDK operations.

Set up an AWS IAM role for a service account

You can create an AWS Identity and Access Management (IAM) role to be assumed by a service account in your Red Hat OpenShift Container Platform cluster that contains the permissions required by your service account to run AWS SDK operations in a pod.

Prerequisites

You have the permissions required to install and configure IAM roles in your AWS account.
You have access to a Red Hat OpenShift Container Platform cluster that uses the AWS Security Token Service (STS). Admin-level user privileges are not required.

You have the Amazon Resource Name (ARN) for the OpenID Connect (OIDC) provider that is configured as the service account issuer in your Red Hat OpenShift Container Platform with STS cluster.

In Red Hat OpenShift Container Platform with STS clusters, the OIDC provider is created during install and set as the service account issuer by default. If you do not know the OIDC provider ARN, contact your cluster administrator.

You have installed the AWS CLI (aws).

Procedure

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.

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.

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

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> 
```
Replace <aws_iam_role_name> with the name of the IAM role that you created in the preceding step.
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.

Create a service account in your project

To allow workloads in a project to assume an AWS Identity and Access Management (IAM) role, you can create a service account configured with your IAM role in that project. By using a service account, you can enable any of the workloads in that project to use the same role by assigning a service account to that workload.

Prerequisites

You have created an AWS IAM role for your service account. For more information, see Setting up an AWS IAM role for a service account.
You have access to a Red Hat OpenShift Container Platform with AWS Security Token Service (STS) cluster. Admin-level user privileges are not required.
You have installed the OpenShift CLI (oc).

Procedure

In your Red Hat OpenShift Container Platform 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.

You are automatically switched to the project when it is created.
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>.

Create the service account in your project:

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

Example output

serviceaccount/<service_account_name> created

Review the details of the service account:

$ oc describe serviceaccount <service_account_name>

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

The output is similar to the following example:

Name:                <service_account_name>
Namespace:           <project_name> 
Labels:              <none>
Annotations:         eks.amazonaws.com/role-arn: <aws_iam_role_arn> 
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.

Create an AWS SDK container image

To deploy pods that can run AWS software development kit (SDK) operations in your cluster, your pods must contain a version of the AWS SDK. You can include an SDK in the container image for use with your pods.

These example steps use Podman to create the container image and Quay.io to host the image. For more information about Quay.io, see Getting Started with Quay.io. The container image can be used to deploy pods that can run AWS SDK operations.

In this example procedure, the AWS Boto3 SDK for Python is installed into a container image. For more information about installing and using the AWS Boto3 SDK, see the AWS Boto3 documentation. For details about other AWS SDKs, see AWS SDKs and Tools Reference Guide in the AWS documentation.

Prerequisites

You have installed Podman on your installation host.
You have a Quay.io user account.

Procedure

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.
From the directory that contains the file, build a container image named awsboto3sdk:
```
$ podman build -t awsboto3sdk .
```
Log in to Quay.io:
```
$ podman login quay.io
```
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.
Push the tagged container image to Quay.io:
```
$ podman push quay.io/<quay_username>/awsboto3sdk:latest
```
Replace <quay_username> with your Quay.io username.
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 Container Platform 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.

Deploy a pod that includes an AWS SDK

To enable your application to automatically assume an AWS Identity and Access Management (IAM) role within a pod, you can assign a previously created service account to the pod so that it can automatically detect which IAM role to assume.

In your pod configuration, specify the service account that includes the eks.amazonaws.com/role-arn annotation. With the service account reference in place for your pod, the pod identity webhook injects the AWS environment variables, the volume mount, and the token volume into your pod. The pod mutation enables the service account to automatically assume the AWS IAM role in the pod.

Prerequisites

You have created an AWS IAM role for your service account. For more information, see Setting up an AWS IAM role for a service account.
You have access to a Red Hat OpenShift Container Platform cluster that uses the AWS Security Token Service (STS). Admin-level user privileges are not required.
You have installed the OpenShift CLI (oc).
You have created a service account in your project that includes an eks.amazonaws.com/role-arn annotation that references the Amazon Resource Name (ARN) for the IAM role that you want the service account to assume.

You have a container image that includes an AWS SDK and the image is available to your cluster. For detailed steps, see Creating an example AWS SDK container image.

In this example procedure, the AWS Boto3 SDK for Python is used. For more information about installing and using the AWS Boto3 SDK, see the AWS Boto3 documentation. For details about other AWS SDKs, see AWS SDKs and Tools Reference Guide in the AWS documentation.

Procedure

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.
Deploy an awsboto3sdk pod:
```
$ oc create -f awsboto3sdk-pod.yaml
```
The output is similar to the following example:
```
pod/awsboto3sdk created
```

Verify the assumed IAM role in your pod

After deploying an awsboto3sdk pod in your project, verify that the pod identity webhook has mutated the pod and check that the required AWS environment variables, volume mount, and OpenID Connect (OIDC) token volume are present within the pod.

You can also verify that the service account assumes the AWS Identity and Access Management (IAM) role for your AWS account when you run AWS SDK operations in the pod.

Prerequisites

You have created an AWS IAM role for your service account. For more information, see Setting up an AWS IAM role for a service account.
You have access to a Red Hat OpenShift Container Platform cluster that uses the AWS Security Token Service (STS). Admin-level user privileges are not required.
You have installed the OpenShift CLI (oc).
You have created a service account in your project that includes an eks.amazonaws.com/role-arn annotation that references the Amazon Resource Name (ARN) for the IAM role that you want the service account to assume.

You have deployed a pod in your user-defined project that includes an AWS SDK. The pod references the service account that uses the pod identity webhook to assume the AWS IAM role required to run the AWS SDK operations. For detailed steps, see Deploying a pod that includes an AWS SDK.

In this example procedure, a pod that includes the AWS Boto3 SDK for Python is used. For more information about installing and using the AWS Boto3 SDK, see the AWS Boto3 documentation. For details about other AWS SDKs, see AWS SDKs and Tools Reference Guide in the AWS documentation.

Procedure

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> 
      AWS_WEB_IDENTITY_TOKEN_FILE:  /var/run/secrets/eks.amazonaws.com/serviceaccount/token 
    Mounts:
      /var/run/secrets/eks.amazonaws.com/serviceaccount from aws-iam-token (ro) 
...
Volumes:
  aws-iam-token: 
    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.
Start an interactive terminal in the awsboto3sdk pod:
```
$ oc exec -ti awsboto3sdk -- /bin/sh
```
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.
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.
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)
```
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 
```
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.
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.