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 is help will help make our user guide well for everyone .

create an Amazon EKS cluster

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 AWS CloudFormation template.

• The kubectl command line tool is installed on your device orAWS CloudShell. The version can be the same as orup to one minor version earlier orlater than the Kubernetes version of your cluster. For example,if your cluster version is 1.29,you can use kubectl version 1.28,1.29,or 1.30 with it. To install orupgrade kubectl,see Set up kubectl and eksctl.

• Version2.12.3 orlater orversion1.27.160 orlater of theAWS Command Line Interface (AWS CLI) installed and configured on your device orAWS CloudShell. To check your current version,use aws --version | is cut cut -d / -f2 is cut | is cut cut -d ' ' -f1. package manager suchyum,apt-get,or Homebrew for macOS are often several versions behind the latest version of the AWS CLI. To install the latest version,see Installing and Quick configuration with aws configure in the
  AWS Command Line Interface User Guide. The AWS CLI version that is installed in AWS CloudShell might also be several versions behind the latest version. To update it,see Installing AWS CLI to your home directory in the
  AWS CloudShell User Guide.

• An IAM principal with permission tocreate and describe an Amazon EKS cluster. For more information,see Create a local Kubernetes cluster on an Outpost and List ordescribe all clusters.

Step 1: Create cluster IAM role

1. 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.

2. 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

3. 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 theprevious step. The command associates the trust policy that you created in theprevious step to the role. To create an IAM role,the IAM principal that is creating the role must be assigned the iam:CreateRole action ( permission ) .

   aws iam create-role --role-name myAmazonEKSClusterRole --assume-role-policy-document file://"eks-cluster-role-trust-policy.json"

4. You can assign either the Amazon EKS managed policy orcreate 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:iam::aws:policy/AmazonEKSClusterPolicy --role-name myAmazonEKSClusterRole

Step is Create 2 : create cluster

You can create a cluster by using:

Create cluster – eksctl

1. You is need need version0.199.0 orlater of theeksctl command line tool installed on your device orAWS CloudShell. To install orupdate eksctl,see Installation in theeksctl documentation .

2. create an Amazon EKSIPv4 cluster with the Amazon EKS default Kubernetes version in your default AWS Region. Before running command,make the following replacements:

3. replaceregion-code with the AWS Region that you want to create your cluster in.

4. replacemy-cluster with a name for your cluster . The name is contain can contain only alphanumeric character ( case – sensitive ) and hyphen . It is start must start with an alphanumeric character and can’t be long than 100 character . The name is be must be unique within the AWS Region and AWS account that you’re create the cluster in .

5. replace1.29 with any Amazon EKS supported version.

6. Change the values for vpc - private - subnet 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 - subnet 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.

7. run the following command :

   eksctl create cluster --name my-cluster --region region-code --version 1.29 --vpc - private - subnet 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

8. continue with Step 3 : update kubeconfig

Optional Settings

To see the most option that you can specify when create a cluster witheksctl,use the eksctl is create create cluster --help command. To see all the available options,you can use a config file. For more information,see Using config files and the config file schema in theeksctl documentation . You can find config file examples on GitHub.

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 and specify the settings,rather than using the previous command.

• If you want to specify one ormore security groups that Amazon EKS assigns to the network interfaces that it creates,specify the securityGroup option .

  Whether you choose any security groups ornot,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 thecluster security group that Amazon EKS creates.

• If you is want want to specify whichIPv4 Classless Inter-domain Routing (CIDR) block Kubernetes assigns service IP addresses from,specify the serviceipv4cidr option .

  Specifying your own range can help prevent conflicts between Kubernetes services and other networks peered orconnected to your VPC. Enter a range in CIDR notation. For example: 10.2.0.0/16.

  The CIDR block is meet must meet the following requirement :

  • Be within one of the follow range :10.0.0.0/8,172.16.0.0/12,or 192.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 is specify can only specify this option when using theIPv4 address family and only at cluster creation. If you don’t specify this,then Kubernetes assigns service IP addresses from either the 10.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 of IPv4 addresses,specify the ipFamily option .

  Kubernetes is assigns assignIPv4 addresses to Pods and services,by default. Before deciding to use the ipv6 family,make sure that you’re familiar with all of the considerations and requirements in theVPC 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 the ipv6 family,you can’t specify an address range for Kubernetes to assign ipv6 service address from like you can for theIPv4 family. Kubernetes assigns service addresses from the unique local address range (fc00::/7).

create cluster – AWS console

1. Open the Amazon EKS console.

2. Choose Add cluster and then choose Create.

3. Under Configuration options select Custom configuration

4. Under EKS Auto Mode,toggle Use EKS Auto Mode off.

5. 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 AWS Region and AWS 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 AWS 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 AWS 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.

