Attach an IAM Role to an Amazon EKS add-on using Pod Identity - Amazon EKS
Retrieve IAM info about an Add-onUpdate Add-on with IAM Role Remove Associations from Add-on Troubleshoot Pod Identities for EKS Add-ons
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? 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.

Attach an IAM Role to an Amazon EKS add-on using Pod Identity

Certain Amazon EKS add-ons need IAM role permissions to call Amazon APIs. For example, the Amazon VPC CNI add-on calls certain Amazon APIs to configure networking resources in your account. These add-ons need to be granted permission using Amazon IAM. More specifically, the service account of the pod running the add-on needs to be associated with an IAM Role with a sufficient IAM Policy.

The recommended way to grant Amazon permissions to cluster workloads is using the Amazon EKS feature Pod Identities. You can use a Pod Identity Association to map the service account of an add-on to an IAM 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. Learn more about EKS Pod Identities.

Amazon EKS add-ons can help manage the life cycle of pod identity associations corresponding to the add-on. For example, you can create or update an Amazon EKS add-on and the necessary pod identity association in a single API call. Amazon EKS also provides an API for retrieving suggested IAM policies.

Suggested Usage:

  1. Confirm that Amazon EKS pod identity agent is setup on your cluster.

  2. Determine if the add-on you want to install requires IAM permissions using the describe-addon-versions Amazon CLI operation. If the requiresIamPermissions flag is true, then you should use the describe-addon-configurations operation to determine the permissions needed by the addon. The response includes a list of suggested managed IAM policies.

  3. Retrieve the name of the Kubernetes Service Account and the suggested IAM policy using the describe-addon-configuration CLI operation. Evaluate the scope of the suggested policy against your security requirements.

  4. Create an IAM role using the suggested permissions policy, and the trust policy required by Pod Identity. For more information, see Creating the EKS Pod Identity association.

  5. Create or update an Amazon EKS add-on using the CLI. Specify at least one pod identity association. A pod identity association is (1) the name of a Kubernetes service account, and (2) the ARN of an IAM role.

Considerations:

  • Pod identity associations created using the add-on APIs are owned by the respective add-on. If you delete the add-on, the pod identity association is also deleted. You can prevent this cascading delete by using the preserve option when deleting an addon using the Amazon CLI or API. You also can directly update or delete the pod identity association if necessary. Add-ons cannot assume ownership of existing pod identity associations. You must delete the existing association and re-create it using an add-on create or update operation.

  • Amazon EKS recommends using pod identity associations to manage IAM permissions for add-ons. The previous method, IAM roles for service accounts (IRSA), is still supported. You can specify both an IRSA serviceAccountRoleArn and a pod identity association for an add-on. If the EKS pod identity agent is installed on the cluster, the serviceAccountRoleArn will be ignored, and EKS will use the provided pod identity association. If Pod Identity is not enabled, the serviceAccountRoleArn will be used.

  • If you update the pod identity associations for an existing add-on, Amazon EKS initiates a rolling restart of the add-on pods.

Retrieve IAM info about an Add-on

You can use the Amazon CLI to determine (1) if an add-on requires IAM permissions, and (2) a suggested IAM policy for that add-on.

Retrieve IAM info about an Amazon EKS Add-on (Amazon CLI)

  1. Determine the name of the add-on you want to install, and the Kubernetes version of your cluster. Learn more about available Amazon EKS Add-ons.

  2. Use the Amazon CLI to determine if the add-on requires IAM permissions. 

    aws eks describe-addon-versions \
--addon-name <addon-name> \
--kubernetes-version <kubernetes-version>

    For example:

    aws eks describe-addon-versions \
