Create an Amazon EKS cluster
Note
This topic covers creating EKS clusters without EKS Auto Mode.
For detailed instructions on creating an EKS Auto Mode cluster, see Create an Amazon EKS Auto Mode cluster.
To get started with EKS Auto Mode, see Get started with Amazon EKS – EKS Auto Mode.
This topic provides an overview of the available options and describes what to consider when you create an Amazon EKS cluster. If you need to create a cluster with your on-premises infrastructure as the compute for nodes, see Create an EKS cluster with hybrid nodes. If this is your first time creating an Amazon EKS cluster, we recommend that you follow one of our guides in Get started with Amazon EKS. These guides help you to create a simple, default cluster without expanding into all of the available options.
Prerequisites
-
An existing VPC and subnets that meet Amazon EKS requirements. Before you deploy a cluster for production use, we recommend that you have a thorough understanding of the VPC and subnet requirements. If you don’t have a VPC and subnets, you can create them using an Amazon EKS provided Amazon CloudFormation template.
-
The
kubectl
command line tool is installed on your device or Amazon CloudShell. The version can be the same as or up to one minor version earlier or later than the Kubernetes version of your cluster. For example, if your cluster version is1.29
, you can usekubectl
version1.28
,1.29
, or1.30
with it. To install or upgradekubectl
, see Set up kubectl and eksctl. -
Version
2.12.3
or later or version1.27.160
or later of the Amazon Command Line Interface (Amazon CLI) installed and configured on your device or Amazon CloudShell. To check your current version, useaws --version | cut -d / -f2 | cut -d ' ' -f1
. Package managers suchyum
,apt-get
, or Homebrew for macOS are often several versions behind the latest version of the Amazon CLI. To install the latest version, see Installing and Quick configuration with aws configure in the Amazon Command Line Interface User Guide. The Amazon CLI version that is installed in Amazon CloudShell might also be several versions behind the latest version. To update it, see Installing Amazon CLI to your home directory in the Amazon CloudShell User Guide. -
An IAM principal with permissions to
create
anddescribe
an Amazon EKS cluster. For more information, see Create a local Kubernetes cluster on an Outpost and List or describe all clusters.
Step 1: Create cluster IAM role
-
If you already have a cluster IAM role, or you’re going to create your cluster with
eksctl
, then you can skip this step. By default,eksctl
creates a role for you. -
Run the following command to create an IAM trust policy JSON file.
cat >eks-cluster-role-trust-policy.json <<EOF { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "eks.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } EOF
-
Create the Amazon EKS cluster IAM role. If necessary, preface
eks-cluster-role-trust-policy.json
with the path on your computer that you wrote the file to in the previous step. The command associates the trust policy that you created in the previous step to the role. To create an IAM role, the IAM principal that is creating the role must be assigned theiam:CreateRole
action (permission).aws iam create-role --role-name myAmazonEKSClusterRole --assume-role-policy-document file://"eks-cluster-role-trust-policy.json"
-
You can assign either the Amazon EKS managed policy or create your own custom policy. For the minimum permissions that you must use in your custom policy, see Amazon EKS cluster IAM role.
Attach the Amazon EKS managed policy named AmazonEKSClusterPolicy to the role. To attach an IAM policy to an IAM principal, the principal that is attaching the policy must be assigned one of the following IAM actions (permissions):
iam:AttachUserPolicy
oriam:AttachRolePolicy
.aws iam attach-role-policy --policy-arn arn:aws-cn:iam::aws:policy/AmazonEKSClusterPolicy --role-name myAmazonEKSClusterRole
Step 2: Create cluster
You can create a cluster by using:
Create cluster - eksctl
-
You need version
0.197.0
or later of theeksctl
command line tool installed on your device or Amazon CloudShell. To install or updateeksctl
, see Installationin the eksctl
documentation. -
Create an Amazon EKS
IPv4
cluster with the Amazon EKS default Kubernetes version in your default Amazon Region. Before running command, make the following replacements: -
Replace
region-code
with the Amazon Region that you want to create your cluster in. -
Replace
my-cluster
with a name for your 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 Region and Amazon account that you’re creating the cluster in. -
Replace
1.29
with any Amazon EKS supported version. -
Change the values for
vpc-private-subnets
to meet your requirements. You can also add additional IDs. You must specify at least two subnet IDs. If you’d rather specify public subnets, you can change--vpc-private-subnets
to--vpc-public-subnets
. Public subnets have an associated route table with a route to an internet gateway, but private subnets don’t have an associated route table. We recommend using private subnets whenever possible.The subnets that you choose must meet the Amazon EKS subnet requirements. Before selecting subnets, we recommend that you’re familiar with all of the Amazon EKS VPC and subnet requirements and considerations.
-
Run the following command:
eksctl create cluster --name my-cluster --region region-code --version 1.29 --vpc-private-subnets subnet-ExampleID1,subnet-ExampleID2 --without-nodegroup
Cluster provisioning takes several minutes. While the cluster is being created, several lines of output appear. The last line of output is similar to the following example line.
[✓] EKS cluster "my-cluster" in "region-code" region is ready
-
Continue with Step 3: Update kubeconfig
Optional Settings
To see the most options that you can specify when creating a cluster with eksctl
, use the eksctl create cluster --help
command. To see all the available options, you can use a config
file. For more information, see Using config fileseksctl
documentation. You can find config file examples
The following are optional settings that, if required, must be added to the previous command. You can only enable these options when you create the cluster, not after. If you need to specify these options, you must create the cluster with an eksctl config file
-
If you want to specify one or more security groups that Amazon EKS assigns to the network interfaces that it creates, specify the securityGroup
option. Whether you choose any security groups or not, Amazon EKS creates a security group that enables communication between your cluster and your VPC. Amazon EKS associates this security group, and any that you choose, to the network interfaces that it creates. For more information about the cluster security group that Amazon EKS creates, see View Amazon EKS security group requirements for clusters. You can modify the rules in the cluster security group that Amazon EKS creates.
-
If you want to specify which
IPv4
Classless Inter-domain Routing (CIDR) block Kubernetes assigns service IP addresses from, specify the serviceIPv4CIDRoption. Specifying your own range can help prevent conflicts between Kubernetes services and other networks peered or connected to your VPC. Enter a range in CIDR notation. For example:
10.2.0.0/16
.The CIDR block must meet the following requirements:
-
Be within one of the following ranges:
10.0.0.0/8
,172.16.0.0/12
, or192.168.0.0/16
. -
Have a minimum size of
/24
and a maximum size of/12
. -
Not overlap with the range of the VPC for your Amazon EKS resources.
You can only specify this option when using the
IPv4
address family and only at cluster creation. If you don’t specify this, then Kubernetes assigns service IP addresses from either the10.100.0.0/16
or172.20.0.0/16
CIDR blocks.
-
-
If you’re creating cluster and want the cluster to assign
IPv6
addresses to Pods and services instead ofIPv4
addresses, specify the ipFamilyoption. Kubernetes assigns
IPv4
addresses to Pods and services, by default. Before deciding to use theIPv6
family, make sure that you’re familiar with all of the considerations and requirements in the VPC requirements and considerations, Subnet requirements and considerations, View Amazon EKS security group requirements for clusters, and Learn about IPv6 addresses to clusters, pods, and services topics. If you choose theIPv6
family, you can’t specify an address range for Kubernetes to assignIPv6
service addresses from like you can for theIPv4
family. Kubernetes assigns service addresses from the unique local address range (fc00::/7
).
Create cluster - Amazon console
-
Open the Amazon EKS console
. -
Choose Add cluster and then choose Create.
-
Under Configuration options select Custom configuration
-
For information about quickly creating a cluster wih EKS Auto Mode, see Create an EKS Auto Mode Cluster with the Amazon Management Console.
-
-
Under EKS Auto Mode, toggle Use EKS Auto Mode off.
-
For information about creating an EKS Auto Mode cluster with custom configuration, see Create an Amazon EKS Auto Mode cluster.
-
-
On the Configure cluster page, enter the following fields:
-
Name – A name for your cluster. The name can contain only alphanumeric characters (case-sensitive), hyphens, and underscores. It must start with an alphanumeric character and can’t be longer than 100 characters. The name must be unique within the Amazon Region and Amazon account that you’re creating the cluster in.
-
Cluster IAM role – Choose the Amazon EKS cluster IAM role that you created to allow the Kubernetes control plane to manage Amazon resources on your behalf.
-
Kubernetes version – The version of Kubernetes to use for your cluster. We recommend selecting the latest version, unless you need an earlier version.
-
Support type — The Kubernetes version policy you would like to set for your cluster. If you want your cluster to only run on a standard support version, you can choose Standard support. If you want your cluster to enter extended support at the end of standard support for a version, you can choose Extended support. If you select a Kubernetes version that is currently in extended support, you can not select standard support as an option.
-
Secrets encryption – (Optional) Choose to enable secrets encryption of Kubernetes secrets using a KMS key. You can also enable this after you create your cluster. Before you enable this capability, make sure that you’re familiar with the information in Encrypt Kubernetes secrets with Amazon KMS on existing clusters.
-
Tags – (Optional) Add any tags to your cluster. For more information, see Organize Amazon EKS resources with tags.
-
ARC Zonal shift - (Optional) You can use Route53 Application Recovery controller to mitigate impaired availability zones. For more information, see Learn about Amazon Application Recovery Controller’s (ARC) Zonal Shift in Amazon EKS.
-
-
In the Cluster access section of the configure cluster page, enter the following fields:
-
Bootstrap cluster administrator access — The cluster creator is automatically a Kubernetes administrator. If you want to disable this, select Disallow cluster administrator access.
-
Cluster authentication mode — Determine how you want to grant IAM users and roles access to Kubernetes APIs. For more information, see Set Cluster Authentication Mode.
When you’re done with this page, choose Next.
-
-
On the Specify networking page, select values for the following fields:
-
VPC – Choose an existing VPC that meets Amazon EKS VPC requirements to create your cluster in. Before choosing a VPC, we recommend that you’re familiar with all of the requirements and considerations in View Amazon EKS networking requirements for VPC and subnets. You can’t change which VPC you want to use after cluster creation. If no VPCs are listed, then you need to create one first. For more information, see Create an Amazon VPC for your Amazon EKS cluster.
-
Subnets – By default, all available subnets in the VPC specified in the previous field are preselected. You must select at least two.
The subnets that you choose must meet the Amazon EKS subnet requirements. Before selecting subnets, we recommend that you’re familiar with all of the Amazon EKS VPC and subnet requirements and considerations.
Security groups – (Optional) Specify one or more security groups that you want Amazon EKS to associate to the network interfaces that it creates.
Whether you choose any security groups or not, Amazon EKS creates a security group that enables communication between your cluster and your VPC. Amazon EKS associates this security group, and any that you choose, to the network interfaces that it creates. For more information about the cluster security group that Amazon EKS creates, see View Amazon EKS security group requirements for clusters. You can modify the rules in the cluster security group that Amazon EKS creates.
-
Choose cluster IP address family – You can choose either IPv4 and IPv6.
Kubernetes assigns
IPv4
addresses to Pods and services, by default. Before deciding to use theIPv6
family, make sure that you’re familiar with all of the considerations and requirements in the VPC requirements and considerations, Subnet requirements and considerations, View Amazon EKS security group requirements for clusters, and Learn about IPv6 addresses to clusters, pods, and services topics. If you choose theIPv6
family, you can’t specify an address range for Kubernetes to assignIPv6
service addresses from like you can for theIPv4
family. Kubernetes assigns service addresses from the unique local address range (fc00::/7
). -
(Optional) Choose Configure Kubernetes Service IP address range and specify a Service
IPv4
range.Specifying your own range can help prevent conflicts between Kubernetes services and other networks peered or connected to your VPC. Enter a range in CIDR notation. For example:
10.2.0.0/16
.The CIDR block must meet the following requirements:
-
Be within one of the following ranges:
10.0.0.0/8
,172.16.0.0/12
, or192.168.0.0/16
. -
Have a minimum size of
/24
and a maximum size of/12
. -
Not overlap with the range of the VPC for your Amazon EKS resources.
-
You can only specify this option when using the
IPv4
address family and only at cluster creation. If you don’t specify this, then Kubernetes assigns service IP addresses from either the10.100.0.0/16
or172.20.0.0/16
CIDR blocks.-
For Cluster endpoint access, select an option. After your cluster is created, you can change this option. Before selecting a non-default option, make sure to familiarize yourself with the options and their implications. For more information, see Control network access to cluster API server endpoint.
When you’re done with this page, choose Next.
-
-
(Optional) On the Configure observability page, choose which Metrics and Control plane logging options to turn on. By default, each log type is turned off.
-
For more information about the Prometheus metrics option, see Step 1: Turn on Prometheus metrics.
-
For more information about the Control plane logging options, see Send control plane logs to CloudWatch Logs.
When you’re done with this page, choose Next.
-
-
On the Select add-ons page, choose the add-ons that you want to add to your cluster. Certain add-ons are pre-selected. You can choose as many Amazon EKS add-ons and Amazon Marketplace add-ons as you require. If the Amazon Marketplace add-ons that you want to install isn’t listed, you can click the page numbering to view additional page results or search for available Amazon Marketplace add-ons by entering text in the search box. You can also filter by category, vendor, or pricing model and then choose the add-ons from the search results. When creating a cluster, you can view, select, and install any add-on that supports EKS Pod Identities as detailed in Learn how EKS Pod Identity grants pods access to Amazon services.
When you’re done with this page, choose Next.
Some add-ons, such as Amazon VPC CNI, CoreDNS, and kube-proxy, are installed by default. If you disable any of the default add-ons, this may affect your ability to run Kubernetes applications.
-
On the Configure selected add-ons settings page, select the version that you want to install. You can always update to a later version after cluster creation.
For add-ons that support EKS Pod Identities, you can use the console to automatically generate the role with the name, Amazon managed policy, and trust policy prepopulated specifically for the add-on. You can re-use existing roles or create new roles for supported add-ons. For the steps to use the console to create roles for add-ons that support EKS Pod Identities, see Create add-on (Amazon Console). If an add-on does not support EKS Pod Identity, a message displays with instructions to use the wizard to create the IAM roles for service accounts (IRSA) after the cluster is created.
You can update the configuration of each add-on after cluster creation. For more information about configuring add-ons, see Update an Amazon EKS add-on. When you’re done with this page, choose Next.
-
On the Review and create page, review the information that you entered or selected on the previous pages. If you need to make changes, choose Edit. When you’re satisfied, choose Create. The Status field shows CREATING while the cluster is provisioned.
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.
Cluster provisioning takes several minutes.
-
Continue with Step 3: Update kubeconfig
Create cluster - Amazon CLI
-
Create your cluster with the command that follows. Before running the command, make the following replacements:
You can only specify this option when using the
IPv4
address family and only at cluster creation. If you don’t specify this, then Kubernetes assigns service IP addresses from either the10.100.0.0/16
or172.20.0.0/16
CIDR blocks.-
Replace
region-code
with the Amazon Region that you want to create your cluster in. -
Replace
my-cluster
with a name for your cluster. The name can contain only alphanumeric characters (case-sensitive), hyphens, and underscores. It must start with an alphanumeric character and can’t be longer than 100 characters. The name must be unique within the Amazon Region and Amazon account that you’re creating the cluster in. -
Replace
1.30
with any Amazon EKS supported version. -
Replace
111122223333
with your account ID andmyAmazonEKSClusterRole
with the name of your cluster IAM role. -
Replace the values for
subnetIds
with your own. You can also add additional IDs. You must specify at least two subnet IDs.The subnets that you choose must meet the Amazon EKS subnet requirements. Before selecting subnets, we recommend that you’re familiar with all of the Amazon EKS VPC and subnet requirements and considerations.
-
If you don’t want to specify a security group ID, remove
,securityGroupIds=sg-<ExampleID1>
from the command. If you want to specify one or more security group IDs, replace the values forsecurityGroupIds
with your own. You can also add additional IDs.Whether you choose any security groups or not, Amazon EKS creates a security group that enables communication between your cluster and your VPC. Amazon EKS associates this security group, and any that you choose, to the network interfaces that it creates. For more information about the cluster security group that Amazon EKS creates, see View Amazon EKS security group requirements for clusters. You can modify the rules in the cluster security group that Amazon EKS creates.
aws eks create-cluster --region region-code --name my-cluster --kubernetes-version 1.30 \ --role-arn arn:aws-cn:iam::111122223333:role/myAmazonEKSClusterRole \ --resources-vpc-config subnetIds=subnet-ExampleID1,subnet-ExampleID2,securityGroupIds=sg-ExampleID1
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.
The following are optional settings that, if required, must be added to the previous command. You can only enable these options when you create the cluster, not after.
-
By default, EKS installs multiple networking add-ons during cluster creation. This includes the Amazon VPC CNI, CoreDNS, and kube-proxy.
If you’d like to disable the installation of these default networking add-ons, use the parameter below. This may be used for alternate CNIs, such as Cilium. Review the EKS API reference for more information.
aws eks create-cluster --bootstrapSelfManagedAddons false
-
If you want to specify which
IPv4
Classless Inter-domain Routing (CIDR) block Kubernetes assigns service IP addresses from, you must specify it by adding the--kubernetes-network-config serviceIpv4Cidr=<cidr-block>
to the following command.10.2.0.0/16
. The CIDR block must meet the following requirements:-
Be within one of the following ranges:
10.0.0.0/8
,172.16.0.0/12
, or192.168.0.0/16
. -
Have a minimum size of
/24
and a maximum size of/12
. -
Not overlap with the range of the VPC for your Amazon EKS resources.
-
-
If you’re creating a cluster and want the cluster to assign
IPv6
addresses to Pods and services instead ofIPv4
addresses, add--kubernetes-network-config ipFamily=ipv6
to the following command.Kubernetes assigns
IPv4
addresses to Pods and services, by default. Before deciding to use theIPv6
family, make sure that you’re familiar with all of the considerations and requirements in the VPC requirements and considerations, Subnet requirements and considerations, View Amazon EKS security group requirements for clusters, and Learn about IPv6 addresses to clusters, pods, and services topics. If you choose theIPv6
family, you can’t specify an address range for Kubernetes to assignIPv6
service addresses from like you can for theIPv4
family. Kubernetes assigns service addresses from the unique local address range (fc00::/7
).
-
-
It takes several minutes to provision the cluster. You can query the status of your cluster with the following command.
aws eks describe-cluster --region region-code --name my-cluster --query "cluster.status"
Don’t proceed to the next step until the output returned is
ACTIVE
. -
Continue with Step 3: Update kubeconfig
Step 3: Update kubeconfig
-
If you created your cluster using
eksctl
, then you can skip this step. This is becauseeksctl
already completed this step for you. Enablekubectl
to communicate with your cluster by adding a new context to thekubectl
config
file. For more information about how to create and update the file, see Connect kubectl to an EKS cluster by creating a kubeconfig file.aws eks update-kubeconfig --region region-code --name my-cluster
An example output is as follows.
Added new context arn:aws-cn:eks:region-code:111122223333:cluster/my-cluster to /home/username/.kube/config
-
Confirm communication with your cluster by running the following command.
kubectl get svc
An example output is as follows.
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE kubernetes ClusterIP 10.100.0.1 <none> 443/TCP 28h
Step 4: Cluster setup
-
(Recommended) To use some Amazon EKS add-ons, or to enable individual Kubernetes workloads to have specific Amazon Identity and Access Management (IAM) permissions, create an IAM OpenID Connect (OIDC) provider for your cluster. You only need to create an IAM OIDC provider for your cluster once. To learn more about Amazon EKS add-ons, see Amazon EKS add-ons. To learn more about assigning specific IAM permissions to your workloads, see IAM roles for service accounts.
-
(Recommended) Configure your cluster for the Amazon VPC CNI plugin for Kubernetes plugin before deploying Amazon EC2 nodes to your cluster. By default, the plugin was installed with your cluster. When you add Amazon EC2 nodes to your cluster, the plugin is automatically deployed to each Amazon EC2 node that you add. The plugin requires you to attach one of the following IAM policies to an IAM role. If your cluster uses the
IPv4
family, use the AmazonEKS_CNI_Policy managed IAM policy. If your cluster uses theIPv6
family, use an IAM policy that you create.The IAM role that you attach the policy to can be the node IAM role, or a dedicated role used only for the plugin. We recommend attaching the policy to this role. For more information about creating the role, see Configure Amazon VPC CNI plugin to use IRSA or Amazon EKS node IAM role.
-
If you deployed your cluster using the Amazon Web Services Management Console, you can skip this step. The Amazon Web Services Management Console deploys the Amazon VPC CNI plugin for Kubernetes, CoreDNS, and
kube-proxy
Amazon EKS add-ons, by default.If you deploy your cluster using either
eksctl
or the Amazon CLI, then the Amazon VPC CNI plugin for Kubernetes, CoreDNS, andkube-proxy
self-managed add-ons are deployed. You can migrate the Amazon VPC CNI plugin for Kubernetes, CoreDNS, andkube-proxy
self-managed add-ons that are deployed with your cluster to Amazon EKS add-ons. For more information, see Amazon EKS add-ons. -
(Optional) If you haven’t already done so, you can enable Prometheus metrics for your cluster. For more information, see Create a scraper in the Amazon Managed Service for Prometheus User Guide.
-
If you plan to deploy workloads to your cluster that use Amazon EBS volumes , and you created a
1.23
or later cluster, then you must install the Amazon EBS CSI to your cluster before deploying the workloads.
Next steps
-
The IAM principal that created the cluster is the only principal that has access to the cluster. Grant permissions to other IAM principals so they can access your cluster.
-
If the IAM principal that created the cluster only has the minimum IAM permissions referenced in the prerequisites, then you might want to add additional Amazon EKS permissions for that principal. For more information about granting Amazon EKS permissions to IAM principals, see Identity and access management for Amazon EKS.
-
If you want the IAM principal that created the cluster, or any other principals to view Kubernetes resources in the Amazon EKS console, grant the Required permissions to the entities.
-
If you want nodes and IAM principals to access your cluster from within your VPC, enable the private endpoint for your cluster. The public endpoint is enabled by default. You can disable the public endpoint once you’ve enabled the private endpoint, if desired. For more information, see Control network access to cluster API server endpoint.