Set up kubectl and eksctl - Amazon EKS
Install or update kubectlInstall eksctlNext steps

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.

Set up kubectl and eksctl

Kubectl is a command line tool that you use to communicate with the Kubernetes API server. The kubectl binary is available in many operating system package managers. Using a package manager for your installation is often easier than a manual download and install process. The eksctl command lets you create and modify Amazon EKS clusters.

Topics on this page help you install and set up these tools:

Install or update kubectl

This topic helps you to download and install, or update, the kubectl binary on your device. The binary is identical to the upstream community versions. The binary is not unique to Amazon EKS or AWS. Use the steps below to get the specific version of kubectl that you need, although many builders simply run brew install kubectl to install it.

Note

You must use a kubectl version that is within one minor version difference of your Amazon EKS cluster control plane. For example, a 1.30 kubectl client works with Kubernetes 1.29, 1.30, and 1.31 clusters.

To install or update kubectl

  1. Determine whether you already have kubectl installed on your device.

    kubectl version --client

    If you have kubectl installed in the path of your device, the example output includes information similar to the following. If you want to update the version that you currently have installed with a later version, complete the next step, making sure to install the new version in the same location that your current version is in.

    Client Version: v1.31.X-eks-1234567

    If you receive no output, then you either don't have kubectl installed, or it's not installed in a location that's in your device's path.

  2. Install or update kubectl on macOS, Linux, and Windows operating systems.

    macOS
    To install or update kubectl on macOS

    1. Download the binary for your cluster's Kubernetes version from Amazon S3.

      • Kubernetes 1.31

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.0/2024-09-12/bin/darwin/amd64/kubectl

      • Kubernetes 1.30

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.4/2024-09-11/bin/darwin/amd64/kubectl

      • Kubernetes 1.29

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.8/2024-09-11/bin/darwin/amd64/kubectl

      • Kubernetes 1.28

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.13/2024-09-11/bin/darwin/amd64/kubectl

      • Kubernetes 1.27

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.27.16/2024-09-11/bin/darwin/amd64/kubectl

      • Kubernetes 1.26

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-09-11/bin/darwin/amd64/kubectl

      • Kubernetes 1.25

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.25.16/2024-09-11/bin/darwin/amd64/kubectl

      • Kubernetes 1.24

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.24.17/2024-09-11/bin/darwin/amd64/kubectl

      • Kubernetes 1.23

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.23.17/2024-09-11/bin/darwin/amd64/kubectl

      • Kubernetes 1.22

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.22.17/2024-09-11/bin/darwin/amd64/kubectl

      • Kubernetes 1.21

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.21.14/2024-07-12/bin/darwin/amd64/kubectl

    2. (Optional) Verify the downloaded binary with the SHA-256 checksum for your binary.

      1. Download the SHA-256 checksum for your cluster's Kubernetes version.

        • Kubernetes 1.31

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.0/2024-09-12/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.30

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.4/2024-09-11/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.29

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.8/2024-09-11/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.28

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.13/2024-09-11/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.27

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.27.16/2024-09-11/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.26

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-09-11/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.25

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.25.16/2024-09-11/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.24

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.24.17/2024-09-11/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.23

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.23.17/2024-09-11/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.22

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.22.17/2024-09-11/bin/darwin/amd64/kubectl.sha256

        • Kubernetes 1.21

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.21.14/2024-07-12/bin/darwin/amd64/kubectl.sha256

      2. Check the SHA-256 checksum for your downloaded binary.

        openssl sha1 -sha256 kubectl

      3. Make sure that the generated checksum in the output matches in the checksum in the downloaded kubectl.sha256 file.

    3. Apply execute permissions to the binary.

      chmod +x ./kubectl

    4. Copy the binary to a folder in your PATH. If you have already installed a version of kubectl, then we recommend creating a $HOME/bin/kubectl and ensuring that $HOME/bin comes first in your $PATH.

      mkdir -p $HOME/bin && cp ./kubectl $HOME/bin/kubectl && export PATH=$HOME/bin:$PATH

    5. (Optional) Add the $HOME/bin path to your shell initialization file so that it is configured when you open a shell.

      echo 'export PATH=$HOME/bin:$PATH' >> ~/.bash_profile
    Linux (amd64)
    To install or update kubectl on Linux (amd64)

    1. Download the kubectl binary for your cluster's Kubernetes version from Amazon S3.

      • Kubernetes 1.31

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.0/2024-09-12/bin/linux/amd64/kubectl

      • Kubernetes 1.30

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.4/2024-09-11/bin/linux/amd64/kubectl

      • Kubernetes 1.29

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.8/2024-09-11/bin/linux/amd64/kubectl

      • Kubernetes 1.28

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.13/2024-09-11/bin/linux/amd64/kubectl

      • Kubernetes 1.27

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.27.16/2024-09-11/bin/linux/amd64/kubectl

      • Kubernetes 1.26

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-09-11/bin/linux/amd64/kubectl

      • Kubernetes 1.25

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.25.16/2024-09-11/bin/linux/amd64/kubectl

      • Kubernetes 1.24

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.24.17/2024-09-11/bin/linux/amd64/kubectl

      • Kubernetes 1.23

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.23.17/2024-09-11/bin/linux/amd64/kubectl

      • Kubernetes 1.22

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.22.17/2024-09-11/bin/linux/amd64/kubectl

      • Kubernetes 1.21

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.21.14/2024-07-12/bin/linux/amd64/kubectl

    2. (Optional) Verify the downloaded binary with the SHA-256 checksum for your binary.

      1. Download the SHA-256 checksum for your cluster's Kubernetes version from Amazon S3 using the command for your device's hardware platform.

        • Kubernetes 1.31

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.0/2024-09-12/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.30

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.4/2024-09-11/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.29

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.8/2024-09-11/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.28

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.13/2024-09-11/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.27

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.27.16/2024-09-11/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.26

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-09-11/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.25

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.25.16/2024-09-11/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.24

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.24.17/2024-09-11/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.23

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.23.17/2024-09-11/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.22

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.22.17/2024-09-11/bin/linux/amd64/kubectl.sha256

        • Kubernetes 1.21

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.21.14/2024-07-12/bin/linux/amd64/kubectl.sha256

      2. Check the SHA-256 checksum for your downloaded binary with one of the following commands.

        • sha256sum -c kubectl.sha256

          When using this command, make sure that you see the following output:

          kubectl: OK
        • openssl sha1 -sha256 kubectl

          When using this command, make sure that the generated checksum in the output matches in the checksum in the downloaded kubectl.sha256 file.

    3. Apply execute permissions to the binary.

      chmod +x ./kubectl

    4. Copy the binary to a folder in your PATH. If you have already installed a version of kubectl, then we recommend creating a $HOME/bin/kubectl and ensuring that $HOME/bin comes first in your $PATH.

      mkdir -p $HOME/bin && cp ./kubectl $HOME/bin/kubectl && export PATH=$HOME/bin:$PATH

    5. (Optional) Add the $HOME/bin path to your shell initialization file so that it is configured when you open a shell.

      Note

      This step assumes you are using the Bash shell; if you are using another shell, change the command to use your specific shell initialization file.

      echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc
    Linux (arm64)
    To install or update kubectl on Linux (arm64)

    1. Download the kubectl binary for your cluster's Kubernetes version from Amazon S3.

      • Kubernetes 1.31

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.0/2024-09-12/bin/linux/arm64/kubectl

      • Kubernetes 1.30

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.4/2024-09-11/bin/linux/arm64/kubectl

      • Kubernetes 1.29

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.8/2024-09-11/bin/linux/arm64/kubectl

      • Kubernetes 1.28

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.13/2024-09-11/bin/linux/arm64/kubectl

      • Kubernetes 1.27

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.27.16/2024-09-11/bin/linux/arm64/kubectl

      • Kubernetes 1.26

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-09-11/bin/linux/arm64/kubectl

      • Kubernetes 1.25

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.25.16/2024-09-11/bin/linux/arm64/kubectl

      • Kubernetes 1.24

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.24.17/2024-09-11/bin/linux/arm64/kubectl

      • Kubernetes 1.23

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.23.17/2024-09-11/bin/linux/arm64/kubectl

      • Kubernetes 1.22

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.22.17/2024-09-11/bin/linux/arm64/kubectl

      • Kubernetes 1.21

        curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.21.14/2024-07-12/bin/linux/arm64/kubectl

    2. (Optional) Verify the downloaded binary with the SHA-256 checksum for your binary.

      1. Download the SHA-256 checksum for your cluster's Kubernetes version from Amazon S3 using the command for your device's hardware platform.

        • Kubernetes 1.31

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.0/2024-09-12/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.30

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.4/2024-09-11/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.29

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.8/2024-09-11/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.28

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.13/2024-09-11/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.27

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.27.16/2024-09-11/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.26

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-09-11/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.25

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.25.16/2024-09-11/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.24

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.24.17/2024-09-11/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.23

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.23.17/2024-09-11/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.22

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.22.17/2024-09-11/bin/linux/arm64/kubectl.sha256

        • Kubernetes 1.21

          curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.21.14/2024-07-12/bin/linux/arm64/kubectl.sha256

      2. Check the SHA-256 checksum for your downloaded binary with one of the following commands.

        • sha256sum -c kubectl.sha256

          When using this command, make sure that you see the following output:

          kubectl: OK
        • openssl sha1 -sha256 kubectl

          When using this command, make sure that the generated checksum in the output matches in the checksum in the downloaded kubectl.sha256 file.

    3. Apply execute permissions to the binary.

      chmod +x ./kubectl

    4. Copy the binary to a folder in your PATH. If you have already installed a version of kubectl, then we recommend creating a $HOME/bin/kubectl and ensuring that $HOME/bin comes first in your $PATH.

      mkdir -p $HOME/bin && cp ./kubectl $HOME/bin/kubectl && export PATH=$HOME/bin:$PATH

    5. (Optional) Add the $HOME/bin path to your shell initialization file so that it is configured when you open a shell.

      Note

      This step assumes you are using the Bash shell; if you are using another shell, change the command to use your specific shell initialization file.

      echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc
    Windows
    To install or update kubectl on Windows

    1. Open a PowerShell terminal.

    2. Download the kubectl binary for your cluster's Kubernetes version from Amazon S3.

      • Kubernetes 1.31

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.0/2024-09-12/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.30

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.4/2024-09-11/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.29

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.8/2024-09-11/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.28

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.13/2024-09-11/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.27

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.27.16/2024-09-11/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.26

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-09-11/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.25

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.25.16/2024-09-11/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.24

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.24.17/2024-09-11/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.23

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.23.17/2024-09-11/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.22

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.22.17/2024-09-11/bin/windows/amd64/kubectl.exe

      • Kubernetes 1.21

        curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.21.14/2024-07-12/bin/windows/amd64/kubectl.exe

    3. (Optional) Verify the downloaded binary with the SHA-256 checksum for your binary.

      1. Download the SHA-256 checksum for your cluster's Kubernetes version for Windows.

        • Kubernetes 1.31

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.31.0/2024-09-12/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.30

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.30.4/2024-09-11/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.29

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.29.8/2024-09-11/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.28

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.28.13/2024-09-11/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.27

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.27.16/2024-09-11/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.26

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.26.15/2024-09-11/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.25

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.25.16/2024-09-11/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.24

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.24.17/2024-09-11/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.23

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.23.17/2024-09-11/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.22

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.22.17/2024-09-11/bin/windows/amd64/kubectl.exe.sha256

        • Kubernetes 1.21

          curl.exe -O https://s3.us-west-2.amazonaws.com/amazon-eks/1.21.14/2024-07-12/bin/windows/amd64/kubectl.exe.sha256

      2. Check the SHA-256 checksum for your downloaded binary.

        Get-FileHash kubectl.exe

      3. Make sure that the generated checksum in the output matches in the checksum in the downloaded kubectl.sha256 file. The PowerShell output should be an uppercase equivalent string of characters.

    4. Copy the binary to a folder in your PATH. If you have an existing directory in your PATH that you use for command line utilities, copy the binary to that directory. Otherwise, complete the following steps.

      1. Create a new directory for your command line binaries, such as C:\bin.

      2. Copy the kubectl.exe binary to your new directory.

      3. Edit your user or system PATH environment variable to add the new directory to your PATH.

      4. Close your PowerShell terminal and open a new one to pick up the new PATH variable.

  3. After you install kubectl, you can verify its version.

    kubectl version --client

  4. When first installing kubectl, it isn't yet configured to communicate with any server. We will cover this configuration as needed in other procedures. If you ever need to update the configuration to communicate with a particular cluster, you can run the following command. Replace region-code with the AWS Region that your cluster is in. Replace my-cluster with the name of your cluster.

    aws eks update-kubeconfig --region region-code --name my-cluster

  5. Consider configuring auto completion, which lets you use the tab key to complete kubectl subcommands after typing the first few letters. See Kubectl autocomplete in the Kubernetes documentation for details.

Install eksctl

The eksctl CLI is used to work with EKS clusters. It automates many individual tasks. See Installation in the eksctl documentation for instructions on installing eksctl.

When using eksctl the IAM security principal that you're using must have permissions to work with Amazon EKS IAM roles, service linked roles, AWS CloudFormation, a VPC, and related resources. For more information, see Actions, resources, and condition keys for Amazon Elastic Container Service for Kubernetes and Using service-linked roles in the IAM User Guide. You must complete all steps in this guide as the same user. To check the current user, run the following command:

aws sts get-caller-identity

Next steps