Learn how EKS Pod Identity grants pods access to AWS services - Amazon EKS

Help improve this page

Want to contribute to this user guide? Scroll to the bottom of this page and select Edit this page on GitHub. Your contributions will help make our user guide better for everyone.

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.

  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

  • 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 AWS 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 AWS 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.

  • 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

Add-on versions compatible with EKS Pod Identity

Important

To use EKS Pod Identity with an EKS Add-on, you must create the EKS Pod Identity association manually. Don’t choose an IAM role in the add-on configuration in the AWS Management Console, that role is only used with IRSA.

Amazon EKS add-ons and self-managed add-ons that need IAM credentials can use EKS Pod Identity, IRSA or the instance role. The list of add-ons that use IAM credentials that support EKS Pod Identity are:

  • Amazon VPC CNI plugin for Kubernetes`1.15.5-eksbuild.1` or later

  • AWS Load Balancer Controller 2.7.0 or later. Note that the AWS Load Balancer Controller isn’t available as an EKS Add-on, but it is available as a self-managed add-on.

EKS Pod Identity restrictions

EKS Pod Identities are available on the following:

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.

  • Amazon EKS add-ons that need IAM credentials. The EKS add-ons can only use IAM roles for service accounts instead. The list of EKS add-ons that use IAM credentials include:

    • The CSI storage drivers: EBS CSI, EFS CSI, Amazon FSx for Lustre CSI driver, Amazon FSx for NetApp ONTAP CSI driver, Amazon FSx for OpenZFS CSI driver, Amazon File Cache CSI driver, AWS Secrets and Configuration Provider (ASCP) for the Kubernetes Secrets Store CSI Driver

      Note

      If these controllers, drivers, and plugins are installed as self-managed add-ons instead of EKS add-ons, they support EKS Pod Identities as longas they are updated to use the latest AWS SDKs.