Configuring Pods to use a Kubernetes service account - Amazon EKS
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).

Configuring Pods to use a Kubernetes service account

If a Pod needs to access Amazon Web Services, then you must configure it to use a Kubernetes service account. The service account must be associated to an Amazon Identity and Access Management (IAM) role that has permissions to access the Amazon Web Services.

  • An existing cluster. If you don't have one, you can create one using one of the Getting started with Amazon EKS guides.

  • An existing IAM OpenID Connect (OIDC) provider for your cluster. To learn if you already have one or how to create one, see Creating an IAM OIDC provider for your cluster.

  • An existing Kubernetes service account that's associated with an IAM role. The service account must be annotated with the Amazon Resource Name (ARN) of the IAM role. The role must have an associated IAM policy that contains the permissions that you want your Pods to have to use Amazon Web Services. For more information about how to create the service account and role, and configure them, see Configuring a Kubernetes service account to assume an IAM role.

  • Version 2.12.3 or later or 1.27.160 or later of the Amazon CLI installed and configured on your device or Amazon CloudShell. You can check your current version with aws --version | cut -d / -f2 | cut -d ' ' -f1. Package managers such yum, apt-get, or Homebrew for macOS are often several versions behind the latest version of the Amazon CLI. To install the latest version, see Installing, updating, and uninstalling the Amazon CLI and Quick configuration with aws configure in the Amazon Command Line Interface User Guide. The Amazon CLI version installed in the Amazon CloudShell may also be several versions behind the latest version. To update it, see Installing Amazon CLI to your home directory in the Amazon CloudShell User Guide.

  • The kubectl command line tool is installed on your device or Amazon CloudShell. The version can be the same as or up to one minor version earlier or later than the Kubernetes version of your cluster. For example, if your cluster version is 1.27, you can use kubectl version 1.26, 1.27, or 1.28 with it. To install or upgrade kubectl, see Installing or updating kubectl.

  • An existing kubectl config file that contains your cluster configuration. To create a kubectl config file, see Creating or updating a kubeconfig file for an Amazon EKS cluster.

To configure a Pod to use a service account
  1. Use the following command to create a deployment manifest that you can deploy a Pod to confirm configuration with. The Pod uses an existing Kubernetes service account. The service account must be properly configured. For more information, see Configuring a Kubernetes service account to assume an IAM role. Replace the example values with your own values.

    cat >my-deployment.yaml <<EOF apiVersion: apps/v1 kind: Deployment metadata: name: my-app spec: selector: matchLabels: app: my-app template: metadata: labels: app: my-app spec: serviceAccountName: my-service-account containers: - name: my-app image: EOF
  2. Deploy the manifest to your cluster.

    kubectl apply -f my-deployment.yaml
  3. Confirm that the required environment variables exist for your Pod.

    1. View the Pods that were deployed with the deployment in the previous step.

      kubectl get pods | grep my-app

      An example output is as follows.

      my-app-6f4dfff6cb-76cv9 1/1 Running 0 3m28s
    2. View the ARN of the IAM role that the Pod is using.

      kubectl describe pod my-app-6f4dfff6cb-76cv9 | grep AWS_ROLE_ARN:

      An example output is as follows.

      AWS_ROLE_ARN: arn:aws-cn:iam::111122223333:role/my-role

      The role ARN must match the role ARN that you annotated the existing service account with. For more about annotating the service account, see Configuring a Kubernetes service account to assume an IAM role.

    3. Confirm that the Pod has a web identity token file mount.

      kubectl describe pod my-app-6f4dfff6cb-76cv9 | grep AWS_WEB_IDENTITY_TOKEN_FILE:

      An example output is as follows.

      AWS_WEB_IDENTITY_TOKEN_FILE: /var/run/secrets/

      The kubelet requests and stores the token on behalf of the Pod. By default, the kubelet refreshes the token if the token is older than 80 percent of its total time to live or older than 24 hours. You can modify the expiration duration for any account other than the default service account by using the settings in your Pod spec. For more information, see Service Account Token Volume Projection in the Kubernetes documentation.

      The Amazon EKS Pod Identity Webhook on the cluster watches for Pods that use a service account with the following annotation: arn:aws-cn:iam::111122223333:role/my-role

      The webhook applies the previous environment variables to those Pods. Your cluster doesn't need to use the webhook to configure the environment variables and token file mounts. You can manually configure Pods to have these environment variables. The supported versions of the Amazon SDK look for these environment variables first in the credential chain provider. The role credentials are used for Pods that meet this criteria.

  4. Confirm that your Pods can interact with the Amazon Web Services using the permissions that you assigned in the IAM policy attached to your role.


    When a Pod uses Amazon credentials from an IAM role that's associated with a service account, the Amazon CLI or other SDKs in the containers for that Pod use the credentials that are provided by that role. If you don't restrict access to the credentials that are provided to the Amazon EKS node IAM role, the Pod still has access to these credentials. For more information, see Restrict access to the instance profile assigned to the worker node.

    If your Pods can't interact with the services as you expected, complete the following steps to confirm that everything is properly configured.

    1. Confirm that your Pods use an Amazon SDK version that supports assuming an IAM role through an OpenID Connect web identity token file. For more information, see Using a supported Amazon SDK.

    2. Confirm that the deployment is using the service account.

      kubectl describe deployment my-app | grep "Service Account"

      An example output is as follows.

      Service Account: my-service-account
    3. If your Pods still can't access services, review the steps that are described in Configuring a Kubernetes service account to assume an IAM role to confirm that your role and service account are configured properly.