Creating an Amazon EKS cluster - Amazon EKS

Creating 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 on an AWS Outpost, see Local clusters for Amazon EKS on AWS Outposts. If this is your first time creating an Amazon EKS cluster, we recommend that you follow one of our Getting started with Amazon EKS guides. These guides help you to create a simple, default cluster without expanding into all of the available options.

Prerequisites

When an Amazon EKS cluster is created, the IAM principal that creates the cluster is permanently added to the Kubernetes RBAC authorization table as the administrator. This principal has system:masters permissions. This principal isn't visible in your cluster configuration. So, it's important to note the principal that created the cluster and make sure that you never delete it. Initially, only the IAM principal that created the server can make calls to the Kubernetes API server using kubectl. If you use the console to create the cluster, you must ensure that the same IAM credentials are in the AWS SDK credential chain when you run kubectl commands on your cluster. After your cluster is created, you can grant other IAM principals access to your cluster.

To create an Amazon EKS cluster

  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.

    To create an Amazon EKS cluster IAM role

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

    2. 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 the iam:CreateRole action (permission).

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

    3. 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 or iam:AttachRolePolicy.

      aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonEKSClusterPolicy --role-name myAmazonEKSClusterRole
    Show moreShow less

  2. Create an Amazon EKS cluster.

    You can create a cluster by using eksctl, the AWS Management Console, or the AWS CLI.

    eksctl
    Prerequisite

    Version 0.159.0 or later of the eksctl command line tool installed on your device or AWS CloudShell. To install or update eksctl, see Installing or updating eksctl.

    To create your cluster

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

    • Replace region-code with the AWS 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 alphabetic 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.

    • Replace 1.27 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. You can't change which subnets you want to use after cluster creation. 

    eksctl create cluster --name my-cluster --region region-code --version 1.27 --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
    Tip

    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 files and the config file schema in the eksctl documentation. You can find config file examples on GitHub.

    Optional settings

    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 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 Amazon EKS security group requirements and considerations. You can modify the rules in the cluster security group that Amazon EKS creates. If you choose to add your own security groups, you can't change the ones that you choose after cluster creation.

    • If you want to specify which IPv4 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 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, 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 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 the 10.100.0.0/16 or 172.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 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 the VPC requirements and considerations, Subnet requirements and considerations, Amazon EKS security group requirements and considerations, and Tutorial: Assigning IPv6 addresses to Pods and services topics. If you choose the IPv6 family, you can't specify an address range for Kubernetes to assign IPv6 service addresses from like you can for the IPv4 family. Kubernetes assigns service addresses from the unique local address range (fc00::/7).

    AWS Management Console
    To create your cluster

    1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters.

    2. Choose Add cluster and then choose Create.

    3. On the Configure cluster page, enter the following fields:

      • Name – A name for your cluster. It must be unique in your AWS account. The name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic 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.

      • Kubernetes version – The version of Kubernetes to use for your cluster. We recommend selecting the latest version, unless you need an earlier version.

      • Cluster service role – Choose the Amazon EKS cluster IAM role that you created to allow the Kubernetes control plane to manage AWS resources on your behalf.

      • 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 Enabling secret encryption on an existing cluster.

      • Tags – (Optional) Add any tags to your cluster. For more information, see Tagging your Amazon EKS resources.

    4. Choose Next.

    5. 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 Amazon EKS VPC and subnet requirements and considerations. 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 Creating a 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. You can't change which subnets you want to use after cluster creation.

        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 Amazon EKS security group requirements and considerations. You can modify the rules in the cluster security group that Amazon EKS creates. If you choose to add your own security groups, you can't change the ones that you choose after cluster creation.

      • 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 the VPC requirements and considerations, Subnet requirements and considerations, Amazon EKS security group requirements and considerations, and Tutorial: Assigning IPv6 addresses to Pods and services topics. If you choose the IPv6 family, you can't specify an address range for Kubernetes to assign IPv6 service addresses from like you can for the IPv4 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, 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 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 the 10.100.0.0/16 or 172.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 Amazon EKS cluster endpoint access control.

    6. On the Configure logging page, you can optionally choose which log types that you want to enable. By default, each log type is Disabled. Before selecting a different option, familiarize yourself with the information in Amazon EKS control plane logging. After you create the cluster, you can change this option.

    7. Select Next.

    8. On the Select add-ons page, choose the add-ons that you want to add to your cluster. 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 search for available AWS Marketplace add-ons by entering text in the search box. You can also search by category, vendor, or pricing model and then choose the add-ons from the search results. Once you've selected the add-ons that you want to install, choose Next.

    9. On the Configure selected add-ons settings page, select the version that you want to install and then choose Next. You can always update to a later version after cluster creation. You can update the configuration of each add-on after cluster creation. For more information about configuring add-ons, see Updating an add-on.

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

    AWS CLI
    To create your cluster

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

      • Replace region-code with the AWS 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 alphabetic 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.

      • Replace 1.28 with any Amazon EKS supported version.

      • Replace 111122223333 with your account ID and myAmazonEKSClusterRole 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. You can't change which subnets you want to use after cluster creation.

      • 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 for securityGroupIds 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 Amazon EKS security group requirements and considerations. You can modify the rules in the cluster security group that Amazon EKS creates. If you choose to add your own security groups, you can't change the ones that you choose after cluster creation.

      aws eks create-cluster --region region-code --name my-cluster --kubernetes-version 1.28 \
   --role-arn arn:aws: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.

      Optional settings

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

        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, 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 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 the 10.100.0.0/16 or 172.20.0.0/16 CIDR blocks.

      • If you're creating a cluster and want the cluster to assign IPv6 addresses to Pods and services instead of IPv4 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 the IPv6 family, make sure that you're familiar with all of the considerations and requirements in the VPC requirements and considerations, Subnet requirements and considerations, Amazon EKS security group requirements and considerations, and Tutorial: Assigning IPv6 addresses to Pods and services topics. If you choose the IPv6 family, you can't specify an address range for Kubernetes to assign IPv6 service addresses from like you can for the IPv4 family. Kubernetes assigns service addresses from the unique local address range (fc00::/7).

    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. 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 Creating or updating a kubeconfig file for an Amazon EKS cluster.

    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

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

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

    Show moreShow less

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

    AmazonEKS_CNI_Policy managed IAM policy

    If your cluster uses the IPv4 family

    Show moreShow less
    An IAM policy that you create

    If your cluster uses the IPv6 family

    Show moreShow less

    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 Configuring the Amazon VPC CNI plugin for Kubernetes to use IAM roles for service accounts or Amazon EKS node IAM role.

    Show moreShow less

  7. 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 deploy your cluster using either eksctl or the 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.

    Show moreShow less

  8. 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 driver to your cluster before deploying the workloads.

Recommended next steps: