Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Access Amazon Resources using EKS Pod Identity Target IAM Roles

When running applications on Amazon Elastic Kubernetes Service (Amazon EKS), you might need to access Amazon resources that exist in the same or different Amazon accounts. This guide shows you how to set up access between these accounts using EKS Pod Identity, which enables your Kubernetes pods to access other Amazon resources.

Prerequisites

Before you begin, ensure you have completed the following steps:

How It Works

Pod Identity enables applications in your EKS cluster to access Amazon resources across accounts through a process called 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 Amazon resources (like S3 buckets or DynamoDB tables). The EKS Pod Identity role must be in your EKS cluster’s account due to IAM PassRole requirements, while the Target IAM Role can be in any Amazon account. PassRole enables an Amazon entity to delegate role assumption to another service. EKS Pod Identity uses PassRole to connect a role to a Kubernetes service account, requiring both the role and the identity passing it to be in the same Amazon account as the EKS cluster. When your application pod needs to access Amazon resources, it requests credentials from Pod Identity. Pod Identity then automatically performs two role assumptions in sequence: first assuming the EKS Pod Identity role, then using those credentials to assume the Target IAM Role. This process provides your pod with temporary credentials that have the permissions defined in the target role, allowing secure access to resources in other Amazon accounts.

Caching considerations

Due to caching mechanisms, updates to an IAM role in an existing Pod Identity association may not take effect immediately in the pods running on your EKS cluster. The Pod Identity Agent caches IAM credentials based on the association’s configuration at the time the credentials are fetched. If the association includes only an EKS Pod Identity role ARN and no Target IAM Role, the cached credentials last for 6 hours. If the association includes both the EKS Pod Identity role ARN and a Target IAM Role, the cached credentials last for 59 minutes. Modifying an existing association, such as updating the EKS Pod Identity role ARN or adding a Target IAM Role, does not reset the existing cache. As a result, the agent will not recognize updates until the cached credentials refresh. To apply changes sooner, you can recreate the existing pods; otherwise, you will need to wait for the cache to expire.

Step 1: Create and associate a Target IAM Role

In this step, you will establish a secure trust chain by creating and configuring a Target IAM Role. For demonstration, we will create a new Target IAM Role to establish a trust chain between two Amazon accounts: the EKS Pod Identity role (e.g., eks-pod-identity-primary-role) in the EKS cluster’s Amazon account gains permission to assume the Target IAM Role (e.g. eks-pod-identity-aws-resources) in your target account, enabling access to Amazon resources like Amazon S3 buckets.

Create the Target IAM Role

Update the Target IAM Role trust policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111122223333:role/eks-pod-identity-primary-role"
            },
            "Action": "sts:AssumeRole",
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111122223333:role/eks-pod-identity-primary-role"
            },
            "Action": "sts:TagSession"
        }
    ]
}

Update the permission policy for EKS Pod Identity role

In this step, you will update the permission policy of the EKS Pod Identity role associated with your Amazon EKS cluster by adding the Target IAM Role ARN as a resource.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole",
                "sts:TagSession"
            ],
            "Resource": "arn:aws:iam::222233334444:role/eks-pod-identity-aws-resources"
        }
    ]
}

Step 2: Associate the Target IAM Role to a Kubernetes service account

In this step, you will create an association between the Target IAM role and the Kubernetes service account in your EKS cluster.

(Optional) Step 3: Add External Permissions to an IAM Target Role

At times, you might need to give a third party access to your Amazon resources (delegate access). For example, you decide to hire a third-party company called Example Corp to monitor your Amazon account and help optimize costs. In order to track your daily spending, Example Corp needs to access your Amazon resources. In this case, we recommend adding an ExternalId to the trust policy of your IAM Target Role to avoid possible Confused Deputy issues.

Edit the trust policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111122223333:role/eks-pod-identity-primary-role"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "region/111122223333/cluster-name/namespace/service-account-name"
                }
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111122223333:role/eks-pod-identity-primary-role"
            },
            "Action": "sts:TagSession"
        }
    ]
}