Getting started with Amazon EKS – Amazon Web Services Management Console and Amazon CLI - 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.

Getting started with Amazon EKS – Amazon Web Services Management Console and Amazon CLI

This guide helps you to create all of the required resources to get started with Amazon Elastic Kubernetes Service (Amazon EKS) using the Amazon Web Services Management Console and the Amazon CLI. In this guide, you manually create each resource. 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 give you complete visibility into how each resource is created and how the resources interact with each other. If you'd rather have most of the resources created for you automatically, use the eksctl CLI to create your cluster and nodes. For more information, see Getting started with Amazon EKS – eksctl.

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.

  • Amazon CLI – A command line tool for working with Amazon services, including Amazon EKS. This guide requires that you use version 2.4.9 or later or 1.22.30 or later. For more information, see Installing, updating, and uninstalling the Amazon CLI in the Amazon Command Line Interface User Guide. After installing the Amazon CLI, we recommend that you also configure it. For more information, see Quick configuration with aws configure in the Amazon Command Line Interface User Guide.

  • kubectl – A command line tool for working with Kubernetes clusters. This guide requires that you use version 1.21 or later. For more information, see Installing kubectl.

  • Required IAM permissions – The IAM security principal that you're using must have permissions to work with Amazon EKS IAM roles and service linked roles, Amazon CloudFormation, and a VPC and related resources. For more information, see Actions, resources, and condition keys for Amazon Elastic Kubernetes Service and Using service-linked roles in the IAM User Guide. You must complete all steps in this guide as the same user.

Step 1: Create your Amazon EKS cluster

Important

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

