Containers

Amazon EKS Pod Identity streamlines cross account access

This post was co-authored by Ashok Srirama, Principal Container Specialist SA and George John, Senior Product Manager EKS. 

Introduction

Today, we’re excited to announce a significant enhancement to Amazon EKS Pod Identity –streamlined cross-account access for Kubernetes applications. This new feature simplifies the process of granting pods permission to access AWS resources in other accounts. By allowing you to specify both a source and target IAM role during Pod Identity association creation, we’ve eliminated the need for complex configurations and application-level changes. This means your Kubernetes applications can now seamlessly access resources across AWS accounts without any code modifications. The feature leverages IAM role chaining behind the scenes, automatically providing the necessary cross-account temporary credentials to your pods at runtime.

At re:Invent 2023, Amazon Elastic Kubernetes Service (Amazon EKS) introduced the EKS Pod Identity feature, enabling users to configure Kubernetes applications running on Amazon EKS with fine-grained AWS Identity and Access Management (IAM) permissions to access AWS resources such as Amazon S3 buckets and Amazon DynamoDB tables. This feature addressed many of the existing challenges of IAM Roles for Service accounts, an alternative mechanism to configure IAM permissions for Kubernetes applications, by eliminating the need to set up OIDC providers for EKS clusters, streamlining IAM trust policies, and streamlining the experience through Amazon EKS APIs. Furthermore, it introduced support for IAM role session tags, allowing IAM administrators to author a single permission policy that can work across roles by allowing access to AWS resources based on matching tags.

But our journey didn’t stop at the launch of the Pod Identity feature. Through continuous user feedback, we learned that multi-account strategies are common among Amazon EKS users, where workloads in one AWS account need to access resources in another. Common scenarios include the following:

  • Platform teams managing centralized multi-tenant EKS clusters in their AWS account, while Business Unit/Application teams operate in separate AWS Accounts. For example, a platform team might maintain a shared EKS cluster for micro services, while individual application teams deploy their micro services to the shared EKS cluster but store their data and configuration in their respective AWS accounts, necessitating secure cross-account access.
  • Centralized CI/CD platforms running on Amazon EKS that need to access resources across multiple AWS accounts. This includes deploying applications to different environments (dev, staging, and prod), and accessing artifact repositories stored in different AWS accounts.
  • Data APIs hosted on EKS clusters needing access to data lakes in other AWS Accounts. For example, analytical workloads running on Amazon EKS might need to process data from multiple business units’ data stores while maintaining data isolation and governance.

EKS Pod Identity supports the following approaches for enabling cross-account access:

  • Resource-based policies: Allows you to directly grant permissions to Amazon EKS pods in one account to access resources in another account by configuring policies on the target resources (such as S3 buckets or DynamoDB tables).
  • IAM role chaining: Enables pods to assume roles in other accounts through a trust relationship between roles, where the pod first assumes a role in its account, which has permissions to assume roles in target accounts.
  • IAM role chaining with AWS Config: Streamline role chaining configuration by specifying cross-account role details in the AWS SDK config file, allowing you to more directly manage and update role associations

For a comprehensive understanding of these approaches and their implementation details, refer to the section “How to perform cross account access with Amazon EKS Pod Identity” in the previous post Amazon EKS Pod Identity: a new way for applications on EKS to obtain IAM credentials. Although these approaches work, they need advanced IAM configurations and application-level changes that can be challenging to maintain at scale.

To address these challenges and support cross-account use cases more seamlessly, we are launching a new streamlined cross account experience with EKS Pod Identity. EKS Pod Identity enables applications in your EKS cluster to access AWS resources across accounts through a process called IAM role chaining. When creating a Pod Identity association, you can provide two IAM roles: an EKS Pod Identity role in the same account as your EKS cluster, and a target IAM role from the account containing your AWS resources (such as S3 buckets or DynamoDB tables). When your application pod needs to access AWS resources, it requests credentials from the EKS Pod Identity, which automatically assumes the roles through IAM role chaining to provide your pod with the necessary cross-account temporary credentials. Furthermore, this feature maintains support for IAM role session tags, enabling fine-grained access control based on pod metadata across accounts.

What is changing in EKS Pod Identity APIs

