Amazon EKS CLI

eksctl cheatsheet — create, manage, delete EKS clusters and nodegroups. eksctl create cluster, eksctl create nodegroup, eksctl upgrade. Full AWS EKS CLI reference.

10 min read

What it is

The eksctl command-line tool for creating and managing Kubernetes clusters on Amazon Elastic Kubernetes Service (EKS). You reach for it when you need to provision, update, or delete EKS clusters and their associated resources quickly and repeatably.

Installation

Linux / macOS

curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
sudo mv /tmp/eksctl /usr/local/bin
eksctl version

Windows (using Chocolatey)

choco install eksctl
eksctl version

Windows (manual download)

  1. Download the latest release from the eksctl GitHub releases page.
  2. Extract the eksctl.exe file.
  3. Add the directory containing eksctl.exe to your system’s PATH environment variable.
  4. Open a new command prompt or PowerShell window and run:
    eksctl version

Core Concepts

  • Cluster Configuration File: eksctl heavily relies on YAML configuration files to define cluster desired state. This allows for declarative, repeatable cluster creation.
  • Node Groups: EKS clusters run worker nodes. eksctl manages these via "Node Groups," which are managed groups of EC2 instances that form your Kubernetes worker fleet. This can include managed node groups (recommended) or self-managed ones.
  • Addons: EKS supports managed addons like kube-proxy, coredns, and the AWS VPC CNI. eksctl can manage the installation and updates of these.
  • IAM Roles: EKS requires specific IAM roles for the control plane and worker nodes. eksctl automatically creates and configures these for you.

Commands / Usage

Cluster Creation

  • Create a basic cluster with default settings:

    eksctl create cluster --name my-cluster --region us-west-2

    Creates an EKS cluster named my-cluster in us-west-2 with a default node group.

  • Create a cluster with a specific Kubernetes version and instance type:

    eksctl create cluster \
  --name my-cluster-v1-27 \
  --region eu-central-1 \
  --version 1.27 \
  --nodegroup-name standard-workers \
  --node-type t3.medium \
  --nodes 3

    Creates an EKS cluster named my-cluster-v1-27 in eu-central-1 running Kubernetes 1.27, with a node group named standard-workers using 3 t3.medium instances.

  • Create a cluster using a configuration file:

    eksctl create cluster -f cluster.yaml

    Creates an EKS cluster defined by the cluster.yaml configuration file.

  • Create a cluster with private networking:

    eksctl create cluster \
  --name private-cluster \
  --region us-east-1 \
  --vpc-private-subnets subnet-0abcd1234efgh5678,subnet-0ijkl9876mnop5432 \
  --vpc-public-subnets subnet-0wxyz9876uvts5432,subnet-0rqpo8765nmkl4321 \
  --without-nodegroup

    Creates a cluster in us-east-1 using specified private and public subnets, and does not create a default node group (you’ll add one later).

  • Create a cluster with Fargate:

    eksctl create cluster \
  --name fargate-cluster \
  --region ap-southeast-2 \
  --fargate-profile-name default \
  --fargate-profile-selectors namespace=default

    Creates an EKS cluster in ap-southeast-2 with a default Fargate profile that applies to the default namespace.

Cluster Management

  • List available EKS clusters:

    eksctl get cluster --region us-west-2

    Lists all EKS clusters in the us-west-2 region.

  • Describe a cluster:

    eksctl get cluster --name my-cluster --region us-west-2 -o json

    Gets detailed information about my-cluster in us-west-2 and outputs it as JSON.

  • Update a cluster’s Kubernetes version:

    eksctl upgrade cluster --name my-cluster --region us-west-2 --version 1.28

    Initiates an upgrade for my-cluster in us-west-2 to Kubernetes version 1.28.

  • Update a cluster’s cloud provider configuration (e.g., tags):

    eksctl utils update-cluster-logging --cluster my-cluster --region us-west-2 --enable-audit --enable-api --enable-authenticator --enable-controller-manager --enable-scheduler

    Enables various control plane logging types for my-cluster in us-west-2.

  • Delete a cluster:

    eksctl delete cluster --name my-cluster --region us-west-2

    Deletes the EKS cluster named my-cluster in us-west-2, including all associated resources like node groups and the VPC (if created by eksctl).

