Getting started with eksctl - Amazon EKS

Getting started with eksctl

This getting started guide helps you to create all of the required resources to get started with Amazon EKS using eksctl, a simple command line utility for creating and managing Kubernetes clusters on Amazon EKS. At the end of this tutorial, you will have a running Amazon EKS cluster that you can deploy applications to.

The procedures in this guide create several resources for you automatically, that you have to create manually when you create your cluster using the AWS Management Console. If you'd rather manually create most of the resources to better understand how they interact with each other, then use the AWS Management Console to create your cluster and compute. For more information, see Getting started with the AWS Management Console.

Prerequisites

This section helps you to install and configure the following tools that you need to create and manage an Amazon EKS cluster.

  • AWS CLI – Command line tools for working with AWS services, including Amazon EKS.

  • eksctl – A command line tool for working with EKS clusters that automates many individual tasks.

  • kubectl – A command line tool for working with Kubernetes clusters.

Install the AWS CLI

You can install the latest version of the AWS CLI for macOS, Linux, or Windows.

[ To install the AWS CLI for macOS ]

  1. If you currently have the AWS CLI installed, determine which version that you have installed.

    aws --version
  2. If you don't have version 1.18.163 or later, or version 2.0.59 or later installed, then install the AWS CLI version 2. For other installation options, or to upgrade your currently installed version 2, see Upgrading the AWS CLI version 2 on macOS.

    curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" sudo installer -pkg AWSCLIV2.pkg -target /

    If you're unable to use the AWS CLI version 2, then ensure that you have the latest version of the AWS CLI version 1 installed using the following command.

    pip3 install awscli --upgrade --user

[ To install the AWS CLI for Linux ]

  1. If you currently have the AWS CLI installed, determine which version that you have installed.

    aws --version
  2. If you don't have version 1.18.163 or later, or version 2.0.59 or later installed, then install the AWS CLI version 2. For other installation options, or to upgrade your currently installed version 2, see Upgrading the AWS CLI version 2 on Linux.

    curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install

    If you're unable to use the AWS CLI version 2, then ensure that you have the latest version of the AWS CLI version 1 installed using the following command.

    pip3 install --upgrade --user awscli

[To install the AWS CLI for Windows]

  1. If you currently have the AWS CLI installed, determine which version that you have installed.

    aws --version
  2. If you don't have either version 1.18.163 or later, or version 2.0.59 or later installed, then install the AWS CLI version 2 using the following steps. For other installation options, or to upgrade your currently installed version 2, see Upgrading the AWS CLI version 2 on Windows.

    1. Download the AWS CLI MSI installer for Windows (64-bit) at https://awscli.amazonaws.com/AWSCLIV2.msi

    2. Run the downloaded MSI installer and follow the onscreen instructions. By default, the AWS CLI installs to C:\Program Files\Amazon\AWSCLIV2.

  3. (Optional) If you're unable to use the AWS CLI version 2, then ensure that you have the latest version of the AWS CLI version 1 installed using the following command.

    pip3 install --user --upgrade awscli

Configure your AWS CLI credentials

Both eksctl and the AWS CLI require that you have AWS credentials configured in your environment. The aws configure command is the fastest way to set up your AWS CLI installation for general use.

$ aws configure AWS Access Key ID [None]: <AKIAIOSFODNN7EXAMPLE> AWS Secret Access Key [None]: <wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY> Default region name [None]: <region-code> Default output format [None]: <json>

When you type this command, the AWS CLI prompts you for four pieces of information: access key, secret access key, AWS Region, and output format. This information is stored in a profile (a collection of settings) named default. This profile is used when you run commands, unless you specify another one.

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

Install eksctl

You can install 0.30.0 version or later of the eksctl command line utility on macOS, Linux, or Windows. For more information, see https://eksctl.io/.

[ To install or upgrade eksctl on macOS using Homebrew ]

