Create kubeconfig file automatically Create kubeconfig file manually

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 in the Kubernetes documentation. This topic provides two procedures to create or update a kubeconfig file for your Amazon EKS cluster:

Creating it automatically with the Amazon CLI update-kubeconfig command.
Creating it manually using the Amazon 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 Amazon CLI or the Amazon IAM Authenticator for Kubernetes with kubectl for cluster authentication. If you have installed the Amazon CLI on your system, then by default the Amazon 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 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.24, you can use kubectl version 1.23, 1.24, or 1.25 with it. To install or upgrade kubectl, see Installing or updating kubectl.

Create `kubeconfig` file automatically

Prerequisites

Version 2.11.3 or later or 1.27.93 or later of the Amazon CLI installed and configured on your device or Amazon CloudShell. You can check your current version with 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, updating, and uninstalling the Amazon CLI and Quick configuration with aws configure in the Amazon Command Line Interface User Guide. The Amazon CLI version installed in the Amazon CloudShell may 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. Replace region-code with the Amazon Web Services 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.
Test your configuration.
```
kubectl get svc
```
The 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 example values with your own and then running the modified commands.
```
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 (Amazon CLI or Amazon 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 under args:. Replace my-role with the name of the IAM role that you want to perform cluster operations with instead of the default Amazon credential provider chain. For more information, see Set up kubectl to use authentication tokens provided by Amazon IAM Authenticator for Kubernetes on GitHub.
- An Amazon CLI named profile – Remove the # at the start of the env: line, and remove # at the start of the lines under it. Replace aws-profile 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 Amazon Profiles on GitHub.
Amazon CLI
Prerequisite

Version 2.11.3 or later or 1.27.93 or later of the Amazon CLI installed and configured on your device or Amazon CloudShell. You can check your current version with 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, updating, and uninstalling the Amazon CLI and Quick configuration with aws configure in the Amazon Command Line Interface User Guide. The Amazon CLI version installed in the Amazon CloudShell may 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.
```
#!/bin/bash
read -r -d '' KUBECONFIG <<EOF
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: $certificate_data
    server: $cluster_endpoint
  name: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
contexts:
- context:
    cluster: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
    user: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
  name: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
current-context: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
kind: Config
preferences: {}
users:
- name: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: aws
      args:
        - --region
        - $region_code
        - eks
        - get-token
        - --cluster-name
        - $cluster_name
        # - "- --role"
        # - "arn:aws-cn:iam::$account_id:role/my-role"
      # env:
        # - name: "Amazon_PROFILE"
        #   value: "aws-profile"
EOF
echo "${KUBECONFIG}" > ~/.kube/config
```
Amazon IAM Authenticator for Kubernetes
Prerequisite

Version 0.5.9 or later of the Amazon IAM Authenticator for Kubernetes installed on your device. To install it, see Installing aws-iam-authenticator.
```
#!/bin/bash
read -r -d '' KUBECONFIG <<EOF
apiVersion: v1
clusters:
- cluster:
    server: $cluster_endpoint
    certificate-authority-data: $certificate_data
  name: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
contexts:
- context:
    cluster: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
    user: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
  name: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
current-context: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
kind: Config
preferences: {}
users:
- name: arn:aws-cn:eks:$region_code:$account_id:cluster/$cluster_name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: aws-iam-authenticator
      args:
        - "token"
        - "-i"
        - "$cluster_name"
        # - "- --role"
        # - "arn:aws-cn:iam::$account_id:role/my-role"
      # env:
        # - name: "Amazon_PROFILE"
        #   value: "aws-profile"
EOF
echo "${KUBECONFIG}" > ~/.kube/config
```
Add the file path to your KUBECONFIG environment variable so that kubectl 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
```
The 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.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

OIDC identity provider authentication

Installing aws-iam-authenticator

Creating or updating a kubeconfig file for an Amazon EKS cluster

Prerequisites

Create kubeconfig file automatically

Prerequisites

To create your kubeconfig file with the Amazon CLI

Create kubeconfig file manually

To create your kubeconfig file manually

Prerequisite

Prerequisite

Creating or updating a `kubeconfig` file for an Amazon EKS cluster

Create `kubeconfig` file automatically

To create your `kubeconfig` file with the Amazon CLI

Create `kubeconfig` file manually

To create your `kubeconfig` file manually