To create your cluster

  1. Create an Amazon VPC with public and private subnets that meets Amazon EKS requirements. Replace region-code with any Region that is supported by Amazon EKS. For a list of Regions, see Amazon EKS endpoints and quotas in the Amazon General Reference guide. You can replace my-eks-vpc-stack with any name you choose.

    aws cloudformation create-stack \ --region region-code \ --stack-name my-eks-vpc-stack \ --template-url https://amazon-eks.s3.cn-north-1.amazonaws.com.cn/cloudformation/2020-10-29/amazon-eks-vpc-private-subnets.yaml
    Tip

    For a list of all the resources the previous command creates, open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation. Choose the my-eks-vpc-stack stack and then choose the Resources tab.

  2. Create a cluster IAM role and attach the required Amazon EKS IAM managed policy to it. Kubernetes clusters managed by Amazon EKS make calls to other Amazon services on your behalf to manage the resources that you use with the service.

    1. Copy the following contents to a file named cluster-role-trust-policy.json.

      { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "eks.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
    2. Create the role.

      aws iam create-role \ --role-name myAmazonEKSClusterRole \ --assume-role-policy-document file://"cluster-role-trust-policy.json"
    3. Attach the required Amazon EKS managed IAM policy to the role.

      aws iam attach-role-policy \ --policy-arn arn:aws-cn:iam::aws:policy/AmazonEKSClusterPolicy \ --role-name myAmazonEKSClusterRole
  3. Open the Amazon EKS console at https://console.amazonaws.cn/eks/home#/clusters.

    Make sure that the Region shown in the top right of your console is the Region that you want to create your cluster in. If it's not, choose the drop-down next to the Region name and choose the Region that you want to use.

  4. Choose Add cluster and then choose Create. If you don't see this option, then choose Clusters in the left panel first.

  5. On the Configure cluster page, do the following:

    1. Enter a Name for your cluster, such as my-cluster.

    2. For Cluster Service Role, choose myAmazonEKSClusterRole.

    3. Leave the remaining settings at their default values and choose Next.

  6. On the Specify networking page, do the following:

    1. Choose the ID of the VPC that you created in a previous step from the VPC drop down list. It is something like vpc-00x0000x000x0x000 | my-eks-vpc-stack-VPC.

    2. Leave the remaining settings at their default values and choose Next.

  7. On the Configure logging page, choose Next.

  8. On the Review and create page, choose Create.

    To the right of the cluster's name, the cluster status is Creating for several minutes until the cluster provisioning process completes. Don't continue to the next step until the status is Active.

    Note

    You might receive an error that one of the Availability Zones in your request doesn't have sufficient capacity to create an Amazon EKS cluster. If this happens, the error output contains the Availability Zones that can support a new cluster. Retry creating your cluster with at least two subnets that are located in the supported Availability Zones for your account. For more information, see Insufficient capacity.

Step 2: Configure your computer to communicate with your cluster

In this section, you create a kubeconfig file for your cluster. The settings in this file enable the kubectl CLI to communicate with your cluster.

To configure your computer to communicate with your cluster

  1. Create or update a kubeconfig file for your cluster. Replace region-code with the Region that you created your cluster in and my-cluster with the name of your cluster.

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

    By default, the config file is created in ~/.kube or the new cluster's configuration is added to an existing config file in ~/.kube.

  2. Test your configuration.

    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

Step 3: Create nodes

Important

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

Managed nodes – Linux

Create a managed node group, specifying the subnets and node IAM role that you created in previous steps.

To create your Amazon EC2 Linux managed node group

  1. Create a node IAM role and attach the required Amazon EKS IAM managed policy to it. The Amazon EKS node kubelet daemon makes calls to Amazon APIs on your behalf. Nodes receive permissions for these API calls through an IAM instance profile and associated policies.

    1. Copy the following contents to a file named node-role-trust-policy.json.

      { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
    2. Create the node IAM role.

      aws iam create-role \ --role-name myAmazonEKSNodeRole \ --assume-role-policy-document file://"node-role-trust-policy.json"
    3. Attach the required managed IAM policies to the role.

      aws iam attach-role-policy \ --policy-arn arn:aws-cn:iam::aws:policy/AmazonEKSWorkerNodePolicy \ --role-name myAmazonEKSNodeRole aws iam attach-role-policy \ --policy-arn arn:aws-cn:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly \ --role-name myAmazonEKSNodeRole aws iam attach-role-policy \ --policy-arn arn:aws-cn:iam::aws:policy/AmazonEKS_CNI_Policy \ --role-name myAmazonEKSNodeRole
  2. Open the Amazon EKS console at https://console.amazonaws.cn/eks/home#/clusters.

  3. Choose the name of the cluster that you created in Step 1: Create your Amazon EKS cluster, such as my-cluster.

  4. On the my-cluster page, do the following:

    1. Choose the Configuration tab.

    2. Choose the Compute tab.

    3. Choose Add Node Group.

  5. On the Configure Node Group page, do the following:

    1. For Name, enter a unique name for your managed node group, such as my-nodegroup.

    2. For Node IAM role name, choose myAmazonEKSNodeRole role that you created in a previous step. We recommend that each node group use its own unique IAM role.

    3. Choose Next.

  6. On the Set compute and scaling configuration page, accept the default values and choose Next.

  7. On the Specify networking page, accept the default values and choose Next.

  8. On the Review and create page, review your managed node group configuration and choose Create.

  9. After several minutes, the Status in the Node Group configuration section will change from Creating to Active. Don't continue to the next step until the status is Active.

Step 4: View resources

You can view your nodes and Kubernetes workloads.

To view your nodes and workloads

  1. In the left panel, choose Clusters, and then in the list of Clusters, choose the name of the cluster that you created, such as my-cluster.

  2. On the my-cluster page, do the following:

    1. On the Overview tab, you see the list of Nodes that were deployed for the cluster. You can choose the name of a node to see more information about it. For more information about what you see here, see View nodes.

    2. On the Workloads tab of the cluster, you see a list of the workloads that are deployed by default to an Amazon EKS cluster. You can choose the name of a workload to see more information about it. For more information about what you see here, see View workloads.

Step 5: Delete resources

After you've finished with the cluster and nodes that you created for this tutorial, you should delete the resources that you created. If you want to do more with this cluster before you delete the resources, see Next steps.

To delete the resources that you created in this guide

  1. Delete any node groups that you created.

    1. Open the Amazon EKS console at https://console.amazonaws.cn/eks/home#/clusters.

    2. In the left navigation, choose Clusters. In the list of clusters, choose my-cluster.

    3. Choose the Configuration tab, and then choose the Compute tab.

    4. If you created a node group, choose the my-nodegroup node group and then choose Delete. Enter my-nodegroup, and then choose Delete.

    5. Don't continue until the node group is deleted.

  2. Delete the cluster.

    1. In the left navigation, choose Clusters. In the list of clusters, choose my-cluster.

    2. Choose Delete cluster.

    3. Enter my-cluster and then choose Delete. Don't continue until the cluster is deleted.

  3. Delete the VPC Amazon CloudFormation stack that you created.

    1. Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

    2. Choose the my-eks-vpc-stack stack, and then choose Delete.

    3. In the Delete my-eks-vpc-stack confirmation dialog box, choose Delete stack.

  4. Delete the IAM roles that you created.

    1. Open the IAM console at https://console.amazonaws.cn/iam/.

    2. In the left navigation panel, choose Roles.

    3. Select each role you created from the list (myAmazonEKSClusterRole, as well as myAmazonEKSNodeRole). Choose Delete, enter the requested confirmation text, then choose Delete.

Next steps

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