Learn how EKS Pod Identity grants pods access to AWS services

Applications in a Pod’s containers can use an AWS SDK or the AWS CLI to make API requests to AWS services using AWS Identity and Access Management (IAM) permissions. Applications must sign their AWS API requests with AWS 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 AWS 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 AWS SDKs, including the AWS 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 AWS 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 AWS 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 AWS 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 AWS services with service accounts — Complete this procedure for each Pod that needs access to AWS services.

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

EKS Pod Identity considerations

• Pod Identity Association Limit: You can create up to 5,000 EKS Pod Identity associations per cluster to map IAM roles to Kubernetes service accounts.

• IAM Role Association: Each Kubernetes service account in a cluster can be associated with one IAM role from the same AWS account as the cluster. To change the role, edit the EKS Pod Identity association. For cross-account access, delegate access to the role using IAM roles. To learn more, see Delegate access across AWS accounts using IAM roles in the IAM User Guide.

• EKS Pod Identity Agent: The Pod Identity Agent is required to use EKS Pod Identity. The agent runs as a Kubernetes DaemonSet on cluster nodes, providing credentials only to pods on the same node. It uses the node’s hostNetwork, occupying port 80 and 2703 on the link-local address (169.254.170.23 for IPv4, [fd00:ec2::23] for IPv6). If IPv6 is disabled in your cluster, disable IPv6 for the Pod Identity Agent. To learn more, see Disable IPv6 in the EKS Pod Identity Agent.

• Eventual Consistency: EKS Pod Identity associations are eventually consistent, with potential delays of several seconds after API calls. Avoid creating or updating associations in critical, high-availability code paths. Instead, perform these actions in separate, less frequent initialization or setup routines. To learn more, see Security Groups Per Pod in the EKS Best Practices Guide.

• Proxy and Security Group Considerations: For pods using a proxy, add 169.254.170.23 (IPv4) and [fd00:ec2::23] (IPv6) to the no_proxy/NO_PROXY environment variables to prevent failed requests to the EKS Pod Identity Agent. If using Security Groups for Pods with the AWS VPC CNI, set the ENABLE_POD_ENI flag to ‘true’ and the POD_SECURITY_GROUP_ENFORCING_MODE flag to ‘standard’. To learn more, see Assign security groups to individual Pods.

EKS Pod Identity cluster versions

To use EKS Pod Identity, 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. To find the suggested version of the Amazon EKS Pod Identity Agent for a Kubernetes version, see Verify Amazon EKS add-on version compatibility with a cluster.

Kubernetes version	Platform version
Kubernetes versions not listed	All platform versions support
1.28	eks.4
1.27	eks.8
1.26	eks.9

EKS Pod Identity restrictions

EKS Pod Identities are available on the following:

• Amazon EKS cluster versions listed in the previous topic EKS Pod Identity cluster versions.

• Worker nodes in the cluster that are Linux Amazon EC2 instances.

EKS Pod Identities aren’t available on the following:

• AWS 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 AWS Fargate (Fargate) aren’t supported. Pods that run on Windows Amazon EC2 instances aren’t supported.