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.
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
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 is1.29
, you can usekubectl
version1.28
,1.29
, or1.30
with it. To install or upgradekubectl
, see Set up kubectl and eksctl. -
Version
2.12.3
or later or version1.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, useaws --version | cut -d / -f2 | cut -d ' ' -f1
. Package managers suchyum
,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 kubectlin the Kubernetes documentation to create or update your kube config
file.
Create kubeconfig
file automatically
-
Version
2.12.3
or later or version1.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, useaws --version | cut -d / -f2 | cut -d ' ' -f1
. Package managers suchyum
,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.-
Create or update a
kubeconfig
file for your cluster. Replaceregion-code
with the AWS Region that your cluster is in and replacemy-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 existingconfig
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 issuekubectl
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 theaws 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. -
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.
-