Node Group Management

  • List node groups for a cluster:

    eksctl get nodegroup --cluster my-cluster --region us-west-2

    Lists all node groups associated with my-cluster in us-west-2.

  • Describe a node group:

    eksctl get nodegroup --cluster my-cluster --region us-west-2 --name standard-workers -o json

    Gets detailed information about the standard-workers node group for my-cluster in us-west-2.

  • Create a new node group for an existing cluster:

    eksctl create nodegroup \
  --cluster my-cluster \
  --region us-west-2 \
  --name gpu-workers \
  --node-type g4dn.xlarge \
  --nodes 2 \
  --node-private-networking \
  --asg-access \
  --external-dns-access \
  --full-ecr-access \
  --alb-ingress-access

    Adds a new node group named gpu-workers with 2 g4dn.xlarge instances to my-cluster in us-west-2, granting it specific IAM permissions for common Kubernetes add-ons.

  • Update a node group (e.g., scale up/down):

    eksctl scale nodegroup \
  --cluster my-cluster \
  --region us-west-2 \
  --name standard-workers \
  --nodes 5

    Scales the standard-workers node group for my-cluster in us-west-2 to have 5 nodes.

  • Update a node group’s instance type (requires recreation):

    eksctl replace nodegroup --cluster my-cluster --region us-west-2 --name old-type-workers --new-node-type m5.xlarge

    Replaces the old-type-workers node group with a new one using m5.xlarge instances. This will terminate the old nodes and create new ones.

  • Delete a node group:

    eksctl delete nodegroup --cluster my-cluster --region us-west-2 --name gpu-workers

    Deletes the gpu-workers node group from my-cluster in us-west-2.

Addon Management

  • List addons for a cluster:

    eksctl get addon --cluster my-cluster --region us-west-2

    Lists all managed addons for my-cluster in us-west-2.

  • Create an addon:

    eksctl create addon --cluster my-cluster --region us-west-2 --name vpc-cni --version 1.12.0-eksbuild.1

    Installs the AWS VPC CNI addon version 1.12.0-eksbuild.1 on my-cluster in us-west-2.

  • Update an addon:

    eksctl update addon --cluster my-cluster --region us-west-2 --name vpc-cni --version 1.13.1-eksbuild.1

    Updates the AWS VPC CNI addon on my-cluster in us-west-2 to version 1.13.1-eksbuild.1.

  • Delete an addon:

    eksctl delete addon --cluster my-cluster --region us-west-2 --name vpc-cni

    Deletes the AWS VPC CNI addon from my-cluster in us-west-2.

Utilities

  • Enable IAM Identity Center for a cluster:

    eksctl utils associate-iam-oidc-provider --cluster my-cluster --region us-west-2 --approve

    Associates an IAM OIDC provider with my-cluster in us-west-2 and automatically approves the necessary IAM role changes.

  • Get kubeconfig for a cluster:

    eksctl utils write-kubeconfig --cluster my-cluster --region us-west-2

    Updates your local kubeconfig file to point to my-cluster in us-west-2.

  • Enable control plane logging:

    eksctl utils update-cluster-logging --cluster my-cluster --region us-west-2 --enable-audit --enable-api

    Enables audit and API server logs for my-cluster in us-west-2.

  • Disable control plane logging:

    eksctl utils update-cluster-logging --cluster my-cluster --region us-west-2 --disable-audit --disable-api

    Disables audit and API server logs for my-cluster in us-west-2.

  • List all IAM roles created by eksctl:

    eksctl get iamserviceaccount --cluster my-cluster --region us-west-2

    Lists IAM service accounts managed by eksctl for my-cluster.

Configuration File Examples

Basic Cluster:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: my-basic-cluster
  region: us-east-1
  version: "1.27"

nodeGroups:
  - name: general-workers
    instanceType: t3.medium
    desiredCapacity: 3

Cluster with Private Networking and Fargate:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: my-private-fargate-cluster
  region: eu-west-2
  version: "1.28"

vpc:
  subnets:
    private:
      eu-west-2a:
        id: subnet-0123456789abcdef0
      eu-west-2b:
        id: subnet-0fedcba9876543210
    public:
      eu-west-2a:
        id: subnet-0abcdef0123456789
      eu-west-2b:
        id: subnet-00123456789abcdef

