Enabling IAM roles for service accounts on your cluster

The IAM roles for service accounts feature is available on new Amazon EKS Kubernetes version 1.14 and later clusters, and clusters that were updated to versions 1.13 or later on or after September 3rd, 2019. Existing clusters can update to version 1.13 or later to take advantage of this feature. For more information, see Updating an Amazon EKS cluster Kubernetes version.

If your cluster supports IAM roles for service accounts, it will have an OpenID Connect issuer URL associated with it. You can view this URL in the Amazon EKS console, or you can use the following AWS CLI command to retrieve it.

Important

You must use at least version 1.18.157 or 2.0.56 of the AWS CLI to receive the proper output from this command. For more information, see Installing the AWS CLI in the AWS Command Line Interface User Guide.

aws eks describe-cluster --name <cluster_name> --query "cluster.identity.oidc.issuer" --output text

Output:

https://oidc.eks.<region-code>.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E

To use IAM roles for service accounts in your cluster, you must create an OIDC identity provider using either eksctl or the AWS Management Console.

To create an IAM OIDC identity provider for your cluster with eksctl

1. Check your eksctl version with the following command. This procedure assumes that you have installed eksctl and that your eksctl version is at least 0.30.0-rc.0.

   eksctl version

   For more information about installing or upgrading eksctl, see Installing or upgrading eksctl.

2. Create your OIDC identity provider for your cluster with the following command. Substitute <cluster_name> with your own value.

   eksctl utils associate-iam-oidc-provider --cluster <cluster_name> --approve

To create an IAM OIDC identity provider for your cluster with the AWS Management Console

1. Retrieve the OIDC issuer URL from the Amazon EKS console description of your cluster or use the following AWS CLI command.

   Important

   You must use at least version 1.18.157 or 2.0.56 of the AWS CLI to receive the proper output from this command. For more information, see Installing the AWS CLI in the AWS Command Line Interface User Guide.

   aws eks describe-cluster --name <cluster_name> --query "cluster.identity.oidc.issuer" --output text

2. Open the IAM console at https://console.aws.amazon.com/iam/.

3. In the navigation panel, choose Identity Providers, and then choose Create Provider.

4. For Provider Type, choose Choose a provider type, and then choose OpenID Connect.

5. For Provider URL, paste the OIDC issuer URL for your cluster.

6. For Audience, type sts.amazonaws.com and choose Next Step.

7. Verify that the provider information is correct, and then choose Create to create your identity provider.

After you have enabled the IAM OIDC identity provider for your cluster, you can create IAM roles to associate with a service account in your cluster. For more information, see Creating an IAM role and policy for your service account