EKS Pod Identities - Amazon EKS
Benefits of EKS Pod IdentitiesSetup overviewConsiderations
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).

EKS Pod Identities

Important

Pod Identity is not available in China Regions. Use IAM roles for service accounts.

Applications in a Pod's containers can use an Amazon SDK or the Amazon CLI to make API requests to Amazon Web 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 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.

  2. Configure a Kubernetes service account to assume an IAM role with EKS Pod Identity – Complete this procedure for each unique set of permissions that you want an application to have.

  3. Configure Pods to use a Kubernetes service account – Complete this procedure for each Pod that needs access to Amazon Web Services.

  4. Use a supported 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 Web Services 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.

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

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.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 Amazon Web Services 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

  • Amazon Load Balancer Controller 2.7.0 or later. Note that the Amazon 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:

  • China Regions.

  • Amazon GovCloud (US).

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

  • 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, Amazon 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 long as they are updated to use the latest Amazon SDKs.