Connecting kubectl to an AWS EKS cluster

The other day I made a wee post about how to manage users on an EKS cluster using IAM users and roles. Today it’s turn to explain how those users can connect to the cluster.

This has been tested on Ubuntu 18,04, 20.04, and MacOS.


  • AWS Command Line Interface. You can find instructions on how to install it here.
  • kubectl. All the steps are explained here.

You must use a kubectl version that is within one minor version difference of your cluster. For example, a v1.2 client should work with v1.1, v1.2, and v1.3

kubectl documentation

AWS CLI Configuration

The AWS CLI stores credentials in a local file named credentials, in a directory named .aws in your home directory. That file can store different profiles and the profile name is something we need to remember as we will use it later.

The way you add the different profiles is entirely up to you and your needs. Simply remember, the first profile (default) it’s used when you don’t pass any profile information to the CLI.

IAM Users

If you’re using the IAM users way you only need to add the IAM user that has been granted permissions on the EKS cluster.
You’ll need to remember the name of the profile where the user credentials are saved as you will use it later.

IAM Roles

If you are using IAM roles you need to add the IAM user that is allowed to assume the role used to connect with EKS. You also need to add the role.

You will need to remember the name of the profile where the role is saved as you will use it later.


role_arn = arn:aws:iam:1234567890:role/EKSRoleName
source_profile = default #This needs to match the profile where the details of the user are saved.

You can check if your details are correct by running the command(s) listed below.

#This gives you information about your own user.
aws sts get-caller-identity                   
    "Account": "1234567890",
    "Arn": "arn:aws:iam::1234567890:user/daveops"
#This gives you information about your own user.
aws sts get-caller-identity                   
    "Account": "1234567890",
    "Arn": "arn:aws:iam::1234567890:user/daveops"

#If the permissions are set correctly and the user can assume the role the output should be similar to what you see below
aws sts get-caller-identity --profile daveops-eks
    "UserId": "AROA22HCPPIFCOKNYURUS:botocore-session-1225235571",
    "Account": "accountNumber",
    "Arn": "arn:aws:sts::accountNumber:assumed-role/daveops-eks/botocore-session-1225235571"

The AWS CLI is now configured, and you have correct permissions. Let’s move to the Kubectl config.


The kubectl config is stored in a file here: ~/.kube/config. Basically it’s a YAML document with the following structure when used for EKS:

apiVersion: v1
- cluster:
    certificate-authority-data: some data here
    name: arn:arnOfTheCluster
- context:
    cluster: arnOfTheCluster
    namespace: namespaceName
    user: arnOfTheCluster
current-context: arn:arnOfTheActiveCluster
kind: Config
preferences: {}
- name: arnOfTheCluster
      - --region
      - regionId
      - eks
      - get-token
      - --cluster-name
      - clusterName
      command: aws
      - name: AWS_PROFILE
        value: profileName #This is important!

Things to know about this:

  • You can configure more than one cluster, but for each of them you’ll need to add a cluster a context and a user.
  • The config is automatically generated and added by the AWS CLI. If you didn’t create the cluster someone will most probably give you the details you need.
  • AWS_PROFILE is important. Remember when I said you would need to remember an AWS profile from the credentials file? Well, now is the moment to use it.
    • If you are using an IAM User, use the name of the profile where the details of your user are stored. In my example this was default.
    • If you are using an IAM Profile, use the name of the profile where the details of the role you assume are stored. In my example this was daveops-eks.

Check that you effectively have access to the cluster by running something on kubectl. For example, the following command returns a list of pods.

kubectl get pods
NAME                                                              READY   STATUS             RESTARTS   AGE
my-service-fdcd8c95d-2862m                                     1/1     Running            0          6d1h
my-service-fdcd8c95d-8hlc2                                     1/1     Running            0          6d1h
my-service-fdcd8c95d-cg67k                                     1/1     Running            0          6d1h
my-service-fdcd8c95d-fgh94                                     1/1     Running            0          6d1h
my-service-fdcd8c95d-p5dqd                                     1/1     Running            0          6d1h
my-service-fdcd8c95d-sfvzh                                     1/1     Running            0          6d1h
my-service-fdcd8c95d-sr7pc                                     1/1     Running            0          6d1h
my-service-fdcd8c95d-swghv                                     1/1     Running            0          6d1h
my-service-fdcd8c95d-t4ztb                                     1/1     Running            0          6d1h

Thanks for visiting my blog! Please, let me know what you think in the comments below. Was this any useful at all? Is there any more information you’d like to see here?


Leave a Reply

Your email address will not be published. Required fields are marked *