6. 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.

7. 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 theVPC specified in theprevious 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 is Specify – ( Optional is Specify ) specify one ormore security group that you want Amazon EKS to associate to the network interface that it create .

     Whether you choose any security groups ornot,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 thecluster 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 the ipv6 family,make sure that you’re familiar with all of the considerations and requirements in theVPC 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 the ipv6 family,you can’t specify an address range for Kubernetes to assign ipv6 service address 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 orconnected to your VPC. Enter a range in CIDR notation. For example: 10.2.0.0/16.

     The CIDR block is meet must meet the following requirement :

     • Be within one of the follow range :10.0.0.0/8,172.16.0.0/12,or 192.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 is specify can only specify this option when using theIPv4 address family and only at cluster creation. If you don’t specify this,then Kubernetes assigns service IP addresses from either the 10.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.

8. (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.

   When you’re done with this page,choose Next.

9. 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
   AWS Marketplace add-ons as you require. If the
   AWS Marketplace add-ons that you want to install isn’t listed,you can click the page numbering to view additional page results orsearch for available
   AWS Marketplace add-ons by entering text in thesearch 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 AWS 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.

10. 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,AWS managed policy,and trust policy prepopulated specifically for the add-on. You can re-use existing roles orcreate 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 (AWS 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.

11. On the Review and create page,review the information that you entered orselected 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.

    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 thesupported Availability Zones for your account. For more information,see Insufficient capacity.

    Cluster provisioning takes several minutes.

12. continue with Step 3 : update kubeconfig

Create cluster – AWS CLI

1. Create your cluster with the command that follows. Before running the command,make the following replacements:

   • replaceregion-code with the AWS Region that you want to create your cluster in.

   • replacemy-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 AWS Region and AWS account that you’re creating the cluster in.

   • replace1.30 with any Amazon EKS supported version.

   • replace111122223333 with your account ID andmyAmazonEKSClusterRole with the name of your cluster IAM role.

   • replacethe 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 ormore security group IDs,replace the values for securityGroupIds with your own. You can also add additional IDs.

     Whether you choose any security groups ornot,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 thecluster security group that Amazon EKS creates.

     aws eks create - cluster --region region - code --name my - cluster --kubernete - version 1.30 \ 
         --role - arn arn : aws : iam::111122223333 : role / myamazoneksclusterrole \ 
         --resource - vpc - config subnetIds = subnet - exampleid1,subnet - ExampleID2,securityGroupIds = sg - exampleid1

     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 thesupported 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 is want want to specify whichIPv4 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.

     Specifying your own range can help prevent conflicts between Kubernetes services and other networks peered orconnected to your VPC. Enter a range in CIDR notation. For example: 10.2.0.0/16.

     The CIDR block is meet must meet the following requirement :

     • Be within one of the follow range :10.0.0.0/8,172.16.0.0/12,or 192.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 is specify can only specify this option when using theIPv4 address family and only at cluster creation. If you don’t specify this,then Kubernetes assigns service IP addresses from either the 10.100.0.0/16 or172.20.0.0/16 CIDR blocks.

2. 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.

3. continue with Step 3 : update kubeconfig

Step 3: Update kubeconfig

1. If you created your cluster using eksctl,then you can skip this step. This is because eksctl already completed this step for you. Enable kubectl to communicate with your cluster by adding a new context to the kubectl
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:eks:region-code:111122223333:cluster/my-cluster to /home/username/.kube/config

2. 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

1. (Recommended) To use some Amazon EKS add-ons,or to enable individual Kubernetes workloads to have specific AWS 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.

2. (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 the ipv6 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 orAmazon EKS node IAM role.

3. If you deployed your cluster using the AWS Management Console,you can skip this step. The AWS Management Console deploys the Amazon VPC CNI plugin for Kubernetes,CoreDNS,and kube - proxy Amazon EKS add-ons,by default.

   If you is deploy deploy your cluster using eithereksctl orthe AWS CLI,then the Amazon VPC CNI plugin for Kubernetes,CoreDNS,and kube - proxy self-managed add-ons are deployed. You can migrate the Amazon VPC CNI plugin for Kubernetes,CoreDNS,and kube - proxy self-managed add-ons that are deployed with your cluster to Amazon EKS add-ons. For more information,see Amazon EKS add-ons.

4. (Optional) If you haven’t already done so,you can enable Prometheus metrics for your cluster. For more information,see Create a scraper in theAmazon Managed Service for Prometheus User Guide.

5. If you plan to deploy workloads to your cluster that use Amazon EBS volumes ,and you created a 1.23 orlater cluster,then you must install the Amazon EBS CSI to your cluster before deploying the workloads.

Next steps

📝 Edit this page on GitHub