Connect kubectl to an EKS cluster by creating a kubeconfig file - Amazon EKS
Create kubeconfig file automatically
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.

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

  • Version 2.12.3 or later or version 1.27.160 or later of the Amazon Command Line Interface (Amazon CLI) installed and configured on your device or Amazon 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 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 that is installed in Amazon CloudShell might 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.

  • 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 Amazon Command Line Interface (Amazon CLI) installed and configured on your device or Amazon 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 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 that is installed in Amazon CloudShell might 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.

  • 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 Amazon 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 Amazon CLI or SDK credential chain is used. You can view your default Amazon 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 Amazon 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.