Getting started with Amazon EKS – eksctl - 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 (PDF).

Getting started with Amazon EKS – eksctl

This guide helps you to create all of the required resources to get started with Amazon Elastic Kubernetes Service (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 Amazon Web Services Management Console. If you'd rather manually create most of the resources to better understand how they interact with each other, then use the Amazon Web Services Management Console to create your cluster and compute. For more information, see Getting started with Amazon EKS – Amazon Web Services Management Console and Amazon CLI.

Prerequisites

Before starting this tutorial, you must install and configure the following tools and resources that you need to create and manage an Amazon EKS cluster.

  • kubectl – A command line tool for working with Kubernetes clusters. For more information, see Installing or updating kubectl.

  • eksctl – A command line tool for working with EKS clusters that automates many individual tasks. For more information, see Installation in the eksctl documentation.

  • Required IAM permissions – The IAM security principal that you're using must have permissions to work with Amazon EKS IAM roles, service linked roles, Amazon 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

Step 1: Create your Amazon EKS cluster and nodes

Important

To get started as simply and quickly as possible, this topic includes steps to create a cluster and nodes with default settings. Before creating a cluster and nodes for production use, we recommend that you familiarize yourself with all settings and deploy a cluster and nodes with the settings that meet your requirements. For more information, see Creating an Amazon EKS cluster and Amazon EKS nodes. Some settings can only be enabled when creating your cluster and nodes.

You can create a cluster with one of the following node types. To learn more about each type, see Amazon EKS nodes. After your cluster is deployed, you can add other node types.

  • Fargate – Linux – Select this type of node if you want to run Linux applications on Amazon Fargate. Fargate is a serverless compute engine that lets you deploy Kubernetes Pods without managing Amazon EC2 instances.

  • Managed nodes – Linux – Select this type of node if you want to run Amazon Linux applications on Amazon EC2 instances. Though not covered in this guide, you can also add Windows self-managed and Bottlerocket nodes to your cluster.

Create your Amazon EKS cluster with the following command. You can replace my-cluster with your own value. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic character and can't be longer than 100 characters. Replace region-code with any Amazon Web Services Region that is supported by Amazon EKS. For a list of Amazon Web Services Regions, see Amazon EKS endpoints and quotas in the Amazon General Reference guide.

Fargate – Linux
eksctl create cluster --name my-cluster --region region-code --fargate
Managed nodes – Linux
eksctl create cluster --name my-cluster --region region-code

Cluster creation takes several minutes. During creation you'll see several lines of output. The last line of output is similar to the following example line.

[...]
[✓]  EKS cluster "my-cluster" in "region-code" region is ready

eksctl created a kubectl config file in ~/.kube or added the new cluster's configuration within an existing config file in ~/.kube on your computer.

After cluster creation is complete, view the Amazon CloudFormation stack named eksctl-my-cluster-cluster in the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation to see all of the resources that were created.

Step 2: View Kubernetes resources

  1. View your cluster nodes.

    kubectl get nodes -o wide

    An example output is as follows.

    Fargate – Linux
    NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME fargate-ip-192-0-2-0.region-code.compute.internal Ready <none> 8m3s v1.2.3-eks-1234567 192.0.2.0 <none> Amazon Linux 2 1.23.456-789.012.amzn2.x86_64 containerd://1.2.3 fargate-ip-192-0-2-1.region-code.compute.internal Ready <none> 7m30s v1.2.3-eks-1234567 192-0-2-1 <none> Amazon Linux 2 1.23.456-789.012.amzn2.x86_64 containerd://1.2.3
    Managed nodes – Linux
    NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME ip-192-0-2-0.region-code.compute.internal Ready <none> 6m7s v1.2.3-eks-1234567 192.0.2.0 192.0.2.2 Amazon Linux 2 1.23.456-789.012.amzn2.x86_64 containerd://1.2.3 ip-192-0-2-1.region-code.compute.internal Ready <none> 6m4s v1.2.3-eks-1234567 192.0.2.1 192.0.2.3 Amazon Linux 2 1.23.456-789.012.amzn2.x86_64 containerd://1.2.3

    For more information about what you see in the output, see View Kubernetes resources.

  2. View the workloads running on your cluster.

    kubectl get pods -A -o wide

    An example output is as follows.

    Fargate – Linux
    NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES kube-system coredns-1234567890-abcde 1/1 Running 0 18m 192.0.2.0 fargate-ip-192-0-2-0.region-code.compute.internal <none> <none> kube-system coredns-1234567890-12345 1/1 Running 0 18m 192.0.2.1 fargate-ip-192-0-2-1.region-code.compute.internal <none> <none>
    Managed nodes – Linux
    NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES kube-system aws-node-12345 1/1 Running 0 7m43s 192.0.2.1 ip-192-0-2-1.region-code.compute.internal <none> <none> kube-system aws-node-67890 1/1 Running 0 7m46s 192.0.2.0 ip-192-0-2-0.region-code.compute.internal <none> <none> kube-system coredns-1234567890-abcde 1/1 Running 0 14m 192.0.2.3 ip-192-0-2-3.region-code.compute.internal <none> <none> kube-system coredns-1234567890-12345 1/1 Running 0 14m 192.0.2.4 ip-192-0-2-4.region-code.compute.internal <none> <none> kube-system kube-proxy-12345 1/1 Running 0 7m46s 192.0.2.0 ip-192-0-2-0.region-code.compute.internal <none> <none> kube-system kube-proxy-67890 1/1 Running 0 7m43s 192.0.2.1 ip-192-0-2-1.region-code.compute.internal <none> <none>

    For more information about what you see in the output, see View Kubernetes resources.

Step 3: Delete your cluster and nodes

After you've finished with the cluster and nodes that you created for this tutorial, you should clean up by deleting the cluster and nodes with the following command. If you want to do more with this cluster before you clean up, see Next steps.

eksctl delete cluster --name my-cluster --region region-code

Next steps

The following documentation topics help you to extend the functionality of your cluster.