Getting started with Amazon EKS – eksctl - Amazon EKS

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 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 Amazon EKS – AWS Management Console and AWS 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. This guide requires that you use version 1.18 or later. For more information, see Installing kubectl.

Step 1: Create your Amazon EKS cluster and nodes

Create your 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.

Select 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 AWS Fargate.

  • 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. A cluster must contain at least one Linux node, even if all your workloads are Windows.

[ Fargate – Linux ]

  1. Create your Amazon EKS cluster with an AWS Fargate profile and Pod execution role with the following command. Replace my-cluster with your own value and us-west-2 with any Amazon EKS Fargate supported Region. If you're deploying to the Africa (Cape Town), Asia Pacific (Hong Kong), Europe (Milan), or Middle East (Bahrain) Regions, the endpoint must be enabled for your account. For more information, see Activating and deactivating AWS STS in an AWS Region. The endpoint is enabled by default for all other Regions.

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

    The previous command creates a cluster and Fargate profile using primarily default settings. To see all resources created, view the stack named eksctl-<my-cluster>-cluster in the AWS CloudFormation console. For a list of all settings and options, enter eksctl create cluster -h. For documentation of all settings and options, see Creating and Managing Clusters in the eksctl documentation.

    Output

    You'll see several lines of output as the cluster and Fargate profile are created. Creation takes several minutes. 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.

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

  2. Test your configuration.

    kubectl get svc

    Output

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

[ Managed nodes – Linux ]

  • Create your cluster and Linux managed node group. Replace my-cluster with your own value and us-west-2 with any Amazon EKS supported Region. If you're deploying to the Africa (Cape Town), Asia Pacific (Hong Kong), Europe (Milan), or Middle East (Bahrain) Regions, the endpoint must be enabled for your account. For more information, see Activating and deactivating AWS STS in an AWS Region. The endpoint is enabled by default for all other Regions.

    Replace <your-key> (including <>) with the name of an existing key pair. If you don't have a key pair, you can create one with the following command. If necessary, change us-west-2 to the Region that you create your cluster in. Be sure to save the return output in a file on your local computer. For more information, see Creating or importing a key pair in the Amazon EC2 User Guide for Linux Instances.

    Though the key isn't required in this guide, you can only specify a key to use when you create the node group. Specifying the key allows you to SSH to nodes once they're created. To run the command, you need to have the AWS CLI version 2.1.16 or later or 1.18.210 or later. For more information, see Installing, updating, and uninstalling the AWS CLI in the AWS Command Line Interface User Guide.

    aws ec2 create-key-pair --region us-west-2 --key-name myKeyPair

    Create your cluster and nodes with the following command.

    eksctl create cluster \ --name my-cluster \ --region us-west-2 \ --with-oidc \ --ssh-access \ --ssh-public-key <your-key> \ --managed

    The previous command creates a cluster with nodes using primarily default Amazon EKS settings. To see all resources created, view the stack named eksctl-<my-cluster>-cluster in the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation. For a list of all settings and options, enter eksctl create cluster -h. For documentation of all settings and options, see Creating and Managing Clusters in the eksctl documentation.

    Output

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

    ... [✓] EKS cluster "my-cluster" in "us-west-2" 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.

Step 2: View resources

  1. View your cluster nodes.

    kubectl get nodes -o wide

    Amazon EC2 node output

    NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME ip-192-168-12-49.us-west-2.compute.internal Ready <none> 6m7s v1.18.9-eks-d1db3c 192.168.12.49 52.35.116.65 Amazon Linux 2 4.14.209-160.335.amzn2.x86_64 docker://19.3.6 ip-192-168-72-129.us-west-2.compute.internal Ready <none> 6m4s v1.18.9-eks-d1db3c 192.168.72.129 44.242.140.21 Amazon Linux 2 4.14.209-160.335.amzn2.x86_64 docker://19.3.6

    Fargate node output

    NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME fargate-ip-192-168-141-147.us-west-2.compute.internal Ready <none> 8m3s v1.18.8-eks-7c9bda 192.168.141.147 <none> Amazon Linux 2 4.14.209-160.335.amzn2.x86_64 containerd://1.3.2 fargate-ip-192-168-164-53.us-west-2.compute.internal Ready <none> 7m30s v1.18.8-eks-7c9bda 192.168.164.53 <none> Amazon Linux 2 4.14.209-160.335.amzn2.x86_64 containerd://1.3.2

    For more information about what you see here, see View nodes.

  2. View the workloads running on your cluster.

    kubectl get pods --all-namespaces -o wide

    Amazon EC2 output

    NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES kube-system aws-node-6ctpm 1/1 Running 0 7m43s 192.168.72.129 ip-192-168-72-129.us-west-2.compute.internal <none> <none> kube-system aws-node-cbntg 1/1 Running 0 7m46s 192.168.12.49 ip-192-168-12-49.us-west-2.compute.internal <none> <none> kube-system coredns-559b5db75d-26t47 1/1 Running 0 14m 192.168.78.81 ip-192-168-72-129.us-west-2.compute.internal <none> <none> kube-system coredns-559b5db75d-9rvnk 1/1 Running 0 14m 192.168.29.248 ip-192-168-12-49.us-west-2.compute.internal <none> <none> kube-system kube-proxy-l8pbd 1/1 Running 0 7m46s 192.168.12.49 ip-192-168-12-49.us-west-2.compute.internal <none> <none> kube-system kube-proxy-zh85h 1/1 Running 0 7m43s 192.168.72.129 ip-192-168-72-129.us-west-2.compute.internal <none> <none>

    Fargate output

    NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES kube-system coredns-69dfb8f894-9z95l 1/1 Running 0 18m 192.168.164.53 fargate-ip-192-168-164-53.us-west-2.compute.internal <none> <none> kube-system coredns-69dfb8f894-c8v66 1/1 Running 0 18m 192.168.141.147 fargate-ip-192-168-141-147.us-west-2.compute.internal <none> <none>

    For more information about what you see here, see View workloads.

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. If you want to do more with this cluster before you clean up, see Next steps.

Delete your cluster and nodes.

eksctl delete cluster --name my-cluster

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.

  • The IAM entity (user or role) that created the cluster is added to the Kubernetes RBAC authorization table as the administrator (with system:masters permissions). Initially, only that IAM user can make calls to the Kubernetes API server using kubectl. If you want other users to have access to your cluster, then you must add them to the aws-auth ConfigMap. For more information, see Managing users or IAM roles for your cluster.

  • Restrict access to IMDS – If you plan to assign IAM roles to all of your Kubernetes service accounts so that pods only have the minimum permissions that they need, and no pods in the cluster require access to the Amazon EC2 instance metadata service (IMDS) for other reasons, such as retrieving the current Region, then we recommend blocking pod access to IMDS. For more information, see IAM roles for service accounts and Restricting access to the IMDS and Amazon EC2 instance profile credentials.

  • Cluster Autoscaler – Configure the Kubernetes Cluster Autoscaler to automatically adjust the number of nodes in your node groups.

  • Deploy a sample Linux workload – Deploy a sample Linux application to test your cluster and Linux nodes.

  • Cluster management – Learn how to use important tools for managing your cluster.