fargateProfiles:
  - name: default-fargate
    selectors:
      - namespace: default
      - namespace: kube-system

Common Patterns

  • Creating a cluster with specific tags:

    eksctl create cluster \
  --name tagged-cluster \
  --region us-west-1 \
  --tags '{"Project":"Alpha","Environment":"Dev"}'

    Creates a cluster and applies the specified tags to AWS resources.

  • Creating a cluster and then immediately configuring kubectl:

    eksctl create cluster --name my-app-cluster --region ap-northeast-1 \
  && eksctl utils write-kubeconfig --cluster my-app-cluster --region ap-northeast-1

    Creates the cluster and then automatically sets up your kubeconfig to use it.

  • Scaling a node group and then verifying:

    eksctl scale nodegroup --cluster my-cluster --region us-east-1 --name standard --nodes 10 \
  && echo "Scaling complete. Verifying..." \
  && eksctl get nodegroup --cluster my-cluster --region us-east-1 --name standard -o json | grep -i desiredcapacity

    Scales a node group and then uses grep to quickly check if the desired capacity has been updated.

  • Upgrading a cluster and all its node groups:

    eksctl upgrade cluster --name my-cluster --region us-west-2 --version 1.28 --approve \
  && eksctl upgrade nodegroup --cluster my-cluster --region us-west-2 --name standard-workers --kubernetes-version 1.28 --approve

    Upgrades the EKS control plane and then upgrades a specific node group to the new Kubernetes version. Note: Node group upgrades might involve replacing nodes.

  • Creating a cluster with custom IAM policies for node groups:

    # cluster.yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: custom-iam-cluster
  region: us-east-1

nodeGroups:
  - name: custom-policy-nodes
    instanceType: t3.medium
    desiredCapacity: 2
    iam:
      withAddonPolicies:
        autoScaler: true # Example: enables policies for cluster-autoscaler
        cloudWatch: true # Example: enables policies for CloudWatch agent
        # You can also attach custom policies directly:
        # attachPolicyARNs:
        #   - arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

    eksctl create cluster -f cluster.yaml

    Defines a node group with pre-defined IAM policies for common addons like cluster-autoscaler and cloudwatch.

  • Draining and deleting a node group before cluster deletion:

    eksctl drain nodegroup --cluster my-cluster --region us-west-2 --name old-workers --grace-period=30s --delete-emptydir-data --force \
  && eksctl delete nodegroup --cluster my-cluster --region us-west-2 --name old-workers

    Safely evicts pods from nodes in old-workers before deleting the node group.

Gotchas

  • Resource Naming Conflicts: eksctl often creates resources (like VPCs, subnets, security groups, IAM roles) based on the cluster name. If you delete a cluster and immediately try to create another with the same name in the same region, you might encounter errors due to lingering resources or naming conflicts. Wait a few minutes or manually clean up resources.
  • IAM Permissions: eksctl requires significant IAM permissions to create and manage EKS clusters, VPCs, EC2 instances, and IAM roles. Ensure the AWS credentials you’re using have these permissions.
  • VPC Creation: By default, eksctl create cluster will create a new VPC for your cluster if you don’t specify existing ones. If you want to use an existing VPC, you must provide the subnet IDs using --vpc-public-subnets and --vpc-private-subnets.
  • delete cluster Behavior: eksctl delete cluster is destructive. It attempts to delete the EKS control plane, all associated node groups, and the VPC and other AWS resources it created. Be very sure before running this command.
  • Node Group Instance Type Updates: You cannot directly change the instance type of an existing node group. You must create a new node group with the desired instance type and migrate your workloads, or use eksctl replace nodegroup.
  • --approve Flag: Many eksctl commands that make significant changes (like upgrades or deletions) require the --approve flag to proceed. This is a safety mechanism to prevent accidental actions.
  • Addon Versions: When creating or updating addons, ensure you use valid and compatible versions. Check the EKS documentation for supported addon versions for your Kubernetes version.
  • Kubeconfig Merging: eksctl utils write-kubeconfig merges the new cluster’s configuration into your existing ~/.kube/config file. If you have many clusters, this file can become large. You might want to manage it more carefully or use tools like kubectx and kubens.
  • Control Plane Logging: Enabling control plane logging incurs costs. Ensure you understand the pricing and only enable logs you actually need.