The easiest way to get started with Amazon EKS and macOS is by installing eksctl with Homebrew. The eksctl Homebrew recipe installs eksctl and any other dependencies that are required for Amazon EKS, such as kubectl. The recipe also installs the aws-iam-authenticator, which is required if you don't have the AWS CLI version 1.16.156 or higher installed.

  1. If you do not already have Homebrew installed on macOS, install it with the following command.

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
  2. Install the Weaveworks Homebrew tap.

    brew tap weaveworks/tap
  3. Install or upgrade eksctl.

    • Install eksctl with the following command:

      brew install weaveworks/tap/eksctl
    • If eksctl is already installed, run the following command to upgrade:

      brew upgrade eksctl && brew link --overwrite eksctl
  4. Test that your installation was successful with the following command.

    eksctl version
    Note

    The GitTag version should be at least 0.30.0. If not, check your terminal output for any installation or upgrade errors, or manually download an archive of the release from https://github.com/weaveworks/eksctl/releases/download/0.30.0/eksctl_Darwin_amd64.tar.gz, extract eksctl, and then execute it.

[ To install or upgrade eksctl on Linux using curl ]

  1. Download and extract the latest release of eksctl with the following command.

    curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
  2. Move the extracted binary to /usr/local/bin.

    sudo mv /tmp/eksctl /usr/local/bin
  3. Test that your installation was successful with the following command.

    eksctl version
    Note

    The GitTag version should be at least 0.30.0. If not, check your terminal output for any installation or upgrade errors, or replace the address in step 1 with https://github.com/weaveworks/eksctl/releases/download/0.30.0/eksctl_Linux_amd64.tar.gz and complete steps 1-3 again.

[ To install or upgrade eksctl on Windows using Chocolatey ]

  1. If you do not already have Chocolatey installed on your Windows system, see Installing Chocolatey.

  2. Install or upgrade eksctl .

    • Install the binaries with the following command:

      chocolatey install -y eksctl
    • If they are already installed, run the following command to upgrade:

      chocolatey upgrade -y eksctl
  3. Test that your installation was successful with the following command.

    eksctl version
    Note

    The GitTag version should be at least 0.30.0. If not, check your terminal output for any installation or upgrade errors, or manually download an archive of the release from https://github.com/weaveworks/eksctl/releases/download/0.30.0/eksctl_Windows_amd64.zip, extract eksctl, and then execute it.

Install and configure kubectl

Kubernetes uses the kubectl command-line utility for communicating with the cluster API server.

Note

If you used the preceding Homebrew instructions to install eksctl on macOS, then kubectl has already been installed on your system. You can skip to Create your Amazon EKS cluster and compute.

You can install version 1.18 of the kubectl command line utility for macOS, Linux, or Windows. If you need to install a different version to use with a different cluster version, then see Installing kubectl.

[ To install kubectl on macOS ]

  1. Download the Amazon EKS vended kubectl binary that corresponds to the Region that your cluster is in.

    • All Regions other than China Regions.

      curl -o kubectl https://amazon-eks.s3.us-west-2.amazonaws.com/1.18.8/2020-09-18/bin/darwin/amd64/kubectl
    • Beijing and Ningxia China Regions.

      curl -o kubectl https://amazon-eks.s3.cn-north-1.amazonaws.com.cn/1.18.8/2020-09-18/bin/darwin/amd64/kubectl
  2. (Optional) Verify the downloaded binary with the SHA-256 sum.

    1. Download the SHA-256 sum that corresponds to the Region that your cluster is in.

      • All Regions other than China Regions.

        curl -o kubectl.sha256 https://amazon-eks.s3.us-west-2.amazonaws.com/1.18.8/2020-09-18/bin/darwin/amd64/kubectl.sha256
      • Beijing and Ningxia China Regions.

        curl -o kubectl.sha256 https://amazon-eks.s3.cn-north-1.amazonaws.com.cn/1.18.8/2020-09-18/bin/darwin/amd64/kubectl.sha256
    2. Check the SHA-256 sum.

      openssl sha1 -sha256 kubectl
    3. Compare the generated SHA-256 sum in the command output against your downloaded SHA-256 file. The two should match.

  3. Apply execute permissions to the binary.

    chmod +x ./kubectl
  4. Move kubectl to a folder that is in your path.

    • If you don't already have a version of kubectl installed, then move the binary to a folder that's already in your PATH.

      sudo mv ./kubectl /usr/local/bin
    • If you already have a version of kubectl installed, then we recommend creating a $HOME/bin/kubectl folder, moving the binary to that folder, and ensuring that $HOME/bin comes first in your $PATH.

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

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

      echo 'export PATH=$PATH:$HOME/bin' >> ~/.bash_profile
  5. After you install kubectl, you can verify its version with the following command:

    kubectl version --short --client

