Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Help improve this page

Want to contribute to this user guide? Choose the Edit this page on GitHub link that is located in the right pane of every page. Your contributions will help make our user guide better for everyone.

Create an EKS Auto Mode Cluster with the Amazon CLI

EKS Auto Mode Clusters automate routine cluster management tasks for compute, storage, and networking. For example, EKS Auto Mode Clusters automatically detect when additional nodes are required and provision new EC2 instances to meet workload demands.

This topic guides you through creating a new EKS Auto Mode Cluster using the Amazon CLI and optionally deploying a sample workload.

Prerequisites

Specify VPC subnets

Amazon EKS Auto Mode deploy nodes to VPC subnets. When creating an EKS cluster, you must specify the VPC subnets where the nodes will be deployed. You can use the default VPC subnets in your Amazon account or create a dedicated VPC for critical workloads.

IAM Roles for EKS Auto Mode Clusters

Cluster IAM Role

EKS Auto Mode requires a Cluster IAM Role to perform actions in your Amazon account, such as provisioning new EC2 instances. You must create this role to grant EKS the necessary permissions. Amazon recommends attaching the following Amazon managed policies to the Cluster IAM Role:

Node IAM Role

When you create an EKS Auto Mode cluster, you specify a Node IAM Role. When EKS Auto Mode creates nodes to process pending workloads, each new EC2 instance node is assigned the Node IAM Role. This role allows the node to communicate with EKS but is generally not accessed by workloads running on the node.

If you want to grant permissions to workloads running on a node, use EKS Pod Identity. For more information, see Learn how EKS Pod Identity grants pods access to Amazon services.

You must create this role and attach the following Amazon managed policy:

EKS Auto Mode also requires a Service-Linked Role, which is automatically created and configured by Amazon. For more information, see AWSServiceRoleForAmazonEKS.

Create an EKS Auto Mode Cluster IAM Role

Step 1: Create the Trust Policy

Create a trust policy that allows the Amazon EKS service to assume the role. Save the policy as trust-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "eks.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ]
    }
  ]
}

Step 2: Create the IAM Role

Use the trust policy to create the Cluster IAM Role:

aws iam create-role \
    --role-name AmazonEKSAutoClusterRole \
    --assume-role-policy-document file://trust-policy.json

Step 3: Note the Role ARN

Retrieve and save the ARN of the new role for use in subsequent steps:

aws iam get-role --role-name AmazonEKSAutoClusterRole --query "Role.Arn" --output text

Step 4: Attach Required Policies

Attach the following Amazon managed policies to the Cluster IAM Role to grant the necessary permissions:

AmazonEKSClusterPolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSClusterPolicy

AmazonEKSComputePolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSComputePolicy

AmazonEKSBlockStoragePolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSBlockStoragePolicy

AmazonEKSLoadBalancingPolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSLoadBalancingPolicy

AmazonEKSNetworkingPolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSNetworkingPolicy

Create an EKS Auto Mode Node IAM Role

Step 1: Create the Trust Policy

Create a trust policy that allows the Amazon EKS service to assume the role. Save the policy as node-trust-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Step 2: Create the Node IAM Role

Use the node-trust-policy.json file from the previous step to define which entities can assume the role. Run the following command to create the Node IAM Role:

aws iam create-role \
    --role-name AmazonEKSAutoNodeRole \
    --assume-role-policy-document file://node-trust-policy.json

Step 3: Note the Role ARN

After creating the role, retrieve and save the ARN of the Node IAM Role. You will need this ARN in subsequent steps. Use the following command to get the ARN:

aws iam get-role --role-name AmazonEKSAutoNodeRole --query "Role.Arn" --output text

Step 4: Attach Required Policies

Attach the following Amazon managed policies to the Node IAM Role to provide the necessary permissions:

AmazonEKSWorkerNodeMinimalPolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoNodeRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSWorkerNodeMinimalPolicy

AmazonEC2ContainerRegistryPullOnly:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoNodeRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly

Create an EKS Auto Mode Cluster

Overview

To create an EKS Auto Mode Cluster using the Amazon CLI, you will need the following parameters:

Default Cluster Configurations

Review these default values and features before creating the cluster:

Note: Node Pools in EKS Auto Mode differ from Amazon EKS Managed Node Groups but can coexist in the same cluster.

Run the Command

Use the following command to create the cluster:

aws eks create-cluster \
  --region ${AWS_REGION} \
  --cli-input-json \
  "{
      \"name\": \"${CLUSTER_NAME}\",
      \"version\": \"${K8S_VERSION}\",
      \"roleArn\": \"${CLUSTER_ROLE_ARN}\",
      \"resourcesVpcConfig\": {
        \"subnetIds\": ${SUBNETS_JSON},
        \"endpointPublicAccess\": true,
        \"endpointPrivateAccess\": true
      },
      \"computeConfig\": {
        \"enabled\": true,
        \"nodeRoleArn\":\"${NODE_ROLE_ARN}\",
        \"nodePools\": [\"general-purpose\", \"system\"]
      },
      \"kubernetesNetworkConfig\": {
        \"elasticLoadBalancing\": {
          \"enabled\": true
        }
      },
      \"storageConfig\": {
        \"blockStorage\": {
          \"enabled\": true
        }
      },
      \"accessConfig\": {
        \"authenticationMode\": \"API\"
      }
    }

Check Cluster Status

Step 1: Verify Cluster Creation

Run the following command to check the status of your cluster. Cluster creation typically takes about 15 minutes:

aws eks describe-cluster --name "${CLUSTER_NAME}" --output json

Step 2: Update kubeconfig

Once the cluster is ready, update your local kubeconfig file to enable kubectl to communicate with the cluster. This configuration uses the Amazon CLI for authentication.

aws eks update-kubeconfig --name "${CLUSTER_NAME}"

Step 3: Verify Node Pools

List the Node Pools in your cluster using the following command:

kubectl get nodepools

Next Steps