-
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
-
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 the iam: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 or iam:AttachRolePolicy.
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonEKSClusterPolicy --role-name myAmazonEKSClusterRole
-
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.191.0 or later of the eksctl command
line tool installed on your device or AWS CloudShell. To install or update eksctl, see Installation in the eksctl documentation.
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
-
Replace my-cluster
-
Replace 1.31
To deploy a 1.31 cluster at this
time, you need to use the AWS Management Console or the AWS CLI.
-
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.
eksctl create cluster --name my-cluster --region region-code --version 1.31 --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
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 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 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, View Amazon EKS security group requirements for clusters, and Assign 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 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
Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters.
-
Choose Add cluster and then choose
Create.
-
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.
-
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.
-
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 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.
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 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, View Amazon EKS security group requirements for clusters, and Assign 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 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 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.
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.
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. 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. You can update the configuration of each
add-on after cluster creation. For more information about
configuring add-ons, see Updating 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.
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
-
Create your cluster with the command that follows. Before
running the command, make the following replacements:
-
Replace
region-code
-
Replace
my-cluster
-
Replace
1.31
-
Replace
111122223333myAmazonEKSClusterRole
-
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 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 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.31 \
--role-arn arn:aws:iam::111122223333:role/myAmazonEKSClusterRole \
--resources-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 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.
-
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
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
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, View Amazon EKS security group requirements for clusters, and Assign 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 addresses from like you can for the IPv4 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.
-
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
-
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
-
(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.
-
(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:
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 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.
-
(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 enabled Prometheus metrics, you must set up your
aws-auth
ConfigMap to give the scraper in-cluster permissions. For more
information, see Configuring your Amazon EKS cluster 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 Store Kubernetes volumes with Amazon EBS to your cluster before deploying the workloads.
