Configure 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).

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.

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

Prerequisites

  • 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 Kubernetes service account and an EKS Pod Identity association that associates the service account with an 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 Configure a Kubernetes service account to assume an IAM role with EKS Pod Identity.

  • The latest version 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.29, you can use kubectl version 1.28, 1.29, or 1.30 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. 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: public.ecr.aws/nginx/nginx:X.XX
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. Confirm that the Pod has a service account token file mount.

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

      An example output is as follows.

      AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE:  /var/run/secrets/pods.eks.amazonaws.com/serviceaccount/eks-pod-identity-token

  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.

    Note

    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 EKS Pod Identity association. For more information, see Use 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