[ To install kubectl on Linux ]

  1. Download the Amazon EKS vended kubectl binary that corresponds to the Region that your cluster is in.

    • All Regions other than China Regions.

      curl -o kubectl https://amazon-eks.s3.us-west-2.amazonaws.com/1.18.8/2020-09-18/bin/linux/amd64/kubectl
    • Beijing and Ningxia China Regions.

      curl -o kubectl https://amazon-eks.s3.cn-north-1.amazonaws.com.cn/1.18.8/2020-09-18/bin/linux/amd64/kubectl
  2. (Optional) Verify the downloaded binary with the SHA-256 sum.

    1. Download the SHA-256 sum that corresponds to the Region that your cluster is in.

      • All Regions other than China Regions.

        curl -o kubectl.sha256 https://amazon-eks.s3.us-west-2.amazonaws.com/1.18.8/2020-09-18/bin/linux/amd64/kubectl.sha256
      • Beijing and Ningxia China Regions.

        curl -o kubectl.sha256 https://amazon-eks.s3.cn-north-1.amazonaws.com.cn/1.18.8/2020-09-18/bin/linux/amd64/kubectl.sha256
    2. Check the SHA-256 sum.

      openssl sha1 -sha256 kubectl
    3. Compare the generated SHA-256 sum in the command output against your downloaded SHA-256 file. The two should match.

  3. Apply execute permissions to the binary.

    chmod +x ./kubectl
  4. Move kubectl to a folder that is in your path.

    • If you don't already have a version of kubectl installed, then move the binary to a folder in your PATH.

      sudo mv ./kubectl /usr/local/bin
    • If you already have a version of kubectl installed, then we recommend creating a $HOME/bin/kubectl folder, moving the binary to that folder, and ensuring that $HOME/bin comes first in your $PATH.

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

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

      echo 'export PATH=$PATH:$HOME/bin' >> ~/.bash_profile
      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.

  5. After you install kubectl, you can verify its version with the following command:

    kubectl version --short --client

[ To install kubectl on Windows ]

  1. Open a PowerShell terminal.

  2. Download the Amazon EKS vended kubectl binary that corresponds to the region that your cluster is in.

    • All Regions other than China Regions.

      curl -o kubectl.exe https://amazon-eks.s3.us-west-2.amazonaws.com/1.18.8/2020-09-18/bin/windows/amd64/kubectl.exe
    • Beijing and Ningxia China Regions.

      curl -o kubectl.exe https://amazon-eks.s3.cn-north-1.amazonaws.com.cn/1.18.8/2020-09-18/bin/windows/amd64/kubectl.exe
  3. (Optional) Verify the downloaded binary with the SHA-256 sum.

    1. Download the SHA-256 sum that corresponds to the region that your cluster is in.

      • All Regions other than China Regions.

        curl -o kubectl.exe.sha256 https://amazon-eks.s3.us-west-2.amazonaws.com/1.18.8/2020-09-18/bin/windows/amd64/kubectl.exe.sha256
      • Beijing and Ningxia China Regions.

        curl -o kubectl.exe.sha256 https://amazon-eks.s3.cn-north-1.amazonaws.com.cn/1.18.8/2020-09-18/bin/windows/amd64/kubectl.exe.sha256
    2. Check the SHA-256 sum.

      Get-FileHash kubectl.exe
    3. Compare the generated SHA-256 sum in the command output against your downloaded SHA-256 file. The two should match, although the PowerShell output will be uppercase.

  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.

  5. After you install kubectl, you can verify its version with the following command:

    kubectl version --short --client