The following APIs are updated to introduce new request and response elements to pass target role Amazon Resource Names (ARNs).

  • CreatePodIdentityAssociation: API call to create an EKS Pod Identity association between a service account in an EKS cluster and an IAM role with EKS Pod Identity.
    • Request parameters
      • Name: The name of the cluster in which to create the association.
      • Namespace: The name of the Kubernetes namespace inside the cluster in which to create the association. The service account and the pods that use the service account must be in this namespace.
      • roleArn: The ARN of the IAM role to associate with the service account. The EKS Pod Identity agent manages credentials to assume this role for applications in the containers in the pods that use this service account.
      • targetRoleArn: The ARN of the target AWS account IAM role to associate with the service account. EKS Pod Identity issues the temporary IAM credentials of this role.
      • serviceAccount: The name of the Kubernetes service account inside the cluster with which to associate the IAM credentials.
      • disableSessionTags: Boolean flag to enable or disable session tags. Default is False
  • UpdatePodIdentityAssociation: API to update an existing pod identity association. Use this to update the IAM role, target IAM role, or disableSessionTags attributes of the association. At least one of these attributes must be present in the request. An association can’t be moved between clusters, namespaces, or service accounts. If you need to edit the namespace or service account, then you must first remove the existing association and then create a new one with your desired settings.
    • name: The name of the cluster where the association exists.
    • associationId: The ID of the association to be updated.
    • roleArn: The new IAM role to associate with the service account.
    • targetRoleArn: The new target IAM role to associate with the service account.
    • disableSessionTags: Boolean flag to enable or disable session tags.

How to get started

In this walkthrough, we demonstrate how a Kubernetes pod running in an EKS cluster in source account, AWS Account A, can access other AWS resources in a target account, AWS Account B, as shown in the following figure.

Figure 1: High level workflow performed by the EKS Pod Identity to provide temporary STS credentials to the Kubernetes pod

Figure 1: High level workflow performed by the EKS Pod Identity to provide temporary STS credentials to the Kubernetes pod.

The high-level flow is as follows:

  1. A platform Amazon EKS user creates an IAM role (account-a-role) in the AWS Account A with a trust policy to allow AssumeRole from pods.eks.amazonaws.com service principal and permission policy to assume role (account-b-role) in Account B.
  2. An application/BU user creates an IAM role (account-b-role) in AWS Account B with a trust policy to allow AssumeRole from account-a-role and appropriate permission policy.
  3. A platform Amazon EKS user creates pod identity association to associate the IAM roles from both accounts to the Kubernetes service account.
  4. The EKS Pod Identity Webhook in the Amazon EKS control plane mutates the Kubernetes pod spec with appropriate environment variables.
  5. When the application tries to retrieve temporary IAM credentials, SDK uses the environment variables to call the eks-pod-identity-agent endpoint to fetch the credentials. EKS Pod Identity agent calls the EKS Auth API, which validates the associations, performs the IAM role chaining operation, and returns the credentials in the response.
  6. The application uses temporary IAM credentials to access AWS resources (such as Amazon S3 and DynamoDB) in AWS Account B.

Prerequisites

The following prerequisites are necessary to complete this solution:

Setup

export AWS_REGION=us-west-2 #Replace with your AWS Region
export AWS_ACCOUNT_A=111122223333 #Replace with your AWS Account number
export AWS_ACCOUNT_B=999988887777 #Replace with your AWS Account number
export CLUSTER_NAME=eks-pod-identity-xacct-demo #Replace with your EKS cluster name
export ACCT_A_PROFILE=<<Name of the AWS CLI Profile for account A>>
export ACCT_B_PROFILE=<<Name of the AWS CLI Profile for account B>>

Initial Setup in AWS Account A (EKS cluster account)

Start by creating an EKS cluster using eksctl with the eks-pod-identity-agent add-on. Create an eksctl config file using the following command:

cat << EOF > cluster.yaml 
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: ${CLUSTER_NAME}
  region: ${AWS_REGION}
  version: "1.32"

addons:
  - name: vpc-cni
  - name: coredns
  - name: kube-proxy
  - name: eks-pod-identity-agent
    
managedNodeGroups:
  - name: ${CLUSTER_NAME}-mng
    instanceType: m6a.large
    privateNetworking: true
    minSize: 2
    desiredCapacity: 2
    maxSize: 5
EOF

Create the EKS cluster using the eksctl command.

eksctl create cluster -f cluster.yaml --profile $ACCT_A_PROFILE

Wait for cluster creation to be complete and make sure that the eks-pod-identity-agent add-on is running in the cluster.

eksctl get addon --cluster ${CLUSTER_NAME} --region ${AWS_REGION} --name eks-pod-identity-agent --profile $ACCT_A_PROFILE -o json

You should see the following output:

