Connect kubectl to an EKS cluster by creating a kubeconfig file

In this topic, you create a kubeconfig file for your cluster (or update an existing one).

The kubectl command-line tool uses configuration information in kubeconfig files to communicate with the API server of a cluster. For more information, see Organizing Cluster Access Using kubeconfig Files in the Kubernetes documentation.

Amazon EKS uses the aws eks get-token command with kubectl for cluster authentication. By default, the AWS CLI uses the same credentials that are returned with the following command:

aws sts get-caller-identity

• An existing Amazon EKS cluster. To deploy one, see Get started with Amazon EKS.

• The kubectl command line tool is installed on your device or AWS 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.

• Version 2.12.3 or later or version 1.27.160 or later of the AWS Command Line Interface (AWS CLI) installed and configured on your device or AWS CloudShell. To check your current version, use 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 AWS CLI. To install the latest version, see Installing and Quick configuration with aws configure in the AWS Command Line Interface User Guide. The AWS CLI version that is installed in AWS CloudShell might also be several versions behind the latest version. To update it, see Installing AWS CLI to your home directory in the AWS CloudShell User Guide.

• An IAM user or role with permission to use the eks:DescribeCluster API action for the cluster that you specify. For more information, see Amazon EKS identity-based policy examples. If you use an identity from your own OpenID Connect provider to access your cluster, then see Using kubectl in the Kubernetes documentation to create or update your kube config file.

Create kubeconfig file automatically

• Version 2.12.3 or later or version 1.27.160 or later of the AWS Command Line Interface (AWS CLI) installed and configured on your device or AWS CloudShell. To check your current version, use 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 AWS CLI. To install the latest version, see Installing and Quick configuration with aws configure in the AWS Command Line Interface User Guide. The AWS CLI version that is installed in AWS CloudShell might also be several versions behind the latest version. To update it, see Installing AWS CLI to your home directory in the AWS CloudShell User Guide.

• Permission to use the eks:DescribeCluster API action for the cluster that you specify. For more information, see Amazon EKS identity-based policy examples.

  1. Create or update a kubeconfig file for your cluster. Replace region-code with the AWS Region that your cluster is in and replace my-cluster with the name of your cluster.

     aws eks update-kubeconfig --region region-code --name my-cluster

     By default, the resulting configuration file is created at the default kubeconfig path (.kube) in your home directory or merged with an existing config file at that location. You can specify another path with the --kubeconfig option.

     You can specify an IAM role ARN with the --role-arn option to use for authentication when you issue kubectl commands. Otherwise, the IAM principal in your default AWS CLI or SDK credential chain is used. You can view your default AWS CLI or SDK identity by running the aws sts get-caller-identity command.

     For all available options, run the aws eks update-kubeconfig help command or see update-kubeconfig in the AWS CLI Command Reference.

  2. Test your configuration.

     kubectl get svc

     An example output is as follows.

     NAME             TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
     svc/kubernetes   ClusterIP   10.100.0.1   <none>        443/TCP   1m

     If you receive any authorization or resource type errors, see Unauthorized or access denied (kubectl) in the troubleshooting topic.