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.
Creating or updating a kubeconfig
file for
an Amazon EKS cluster
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 Amazon CLI uses the same credentials that are returned with the
following command:
aws sts get-caller-identity
Prerequisites
-
An existing Amazon EKS cluster. To deploy one, see Getting 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 is1.29
, you can usekubectl
version1.28
,1.29
, or1.30
with it. To install or upgradekubectl
, see Installing or updating kubectl. -
Version
2.12.3
or later or version1.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
. Package managers suchaws --version | cut -d / -f2 | cut -d ' ' -f1
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, updating, and uninstalling the Amazon CLI 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 Usingkubectl
in the Kubernetes documentation to create or update your kube config
file.
Create kubeconfig
file
automatically
Prerequisites
-
Version
2.12.3
or later or version1.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
. Package managers suchaws --version | cut -d / -f2 | cut -d ' ' -f1
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, updating, and uninstalling the Amazon CLI 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.
To create your kubeconfig
file with the Amazon CLI
-
Create or update a
kubeconfig
file for your cluster. Replaceregion-code
with the Amazon Web Services Region that your cluster is in and replacemy-cluster
with the name of your cluster.aws eks update-kubeconfig --region
region-code
--namemy-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 Amazon CLI or SDK credential chain is used. You can view your default Amazon 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 seeupdate-kubeconfig
in the Amazon 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.