Learn how EKS Pod Identity grants pods access to Amazon services - Amazon EKS
Benefits of EKS Pod IdentitiesOverview of setting up EKS Pod IdentitiesEKS Pod Identity considerations
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

Want to contribute to this user guide? Choose the Edit this page on GitHub link that is located in the right pane of every page. Your contributions will help make our user guide better for everyone.

Learn how EKS Pod Identity grants pods access to Amazon services

Applications in a Pod’s containers can use an Amazon SDK or the Amazon CLI to make API requests to Amazon services using Amazon Identity and Access Management (IAM) permissions. Applications must sign their Amazon API requests with Amazon credentials.

EKS Pod Identities provide the ability to manage credentials for your applications, similar to the way that Amazon EC2 instance profiles provide credentials to Amazon EC2 instances. Instead of creating and distributing your Amazon credentials to the containers or using the Amazon EC2 instance’s role, you associate an IAM role with a Kubernetes service account and configure your Pods to use the service account.

Each EKS Pod Identity association maps a role to a service account in a namespace in the specified cluster. If you have the same application in multiple clusters, you can make identical associations in each cluster without modifying the trust policy of the role.

If a pod uses a service account that has an association, Amazon EKS sets environment variables in the containers of the pod. The environment variables configure the Amazon SDKs, including the Amazon CLI, to use the EKS Pod Identity credentials.

Benefits of EKS Pod Identities

EKS Pod Identities provide the following benefits:

  • Least privilege – You can scope IAM permissions to a service account, and only Pods that use that service account have access to those permissions. This feature also eliminates the need for third-party solutions such as kiam or kube2iam.

  • Credential isolation – A Pod’s containers can only retrieve credentials for the IAM role that’s associated with the service account that the container uses. A container never has access to credentials that are used by other containers in other Pods. When using Pod Identities, the Pod’s containers also have the permissions assigned to the Amazon EKS node IAM role, unless you block Pod access to the Amazon EC2 Instance Metadata Service (IMDS). For more information, see Restrict access to the instance profile assigned to the worker node.

  • Auditability – Access and event logging is available through Amazon CloudTrail to help facilitate retrospective auditing.

EKS Pod Identity is a simpler method than IAM roles for service accounts, as this method doesn’t use OIDC identity providers. EKS Pod Identity has the following enhancements:

  • Independent operations – In many organizations, creating OIDC identity providers is a responsibility of different teams than administering the Kubernetes clusters. EKS Pod Identity has clean separation of duties, where all configuration of EKS Pod Identity associations is done in Amazon EKS and all configuration of the IAM permissions is done in IAM.

  • Reusability – EKS Pod Identity uses a single IAM principal instead of the separate principals for each cluster that IAM roles for service accounts use. Your IAM administrator adds the following principal to the trust policy of any role to make it usable by EKS Pod Identities.

                "Principal": {
                "Service": "pods.eks.amazonaws.com"
            }

  • Scalability — Each set of temporary credentials are assumed by the EKS Auth service in EKS Pod Identity, instead of each Amazon SDK that you run in each pod. Then, the Amazon EKS Pod Identity Agent that runs on each node issues the credentials to the SDKs. Thus the load is reduced to once for each node and isn’t duplicated in each pod. For more details of the process, see Understand how EKS Pod Identity works.

For more information to compare the two alternatives, see Grant Kubernetes workloads access to Amazon using Kubernetes Service Accounts.

Overview of setting up EKS Pod Identities

Turn on EKS Pod Identities by completing the following procedures:

  1. Set up the Amazon EKS Pod Identity Agent — You only complete this procedure once for each cluster. You do not need to complete this step if EKS Auto Mode is enabled on your cluster.

  2. Assign an IAM role to a Kubernetes service account — Complete this procedure for each unique set of permissions that you want an application to have.

  3. Configure pods to access Amazon services with service accounts — Complete this procedure for each Pod that needs access to Amazon services.

  4. Use pod identity with the Amazon SDK — Confirm that the workload uses an Amazon SDK of a supported version and that the workload uses the default credential chain.

EKS Pod Identity considerations

  • You can associate one IAM role to each Kubernetes service account in each cluster. You can change which role is mapped to the service account by editing the EKS Pod Identity association.

  • You can only associate roles that are in the same Amazon account as the cluster. You can delegate access from another account to the role in this account that you configure for EKS Pod Identities to use. For a tutorial about delegating access and AssumeRole, see Delegate access across Amazon accounts using IAM roles in the IAM User Guide.

  • The EKS Pod Identity Agent is required. It runs as a Kubernetes DaemonSet on your nodes and only provides credentials to pods on the node that it runs on. For more information about EKS Pod Identity Agent compatibility, see the following section EKS Pod Identity restrictions.

  • If you are using Security Group for Pods along with Pod Identity Agent, you may need to set the POD_SECURITY_GROUP_ENFORCING_MODE Flag for the Amazon VPC CNI. For more information on security group for pods considerations, see Assign security groups to individual Pods.

  • The EKS Pod Identity Agent uses the hostNetwork of the node and it uses port 80 and port 2703 on a link-local address on the node. This address is 169.254.170.23 for IPv4 and [fd00:ec2::23] for IPv6 clusters.

    If you disable IPv6 addresses, or otherwise prevent localhost IPv6 IP addresses, the agent can’t start. To start the agent on nodes that can’t use IPv6, follow the steps in Disable IPv6 in the EKS Pod Identity Agent to disable the IPv6 configuration.

EKS Pod Identity cluster versions

To use EKS Pod Identities, the cluster must have a platform version that is the same or later than the version listed in the following table, or a Kubernetes version that is later than the versions listed in the table.

Kubernetes version Platform version

1.31

eks.4

1.30

eks.2

1.29

eks.1

1.28

eks.4

1.27

eks.8

1.26

eks.9

1.25

eks.10

1.24

eks.13

EKS Pod Identity restrictions

EKS Pod Identities are available on the following:

EKS Pod Identities aren’t available on the following:

  • Amazon Outposts.

  • Amazon EKS Anywhere.

  • Kubernetes clusters that you create and run on Amazon EC2. The EKS Pod Identity components are only available on Amazon EKS.

You can’t use EKS Pod Identities with:

  • Pods that run anywhere except Linux Amazon EC2 instances. Linux and Windows pods that run on Amazon Fargate (Fargate) aren’t supported. Pods that run on Windows Amazon EC2 instances aren’t supported.