Create your Amazon EKS cluster and compute

This section helps you to create an Amazon EKS cluster with a compute option to run your applications. The latest Kubernetes version available in Amazon EKS is installed so that you can take advantage of the latest Kubernetes and Amazon EKS features. Some features are not available on older versions of Kubernetes.

Important

Make sure that the AWS Security Token Service (STS) endpoint for the Region that your cluster is in is enabled for your account. If the endpoint is not enabled, then nodes will fail to join the cluster during cluster creation. For more information, see Activating and deactivating AWS STS in an AWS Region.

Select one of the following compute options. To learn more about each option, see Amazon EKS compute. After your cluster is deployed, you can add other options, if you choose.

  • Fargate – Linux – Select this option if you want to run Linux applications on AWS Fargate.

  • Managed nodes – Linux – Select this option if you want to run Amazon Linux applications on Amazon EC2 instances

  • Self-managed nodes – Windows – Select this option if you want to run Windows applications on Amazon EC2 instances. You can also run Linux applications using this option because even if you only need to run Windows applications, your cluster must still have at least one Linux node.

Though not covered in this guide, you can also add Bottlerocket nodes to your cluster. For more information, see Launching self-managed Bottlerocket nodes.

[ Fargate – Linux ]

Note

Create your Amazon EKS cluster with Fargate support with the following command. You can replace <my-cluster> with your own value and you can replace <us-west-2> with any Amazon EKS Fargate supported Region.

We recommend that you deploy version 1.18 (but first remove the <>). If you replace 1.18, then read the important Amazon EKS release notes for the version and install the corresponding version of kubectl.

eksctl create cluster \ --name <my-cluster> \ --version <1.18> \ --region <us-west-2> \ --fargate

Your new Amazon EKS cluster is created without a node group. Eksctl creates a pod execution role, a Fargate profile for the default and kube-system namespaces, and it patches the coredns deployment so that it can run on Fargate. For more information see AWS Fargate.

[ Managed nodes – Linux ]

You can create the nodes with or without a launch template. A launch template allows for greater customization, to include the ability to deploy a custom AMI.

Create your Amazon EKS cluster and Linux nodes without a launch template with the following command. Replace the <example values> with your own values. You can replace <us-west-2> with any Amazon EKS supported Region.

Important

Do not use eksctl to create a cluster or nodes in an AWS Region where you have AWS Outposts, AWS Wavelength, or AWS Local Zones enabled. Create a cluster and self-managed nodes using the Amazon EC2 API or AWS CloudFormation instead. For more information, see To launch self-managed nodes using the AWS Management Console and To launch self-managed Windows nodes using the AWS Management Console.

Important

Amazon EKS nodes are standard Amazon EC2 instances, and you are billed for them based on normal Amazon EC2 instance prices. For more information, see Amazon EC2 pricing.

We recommend that you deploy version 1.18 (but first remove the <>). If you replace 1.18, then read the important Amazon EKS release notes for the version and install the corresponding version of kubectl.

Though --ssh-public-key is optional, we highly recommend that you specify it when you create your node group with a cluster. This option enables SSH access to the nodes in your managed node group. Enabling SSH access allows you to connect to your instances and gather diagnostic information if there are issues. You cannot enable remote access after the node group is created. If you don't have a public key, then you can create a key pair for Amazon EC2 to specify for --ssh-public-key. Ensure that you create the key in the same Region that you create the cluster in.

eksctl create cluster \ --name <my-cluster> \ --version <1.18> \ --region <us-west-2> \ --nodegroup-name <linux-nodes> \ --nodes <3> \ --nodes-min <1> \ --nodes-max <4> \ --ssh-access \ --ssh-public-key <name-of-ec2-keypair> \ --managed