--addon-name aws-ebs-csi-driver \
--kubernetes-version 1.30

    Review the following sample output. Note that requiresIamPermissions is true, and the default add-on version. You need to specify the add-on version when retrieving the recommended IAM policy.

    {
    "addons": [
        {
            "addonName": "aws-ebs-csi-driver",
            "type": "storage",
            "addonVersions": [
                {
                    "addonVersion": "v1.31.0-eksbuild.1",
                    "architecture": [
                        "amd64",
                        "arm64"
                    ],
                    "compatibilities": [
                        {
                            "clusterVersion": "1.30",
                            "platformVersions": [
                                "*"
                            ],
                            "defaultVersion": true
                        }
                    ],
                    "requiresConfiguration": false,
                    "requiresIamPermissions": true
                },
[...]

  3. If the add-on requires IAM permissions, use the Amazon CLI to retrieve a recommended IAM policy. 

    aws eks describe-addon-configuration \
--query podIdentityConfiguration \
--addon-name <addon-name> \
--addon-version <addon-version>

    For example:

    aws eks describe-addon-configuration \
--query podIdentityConfiguration \
--addon-name aws-ebs-csi-driver \
--addon-version v1.31.0-eksbuild.1

    Review the following output. Note the recommendedManagedPolicies.

    [
    {
        "serviceAccount": "ebs-csi-controller-sa",
        "recommendedManagedPolicies": [
            "arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy"
        ]
    }
]

  4. Create an IAM role and attach the recommended Managed Policy. Alternatively, review the managed policy and scope down the permissions as appropriate. Review the instructions for creating an IAM Role for use with EKS Pod Identities.

Update Add-on with IAM Role

Update an Amazon EKS Add-on to use a Pod Identity Association (Amazon CLI)

  1. Determine:

    • cluster-name – The name of the EKS cluster to install the add-on onto.

    • addon-name – The name of the Amazon EKS add-on to install.

    • service-account-name – The name of the Kubernetes Service Account used by the add-on.

    • iam-role-arn – The ARN of an IAM role with sufficient permissions for the add-on. The IAM Role must have the required trust policy for EKS Pod Identity.

  2. Update the add-on using the Amazon CLI. You can also specify pod identity associations when creating an add-on, using the same --pod-identity-assocations syntax. Note that when you specify pod identity associations while updating an add-on, all previous pod identity associations are overwritten. 

    aws eks update-addon --cluster-name <cluster-name> \
--addon-name <addon-name> \
--pod-identity-associations 'serviceAccount=<service-account-name>,roleArn=<role-arn>'

    For example:

    aws eks update-addon --cluster-name mycluster \
--addon-name aws-ebs-csi-driver \
--pod-identity-associations 'serviceAccount=ebs-csi-controller-sa,roleArn=arn:aws:iam::123456789012:role/StorageDriver'

  3. Validate the pod identity association was created:

    aws eks list-pod-identity-associations --cluster-name <cluster-name>

    If successful, you should see output similar to the following. Note the OwnerARN of the EKS add-on. 

    {
    "associations": [
        {
            "clusterName": "mycluster",
            "namespace": "kube-system",
            "serviceAccount": "ebs-csi-controller-sa",
            "associationArn": "arn:aws:eks:cn-north-1:123456789012:podidentityassociation/mycluster/a-4wvljrezsukshq1bv",
            "associationId": "a-4wvljrezsukshq1bv",
            "ownerArn": "arn:aws:eks:cn-north-1:123456789012:addon/mycluster/aws-ebs-csi-driver/9cc7ce8c-2e15-b0a7-f311-426691cd8546"
        }
    ]
}

Remove Associations from Add-on

Remove all pod identity associations from an Amazon EKS Add-on (Amazon CLI)

  1. Determine:

    • cluster-name – The name of the EKS cluster to install the add-on onto.

    • addon-name – The name of the Amazon EKS add-on to install.

  2. Update the addon to specify an empty array of pod identity associations. 

    aws eks update-addon --cluster-name <cluster-name> \
--addon-name <addon-name> \
--pod-identity-associations "[]"

Troubleshoot Pod Identities for EKS Add-ons

If your add-ons are encountering errors while attempting Amazon API, SDK, or CLI operations, confirm the following:

  • The Pod Identity Agent is installed in your cluster.

  • The Add-on has a valid pod identity association.

    • Use the Amazon CLI to retrieve the associations for service account name used by the add-on. 

      aws eks list-pod-identity-associations --cluster-name <cluster-name>

  • The intended IAM role has the required trust policy for EKS Pod Identities.

    • Use the Amazon CLI to retrieve the trust policy for an add-on. 

      aws iam get-role --role-name <role-name> --query Role.AssumeRolePolicyDocument

  • The intended IAM role has the necessary permissions for the add-on.

    • Use Amazon CloudTrail to review AccessDenied or UnauthorizedOperation events .

  • The service account name in the pod identity association matches the service account name used by the add-on.