Help improve this page
Want to contribute to this user guide? Scroll to the bottom of this page and select Edit this page on GitHub. Your contributions will help make our user guide better for everyone.
Get 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 Get 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. 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. For more information, see Set up kubectl and eksctl. -
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 Kubernetes Service 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
-
We recommend that you complete the steps in this topic in a Bash shell. If you aren't using a Bash shell, some script commands such as line continuation characters and the way variables are set and used require adjustment for your shell. Additionally, the quoting and escaping rules for your shell might be different. For more information, see Using quotation marks with strings in the Amazon CLI in the Amazon Command Line Interface User Guide.
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 Create an Amazon EKS cluster. Some settings can only be enabled when creating your cluster.
To create your cluster
-
Create an Amazon VPC with public and private subnets that meets Amazon EKS requirements. Replace
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. You can replaceregion-code
with any name you choose.my-eks-vpc-stack
aws cloudformation create-stack \ --region
region-code
\ --stack-namemy-eks-vpc-stack
\ --template-url https://s3.cn-north-1.amazonaws.com.cn/amazon-eks/cloudformation/2020-10-29/amazon-eks-vpc-private-subnets.yamlTip
For a list of all the resources the previous command creates, open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation
. Choose the
stack and then choose the Resources tab.my-eks-vpc-stack
-
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.
-
Copy the following contents to a file named
.eks-cluster-role-trust-policy.json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "eks.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
-
Create the role.
aws iam create-role \ --role-name
myAmazonEKSClusterRole
\ --assume-role-policy-document file://"eks-cluster-role-trust-policy.json
" -
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
-
Open the Amazon EKS console at https://console.amazonaws.cn/eks/home#/clusters
. Make sure that the Amazon Web Services Region shown in the upper right of your console is the Amazon Web Services Region that you want to create your cluster in. If it's not, choose the dropdown next to the Amazon Web Services Region name and choose the Amazon Web Services Region that you want to use.
-
Choose Add cluster, and then choose Create. If you don't see this option, then choose Clusters in the left navigation pane first.
-
On the Configure cluster page, do the following:
-
Enter a Name for your cluster, such as
my-cluster
. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphanumeric character and can't be longer than 100 characters. The name must be unique within the Amazon Web Services Region and Amazon Web Services account that you're creating the cluster in. -
For Cluster Service Role, choose
myAmazonEKSClusterRole
. -
Leave the remaining settings at their default values and choose Next.
-
-
On the Specify networking page, do the following:
-
Choose the ID of the VPC that you created in a previous step from the VPC dropdown list. It is something like
vpc-00x0000x000x0x000
|my-eks-vpc-stack-VPC
. -
Leave the remaining settings at their default values and choose Next.
-
-
On the Configure observability page, choose Next.
-
On the Select add-ons page, choose Next.
For more information on add-ons, see Amazon EKS add-ons.
-
On the Configure selected add-ons settings page, choose Next.
-
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
-
Create or update a
kubeconfig
file for your cluster. Replace
with the Amazon Web Services Region that you created your cluster in. Replaceregion-code
with the name of your cluster.my-cluster
aws eks update-kubeconfig --region
region-code
--namemy-cluster
By default, the
config
file is created in~/.kube
or the new cluster's configuration is added to an existingconfig
file in~/.kube
. -
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 topic.
An example output is as follows.
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 Manage compute resources by using nodes. Some settings can only be enabled when creating your nodes.
You can create a cluster with one of the following node types. To learn more about each type, see Manage compute resources by using nodes. After your cluster is deployed, you can add other node types.
-
Fargate – Linux – Choose 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 – Choose 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.
Step 4: View resources
You can view your nodes and Kubernetes workloads.
To view your nodes and workloads
-
In the left navigation pane, choose Clusters. In the list of Clusters, choose the name of the cluster that you created, such as
my-cluster
. -
On the
my-cluster
page, choose the following:-
Compute 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.
-
Resources tab – You see all of the Kubernetes resources that are deployed by default to an Amazon EKS cluster. Select any resource type in the console to learn more about it.
-
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
-
Delete any node groups or Fargate profiles that you created.
-
Open the Amazon EKS console at https://console.amazonaws.cn/eks/home#/clusters
. -
In the left navigation pane, choose Clusters. In the list of clusters, choose
my-cluster
. -
Choose the Compute tab.
-
If you created a node group, choose the
node group and then choose Delete. Entermy-nodegroup
, and then choose Delete.my-nodegroup
-
For each Fargate profile that you created, choose it and then choose Delete. Enter the name of the profile, and then choose Delete.
Note
When deleting a second Fargate profile, you may need to wait for the first one to finish deleting.
-
Don't continue until the node group or Fargate profiles are deleted.
-
-
Delete the cluster.
-
In the left navigation pane, choose Clusters. In the list of clusters, choose
my-cluster
. -
Choose Delete cluster.
-
Enter
and then choose Delete. Don't continue until the cluster is deleted.my-cluster
-
-
Delete the VPC Amazon CloudFormation stack that you created.
-
Open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation
. -
Choose the
stack, and then choose Delete.my-eks-vpc-stack
-
In the Delete
my-eks-vpc-stack
confirmation dialog box, choose Delete stack.
-
-
Delete the IAM roles that you created.
-
Open the IAM console at https://console.amazonaws.cn/iam/
. -
In the left navigation pane, choose Roles.
-
Select each role you created from the list (
myAmazonEKSClusterRole
, as well as AmazonEKSFargatePodExecutionRole ormyAmazonEKSNodeRole
). 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.
The IAM principal that created the cluster is the only principal that can make calls to the Kubernetes API server with
kubectl
or the Amazon Web Services Management Console. If you want other IAM principals to have access to your cluster, then you need to add them. For more information, see Grant IAM users and roles access to Kubernetes APIs and Required permissions.Deploy a sample application to your cluster.
Before deploying a cluster for production use, we recommend familiarizing yourself with all of the settings for clusters and nodes. Some settings (such as enabling SSH access to Amazon EC2 nodes) must be made when the cluster is created.
To increase security for your cluster, configure the Amazon VPC Container Networking Interface plugin to use IAM roles for service accounts.