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 Fileskubeconfig
file for
your Amazon EKS cluster:
-
Creating it automatically with the AWS CLI
update-kubeconfig
command. -
Creating it manually using the AWS CLI or the
aws-iam-authenticator
.
Amazon EKS uses the aws eks get-token
command, available in version
1.16.156
or later of the AWS CLI or the AWS IAM Authenticator for Kuberneteskubectl
for cluster authentication.
If you have installed the AWS CLI on your system, then by default the AWS IAM
Authenticator for Kubernetes 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 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.27
, you can usekubectl
version1.26
,1.27
, or1.28
with it. To install or upgradekubectl
, see Installing or updating kubectl.
Create kubeconfig
file
automatically
Prerequisites
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, updating, and uninstalling the AWS CLI 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.
To create your kubeconfig
file with the AWS CLI
-
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
--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 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 seeupdate-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.
Create kubeconfig
file
manually
To create your kubeconfig
file manually
-
Set values for a few variables by replacing the
with your own and then running the modified commands.example values
export region_code=
region-code
export cluster_name=my-cluster
export account_id=111122223333
-
Retrieve the endpoint for your cluster and store the value in a variable.
cluster_endpoint=$(aws eks describe-cluster \ --region $region_code \ --name $cluster_name \ --query "cluster.endpoint" \ --output text)
-
Retrieve the Base64-encoded certificate data required to communicate with your cluster and store the value in a variable.
certificate_data=$(aws eks describe-cluster \ --region $region_code \ --name $cluster_name \ --query "cluster.certificateAuthority.data" \ --output text)
-
Create the default
~/.kube
directory if it doesn't already exist.mkdir -p ~/.kube
-
Run one of the following commands for your preferred client token method (AWS CLI or AWS IAM authenticator for Kubernetes) to create the
config
file in the~/.kube
directory. You can specify the following before running one of the commands by modifying the command to include the following:-
An IAM role – Remove the
#
at the start of the lines underargs:
. Replace
with the name of the IAM role that you want to perform cluster operations with instead of the default AWS credential provider chain. For more information, see Set upmy-role
kubectl
to use authentication tokens provided by AWS IAM Authenticator for Kuberneteson GitHub. -
An AWS CLI named profile – Remove the
#
at the start of theenv:
line, and remove#
at the start of the lines under it. Replace
with the name of the profile to use. If you don't specify a profile, then the default profile is used. For additional information, see Specifying Credentials & Using AWS Profilesaws-profile
on GitHub.
-
-
Add the file path to your
KUBECONFIG
environment variable so thatkubectl
knows where to look for your cluster configuration.-
For Bash shells on macOS or Linux:
export KUBECONFIG=$KUBECONFIG:~/.kube/config
-
For PowerShell on Windows:
$ENV:KUBECONFIG="{0};{1}" -f $ENV:KUBECONFIG, "$ENV:userprofile\.kube\config"
-
-
(Optional) Add the configuration to your shell initialization file so that it is configured when you open a shell.
-
For Bash shells on macOS:
echo 'export KUBECONFIG=$KUBECONFIG:~/.kube/config' >> ~/.bash_profile
-
For Bash shells on Linux:
echo 'export KUBECONFIG=$KUBECONFIG:~/.kube/config' >> ~/.bashrc
-
For PowerShell on Windows:
[System.Environment]::SetEnvironmentVariable('KUBECONFIG', $ENV:KUBECONFIG, 'Machine')
-
-
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.