Create your Amazon EKS cluster and Amazon Linux nodes with a launch template. The launch template must already exist and must meet the requirements specified in Launch template configuration basics. Create a file named <cluster-node-group-lt.yaml> with the following contents, replacing the example <values> with your own values. Several settings that you specify when deploying without a launch template are moved into the launch template. If you don't specify a version, the template's default version is used.

--- apiVersion: eksctl.io/v1alpha5 kind: ClusterConfig metadata: name: <my-cluster> region: <us-west-2> version: '<1.18>' managedNodeGroups: - name: <ng-linux> launchTemplate: id: lt-<id> version: "<1>"

Create the cluster and node group with the following command.

eksctl create cluster --config-file <cluster-node-group-lt>.yaml

Output:

You'll see several lines of output as the cluster and nodes are created. The last line of output is similar to the following example line.

[✓] EKS cluster "<my-cluster>" in "<us-west-2>" region is ready

If nodes fail to join the cluster, then see Nodes fail to join cluster in the Troubleshooting guide.

[ Self-managed nodes – Windows ]

Familiarize yourself with the Windows support considerations, which include supported values for instanceType in the example text below. Replace the example <values> with your own values.

We recommend that you deploy version 1.18. If you must deploy an earlier version, then you can only replace it with version 1.16 or later. If you change 1.18, then read the important Amazon EKS release notes for the version and install the corresponding version of kubectl.

Important

Do not use eksctl to create a cluster or nodes in an AWS Region where you have AWS Outposts, AWS Wavelength, or AWS Local Zones enabled. Create a cluster and self-managed nodes using the Amazon EC2 API or AWS CloudFormation instead. For more information, see To launch self-managed nodes using the AWS Management Console and To launch self-managed Windows nodes using the AWS Management Console.

Important

Amazon EKS nodes are standard Amazon EC2 instances, and you are billed for them based on normal Amazon EC2 instance prices. For more information, see Amazon EC2 pricing.

  1. Save the text below to a file named cluster-spec.yaml. The configuration file is used to create a cluster with a self-managed Windows node group and a managed Linux node group. Even if you only want to run Windows applications in your cluster, all Amazon EKS clusters must contain at least one Linux node, though we recommend that you create at least two Linux nodes for availability purposes. For more information about using a config file with eksctl, the config file schema, and config file samples, see the eksctl documentation. We recommend that you deploy version 1.18 (but first remove the <>). If you replace 1.18, then read the important Amazon EKS release notes for the version and install the corresponding version of kubectl.

    --- apiVersion: eksctl.io/v1alpha5 kind: ClusterConfig metadata: name: <my-cluster> region: <<us-west-2> version: '<1.18>' managedNodeGroups: - name: <linux-ng> instanceType: <m5.large> minSize: <2> nodeGroups: - name: <windows-ng> instanceType: <m5.large> minSize: <2> volumeSize: <100> amiFamily: <WindowsServer2019FullContainer>
  2. Create your Amazon EKS cluster and Windows and Linux nodes with the following command.

    eksctl create cluster -f cluster-spec.yaml --install-vpc-controllers
    Note

    For more information about the available options for eksctl create cluster , see the project README on GitHub or view the help page with the following command.

    eksctl create cluster --help

    Output:

    You'll see several lines of output as the cluster and nodes are created. The last line of output is similar to the following example line.

    [✓] EKS cluster "<my-cluster>" in "<us-west-2>" region is ready

    If nodes fail to join the cluster, then see Nodes fail to join cluster in the Troubleshooting guide.

    Cluster provisioning usually takes between 10 and 15 minutes.

  3. When your cluster is ready, test that your kubectl configuration is correct.

    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
  4. (Linux accelerated AMI nodes only) If you chose an accelerated AMI instance type and the Amazon EKS optimized accelerated AMI , then you must apply the NVIDIA device plugin for Kubernetes as a DaemonSet on your cluster with the following command.

    kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.6.0/nvidia-device-plugin.yml

Next steps

Now that you have a working Amazon EKS cluster with nodes, you are ready to start installing Kubernetes add-ons and deploying applications to your cluster. The following documentation topics help you to extend the functionality of your cluster.