[
    {
        "Name": "eks-pod-identity-agent",
        "Version": "v1.3.5-eksbuild.2",
        "NewerVersion": "",
        "IAMRole": "",
        "Status": "ACTIVE",
        "ConfigurationValues": "",
        "Issues": null
    }
]

Create the necessary IAM resources to make the cross account access possible. You need an IAM role in the target AWS Account that has permissions to the necessary AWS resources and an IAM role in the source AWS Account that has permission to assume the target account’s IAM role. Therefore, create the IAM role in the source AWS account.

Create an IAM role (account-a-role) with a permission policy to assume the IAM role (account-b-role) in the target AWS Account.

cat << EOF > role_a_permission_policy.json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole",
                "sts:TagSession"
            ],
            "Resource": [
                "arn:aws:iam::${AWS_ACCOUNT_B}:role/account-b-role"
            ]
        }
    ]
}
EOF
cat << EOF > role_a_trust_policy.json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "pods.eks.amazonaws.com"
            },
            "Action": [
                "sts:AssumeRole",
                "sts:TagSession"
            ]
        }
    ]
}
EOF
aws iam create-policy --policy-document file://role_a_permission_policy.json \
    --policy-name eks-pod-identity-xacct-policy --profile $ACCT_A_PROFILE
    
aws iam create-role --role-name account-a-role \
    --assume-role-policy-document file://role_a_trust_policy.json \
    --profile $ACCT_A_PROFILE
    
aws iam attach-role-policy --role-name account-a-role \
    --policy-arn arn:aws:iam::${AWS_ACCOUNT_A}:policy/eks-pod-identity-xacct-policy \
    --profile $ACCT_A_PROFILE

Setup in AWS Account B

Similarly in Account B, create an IAM role (account-b-role) with a permission policy that gives access to appropriate resources in the target account. For demonstration purposes, you use the AmazonS3ReadOnlyAccess permission policy. There are multiple approaches to author the trust policies: you can either establish the trust with specific IAM roles in the source account or with the entire AWS Account. The latter approach is beneficial if you don’t have visibility into IAM roles in the source account and would rather give the responsibility to the source account owners, such as the Platform team, to manage those permissions. They would need to manage the permission policies so that only the appropriate roles can assume these roles in Account B.

In either case, it’s recommended to use an external ID as part of the trust policy to mitigate the confused deputy problem. The confused deputy problem is a security issue where an entity that doesn’t have permission to perform an action can coerce a more-privileged entity to perform the action. To mitigate this risk, EKS Pod Identity automatically injects an externalId in the cross-account AssumeRole API call using the following format: region/account-a-id/cluster-name/namespace/service-account-name. 

cat << EOF > role_b_trust_policy.json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::${AWS_ACCOUNT_A}:role/account-a-role"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "${AWS_REGION}/${AWS_ACCOUNT_A}/${CLUSTER_NAME}/default/demo-app-sa"
                }
            }
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::${AWS_ACCOUNT_A}:role/account-a-role"
            },
            "Action": "sts:TagSession"
        }
    ]
}
EOF
    
aws iam create-role --role-name account-b-role \
    --assume-role-policy-document file://role_b_trust_policy.json \
    --profile $ACCT_B_PROFILE
    
aws iam attach-role-policy --role-name account-b-role \
    --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \
    --profile $ACCT_B_PROFILE

Complete the AWS Account A configuration

Now that you have created the necessary IAM roles, use the EKS Pod Identity to associate the source and target account IAM roles to the Kubernetes service account used by your demo application. Notice a new attribute in the CreatePodIdentityAssociation API to pass the target account IAM role.

aws eks create-pod-identity-association --region $AWS_REGION \
    --cluster-name $CLUSTER_NAME \
    --service-account demo-app-sa --namespace default \
    --role-arn arn:aws:iam::${AWS_ACCOUNT_A}:role/account-a-role \
    --target-role-arn arn:aws:iam::${AWS_ACCOUNT_B}:role/account-b-role \
    --profile $ACCT_A_PROFILE

Expected output:

{
    "association": {
        "clusterName": "eks-pod-identity-xacct-demo",
        "namespace": "default",
        "serviceAccount": "demo-app-sa",
        "roleArn": "arn:aws:iam::111122223333:role/account-a-role",
        "associationArn": "arn:aws:eks:us-west-2:111122223333:podidentityassociation/eks-pod-identity-xacct-demo/a-hw7ewqqhtvfqjkx7r",
        "associationId": "a-hw7ewqqhtvfqjkx7r",
        "tags": {},
        "createdAt": "2025-03-03T19:52:49.103000+00:00",
        "modifiedAt": "2025-03-03T19:52:49.103000+00:00",
        "disableSessionTags": false,
        "targetRoleArn": "arn:aws:iam::999988887777:role/account-b-role",
        "externalId": "us-west-2/111122223333/eks-pod-identity-xacct-demo/default/demo-app-sa"
    }
}

