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 AWS Resources using EKS Pod Identity Target IAM Roles

When running applications on Amazon Elastic Kubernetes Service (Amazon EKS), you might need to access AWS resources that exist in different AWS accounts. This guide shows you how to set up cross account access using EKS Pod Identity, which enables your Kubernetes pods to access other AWS resources using target roles.

Prerequisites

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

How It Works

Pod Identity enables applications in your EKS cluster to access AWS 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 AWS resources you wish to access, (like S3 buckets or RDS Databases). 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 AWS account. PassRole enables an AWS 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 AWS account as the EKS cluster. When your application pod needs to access AWS 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 AWS 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 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 AWS accounts: the EKS Pod Identity role (e.g., eks-pod-identity-primary-role) in the EKS cluster’s AWS account gains permission to assume the Target IAM Role (e.g. eks-pod-identity-aws-resources) in your target account, enabling access to AWS 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:root"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ],
      "Condition": {
        "StringEquals": {
          "aws:PrincipalTag/eks-cluster-arn": "arn:aws:eks:us-east-1:111122223333:cluster/example-cluster",
          "aws:PrincipalTag/kubernetes-namespace": "ExampleNameSpace",
          "aws:PrincipalTag/kubernetes-service-account": "ExampleServiceAccountName"
        },
        "ArnEquals": {
          "aws:PrincipalARN": "arn:aws:iam::111122223333:role/eks-pod-identity-primary-role"
        }
      }
    }
  ]
}

The above policy policy lets the role eks-pod-identeity-primary-role from AWS account 111122223333 with the relevant EKS Pod Identity Session Tags assume this role.

If you Disabled Session Tags in your EKS Pod Identity, EKS Pod Identity also sets the sts:ExternalId with information about the cluster, namespace, and service account of a pod when assuming a target role.

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

The above policy helps ensure that only the expected cluster, namespace and service account can assume the target role.

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.