Create a kubeconfig for Amazon EKS - Amazon EKS
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.

Create a kubeconfig for Amazon EKS

In this section, you create a kubeconfig file for your cluster (or update an existing one).

This section offers two procedures to create or update your kubeconfig. You can quickly create or update a kubeconfig with the Amazon CLI update-kubeconfig command automatically by using the Amazon CLI, or you can create a kubeconfig 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 will use the same credentials that are returned with the following command:

aws sts get-caller-identity

For more information, see Configuring the Amazon CLI in the Amazon Command Line Interface User Guide.

Create kubeconfig automatically

To create your kubeconfig file with the Amazon CLI

  1. Ensure that you have version 1.16.156 or later of the Amazon CLI installed. To install or upgrade the Amazon CLI, see Installing the Amazon CLI in the Amazon Command Line Interface User Guide.

    Note

    Your system's Python version must be 2.7.9 or later. Otherwise, you receive hostname doesn't match errors with Amazon CLI calls to Amazon EKS.

    You can check your Amazon CLI version with the following command:

    aws --version
    Important

    Package managers such yum , apt-get , or Homebrew for macOS are often behind several versions of the Amazon CLI. To ensure that you have the latest version, see Installing the Amazon CLI in the Amazon Command Line Interface User Guide.

  2. Use the Amazon CLI update-kubeconfig command to create or update your kubeconfig for your cluster.

    • By default, the resulting configuration file is created at the default kubeconfig path (.kube/config) in your home directory or merged with an existing kubeconfig 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 entity 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 more information, see the help page with the aws eks update-kubeconfig help command or see update-kubeconfig in the Amazon CLI Command Reference.

    Note

    To run the following command, you must have permission to use the eks:DescribeCluster API action with the cluster that you specify. For more information, see Amazon EKS identity-based policy examples.

    aws eks --region <region-code> update-kubeconfig --name <cluster_name>
  3. Test your configuration.

    kubectl get svc
    Note

    If you receive any authorization or resource type errors, see Unauthorized or access denied (kubectl) in the troubleshooting section.

    Output:

    NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE svc/kubernetes ClusterIP 10.100.0.1 <none> 443/TCP 1m

Create kubeconfig manually

To create your kubeconfig file manually

  1. Create the default ~/.kube directory if it does not already exist.

    mkdir -p ~/.kube
  2. Open your favorite text editor and copy one of the kubeconfig code blocks below into it, depending on your preferred client token method.

    • To use the Amazon CLI aws eks get-token command (requires version 1.16.156 or later of the Amazon CLI):

      apiVersion: v1 clusters: - cluster: server: <endpoint-url> certificate-authority-data: <base64-encoded-ca-cert> name: kubernetes contexts: - context: cluster: kubernetes user: aws name: aws current-context: aws kind: Config preferences: {} users: - name: aws user: exec: apiVersion: client.authentication.k8s.io/v1alpha1 command: aws args: - "eks" - "get-token" - "--cluster-name" - "<cluster-name>" # - "--role-arn" # - "<role-arn>" # env: # - name: AWS_PROFILE # value: "<aws-profile>"
    • To use the Amazon IAM authenticator for Kubernetes:

      apiVersion: v1 clusters: - cluster: server: <endpoint-url> certificate-authority-data: <base64-encoded-ca-cert> name: kubernetes contexts: - context: cluster: kubernetes user: aws name: aws current-context: aws kind: Config preferences: {} users: - name: aws user: exec: apiVersion: client.authentication.k8s.io/v1alpha1 command: aws-iam-authenticator args: - "token" - "-i" - "<cluster-name>" # - "-r" # - "<role-arn>" # env: # - name: AWS_PROFILE # value: "<aws-profile>"
  3. Replace the <endpoint-url> with the endpoint URL that was created for your cluster.

  4. Replace the <base64-encoded-ca-cert> with the certificateAuthority.data that was created for your cluster.

  5. Replace the <cluster-name> with your cluster name.

  6. (Optional) To assume an IAM role to perform cluster operations instead of the default Amazon credential provider chain, uncomment the -r or --role and <role-arn> lines and substitute an IAM role ARN to use with your user.

  7. (Optional) To always use a specific named Amazon credential profile (instead of the default Amazon credential provider chain), uncomment the env lines and substitute <aws-profile> with the profile name to use.

  8. Save the file to the default kubectl folder, with your cluster name in the file name. For example, if your cluster name is <devel>, save the file to ~/.kube/config-<devel>.

  9. Add that 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-<devel>
    • For PowerShell on Windows:

      $ENV:KUBECONFIG="{0};{1}" -f $ENV:KUBECONFIG, "$ENV:userprofile\.kube\config-<devel>"
  10. (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-<devel>' >> ~/.bash_profile
    • For Bash shells on Linux:

      echo 'export KUBECONFIG=$KUBECONFIG:~/.kube/config-<devel>' >> ~/.bashrc
    • For PowerShell on Windows:

      [System.Environment]::SetEnvironmentVariable('KUBECONFIG', $ENV:KUBECONFIG, 'Machine')
  11. Test your configuration.

    kubectl get svc
    Note

    If you receive any authorization or resource type errors, see Unauthorized or access denied (kubectl) in the troubleshooting section.

    Output:

    NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE svc/kubernetes ClusterIP 10.100.0.1 <none> 443/TCP 1m