In the response, an externalId is returned in the following format: region/account-number/cluster-name/namespace/service-account-name, along with associationId, etc. You already used this to create the condition statement in the target IAM role trust policy to mitigate the confused deputy problem. This completes the necessary infrastructure setup. Deploy the sample application with the demo-app-sa service account in the default namespace.

kubectl create sa demo-app-sa

kubectl run awscli \
  --image=amazon/aws-cli:latest \
  --restart=Never \
  --command \
  --overrides='{ "spec": { "serviceAccountName": "demo-app-sa" }}' \
  -- sleep infinity

When the pod is up and running, run the following commands to confirm the IAM session credentials. You should observe that the EKS Pod Identity automatically provided the session credentials for the target AWS account’s IAM role by performing role chaining.

Validate if the Pod is running.

kubectl get pods

Expected output:

NAME       READY      STATUS      RESTARTS      AGE
aws-cli    1/1        Running     0             4m

Run the aws-cli command to validate the Assumed Role.

kubectl exec awscli -- /bin/bash -c "aws sts get-caller-identity"

Expected output:

{
    "UserId": "AROA43MFJ4FMNLTSEPVJ5:..........",
    "Account": "999988887777",
    "Arn": "arn:aws:sts::999988887777:assumed-role/account-b-role/eks-eks-po-ide-awscli-8dbbcff5-9716-40c5-a474-c01c3190deeb"
}

Try listing the S3 buckets in the Target Account.

kubectl exec awscli -- /bin/bash -c "aws s3 ls"

Expected output:

<<list of S3 buckets from the target AWS Account>>

This demonstrates how the Amazon EKS workloads can use the new EKS Pod Identity cross account feature to securely access resources in other AWS accounts.

Cleaning up

To avoid ongoing charges, make sure to delete the EKS cluster resources created in your AWS account.

eksctl delete cluster -f cluster.yaml --profile $ACCT_A_PROFILE

# Delete IAM Resources in Account A
aws iam detach-role-policy --role-name account-a-role \
    --policy-arn arn:aws:iam::${AWS_ACCOUNT_A}:policy/eks-pod-identity-xacct-policy \
    --profile $ACCT_A_PROFILE 
    
aws iam delete-role --role-name account-a-role --profile $ACCT_A_PROFILE

aws iam delete-policy --policy-arn arn:aws:iam::${AWS_ACCOUNT_A}:policy/eks-pod-identity-xacct-policy \
    --profile $ACCT_A_PROFILE 

# Delete IAM Resources in Account B
aws iam detach-role-policy --role-name account-b-role \
    --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \
   --profile $ACCT_B_PROFILE
   
iam delete-role --role-name account-b-role --profile $ACCT_B_PROFILE

Considerations

  • The EKS Pod Identity cross account feature is supported on all Kubernetes versions supported in Amazon EKS as of this writing.
  • EKS Pod Identity cross account feature is available in all AWS Commercial, Mainland China, and AWS GovCloud (US) Regions where Amazon EKS is supported.
  • You can associate only one IAM role to a Kubernetes service account using EKS Pod Identity feature. However, you can update the role associations any time.
  • You can use AWS CloudFormation support, AWS CLI, and Amazon EKS API to create cross account pod identity associations. Terraform and eksctl support will be added later.
  • When EKS Pod Identity assumes a role, it automatically adds session tags. These tags, along with inline session policies and managed policy ARNs, are compressed into a packed binary format that has a size limit. If you encounter a PackedPolicyTooLarge error because of exceeding this size limit, then you can reduce the packed binary size by disabling the session tags. Disable them by using --disable-session-tags in the create-pod-identity-association or update-pod-identity-association API calls.

Conclusion

In this post, we demonstrated the new cross-account capabilities of Amazon EKS Pod Identity, which streamlines how Amazon EKS workloads can securely access AWS resources across AWS accounts. This feature eliminates the complexity of traditional cross-account access methods by providing a streamlined experience through Amazon EKS APIs. Whether you’re running a centralized platform team, managing CI/CD pipelines, or building data APIs, EKS Pod Identity now offers a more direct and maintainable approach to cross-account access. We encourage you to start using this feature, and leave us feedback at AWS Containers Roadmap.