Configure pods to access Amazon services with service accounts - 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? Choose the Edit this page on GitHub link that is located in the right pane of every page. Your contributions will help make our user guide better for everyone.

Configure pods to access Amazon services with service accounts

If a Pod needs to access Amazon 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 services.

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

  • 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 services. For more information about how to create the service account and role, and configure them, see Assign an IAM role to a Kubernetes service account.

  • 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 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 Set up kubectl and eksctl.

  • An existing kubectl config file that contains your cluster configuration. To create a kubectl config file, see Connect kubectl to an EKS cluster by creating a kubeconfig file.

    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 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 roleAmazon 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 pod identity with the 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