EKS via SDK Basics

Seven short examples that take you from an empty account to a running cluster with worker capacity, all through the EKS SDK. Each shows the same operation in Python (boto3) and TypeScript (AWS SDK for JavaScript v3).

Two of these steps - building the IAM roles and building a kubeconfig - are not EKS SDK calls, and they are flagged as such so the boundary stays clear.

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-eks (Node.js 18+).
Credentials with eks:* on the cluster plus iam:PassRole for the cluster and node roles.
A cluster IAM role (trusts eks.amazonaws.com, has AmazonEKSClusterPolicy) and a node IAM role (trusts ec2.amazonaws.com, has AmazonEKSWorkerNodePolicy, AmazonEC2ContainerRegistryReadOnly, and AmazonEKS_CNI_Policy). Create these once with the IAM SDK or IaC.
Two or more subnets in different AZs.

Basic Examples

1. Create a Cluster

CreateCluster provisions the AWS-managed control plane. Pass the cluster role, a Kubernetes version, and the VPC networking it should live in.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.create_cluster(
    name="platform",
    roleArn="arn:aws:iam::111122223333:role/eksClusterRole",
    version="1.30",
    resourcesVpcConfig={
        "subnetIds": ["subnet-0aaa", "subnet-0bbb"],
        "endpointPublicAccess": True,
        "endpointPrivateAccess": True,
    },
)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, CreateClusterCommand } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new CreateClusterCommand({
  name: "platform",
  roleArn: "arn:aws:iam::111122223333:role/eksClusterRole",
  version: "1.30",
  resourcesVpcConfig: {
    subnetIds: ["subnet-0aaa", "subnet-0bbb"],
    endpointPublicAccess: true,
    endpointPrivateAccess: true,
  },
}));

roleArn is the cluster role, not a node role; the control plane assumes it.
version pins the Kubernetes minor version; omit it to get the current default.
resourcesVpcConfig.subnetIds must span at least two AZs.
The call returns immediately with status: CREATING - it is not usable yet.

2. Wait for the Cluster to Become Active

Use a waiter instead of a sleep loop. It polls DescribeCluster until status is ACTIVE.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.get_waiter("cluster_active").wait(name="platform")
print("cluster is ACTIVE")

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, waitUntilClusterActive } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await waitUntilClusterActive({ client: eks, maxWaitTime: 900 }, { name: "platform" });
console.log("cluster is ACTIVE");

Control-plane creation typically takes several minutes, so allow a generous maxWaitTime.
boto3 waiters have sensible built-in delays and attempt counts.
The v3 waiter needs an explicit maxWaitTime in seconds.
Only after this returns can you attach node groups or connect with kubectl.

3. Describe the Cluster

DescribeCluster returns the fields you need to connect and to wire IRSA later.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
c = eks.describe_cluster(name="platform")["cluster"]
print(c["endpoint"])                        # API server URL
print(c["certificateAuthority"]["data"])    # base64 CA cert
print(c["identity"]["oidc"]["issuer"])      # OIDC issuer for IRSA

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, DescribeClusterCommand } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
const c = (await eks.send(new DescribeClusterCommand({ name: "platform" }))).cluster;
console.log(c?.endpoint);                       // API server URL
console.log(c?.certificateAuthority?.data);     // base64 CA cert
console.log(c?.identity?.oidc?.issuer);         // OIDC issuer for IRSA

endpoint plus certificateAuthority.data are exactly what a kubeconfig needs.
identity.oidc.issuer is the trust anchor for IAM Roles for Service Accounts.
status here also reports UPDATING during an in-place version or config change.
version and platformVersion tell you the Kubernetes and EKS platform levels.

4. List Clusters

ListClusters returns cluster names in the region; page through if you run many.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
for page in eks.get_paginator("list_clusters").paginate():
    for name in page["clusters"]:
        print(name)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, paginateListClusters } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
for await (const page of paginateListClusters({ client: eks }, {})) {
  for (const name of page.clusters ?? []) console.log(name);
}

ListClusters returns names only; call DescribeCluster per name for details.
Both SDKs offer paginators so you never manage nextToken by hand.
Results are region-scoped, like nearly every EKS operation.
It also lists connected (EKS Anywhere) clusters registered to the region.

Intermediate Examples

5. Create a Managed Node Group

CreateNodegroup attaches worker capacity. It needs the node role, subnets, and a scalingConfig.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.create_nodegroup(
    clusterName="platform",
    nodegroupName="general",
    nodeRole="arn:aws:iam::111122223333:role/eksNodeRole",
    subnets=["subnet-0aaa", "subnet-0bbb"],
    scalingConfig={"minSize": 2, "maxSize": 5, "desiredSize": 2},
    instanceTypes=["t3.large"],
    amiType="AL2023_x86_64_STANDARD",
    capacityType="ON_DEMAND",
)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, CreateNodegroupCommand } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new CreateNodegroupCommand({
  clusterName: "platform",
  nodegroupName: "general",
  nodeRole: "arn:aws:iam::111122223333:role/eksNodeRole",
  subnets: ["subnet-0aaa", "subnet-0bbb"],
  scalingConfig: { minSize: 2, maxSize: 5, desiredSize: 2 },
  instanceTypes: ["t3.large"],
  amiType: "AL2023_x86_64_STANDARD",
  capacityType: "ON_DEMAND",
}));

nodeRole is the EC2 instance role for the workers, distinct from the cluster role.
amiType selects the managed AMI family, such as AL2023_x86_64_STANDARD.
capacityType is ON_DEMAND or SPOT.
Like the cluster, a node group starts CREATING and needs a waiter.

6. Wait for the Node Group, Then Build a kubeconfig

Wait on nodegroup_active, then connect. The connect step is a CLI/kubectl action, not an SDK call.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.get_waiter("nodegroup_active").wait(
    clusterName="platform", nodegroupName="general",
)
print("nodes are ACTIVE")

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, waitUntilNodegroupActive } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await waitUntilNodegroupActive(
  { client: eks, maxWaitTime: 900 },
  { clusterName: "platform", nodegroupName: "general" },
);
console.log("nodes are ACTIVE");

Once the nodes are active, get a kubeconfig so kubectl can talk to the cluster. This is a plain shell step:

# NOT an EKS SDK call - this writes a kubeconfig entry for kubectl.
aws eks update-kubeconfig --name platform --region us-east-1
kubectl get nodes   # your managed node group should appear as Ready

The waiter blocks until the EC2 workers join the cluster and report healthy.
update-kubeconfig merges an entry into ~/.kube/config; it does not touch AWS state.
From here on, deploying apps is the Kubernetes API's job, not the EKS SDK's.
If kubectl get nodes is empty, the access side (entry or aws-auth) is usually the cause.

7. Clean Up

Delete the node group first, wait for it to go, then delete the cluster. Order matters.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.delete_nodegroup(clusterName="platform", nodegroupName="general")
eks.get_waiter("nodegroup_deleted").wait(
    clusterName="platform", nodegroupName="general",
)
eks.delete_cluster(name="platform")

// --- TypeScript (AWS SDK v3) ---
import {
  EKSClient, DeleteNodegroupCommand, DeleteClusterCommand, waitUntilNodegroupDeleted,
} from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new DeleteNodegroupCommand({ clusterName: "platform", nodegroupName: "general" }));
await waitUntilNodegroupDeleted(
  { client: eks, maxWaitTime: 900 },
  { clusterName: "platform", nodegroupName: "general" },
);
await eks.send(new DeleteClusterCommand({ name: "platform" }));

DeleteCluster fails while node groups, Fargate profiles, or add-ons still exist - remove them first.
Waiting on nodegroup_deleted ensures the workers are gone before the control plane.
A running control plane bills per hour, so tear down test clusters promptly.
Deleting the cluster does not delete the IAM roles or subnets you supplied.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Two of these steps - building the IAM roles and building a kubeconfig - are not EKS SDK calls, and they are flagged as such so the boundary stays clear.

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-eks (Node.js 18+).
Credentials with eks:* on the cluster plus iam:PassRole for the cluster and node roles.
A cluster IAM role (trusts eks.amazonaws.com, has AmazonEKSClusterPolicy) and a node IAM role (trusts ec2.amazonaws.com, has AmazonEKSWorkerNodePolicy, AmazonEC2ContainerRegistryReadOnly, and AmazonEKS_CNI_Policy). Create these once with the IAM SDK or IaC.
Two or more subnets in different AZs.

Basic Examples

1. Create a Cluster

CreateCluster provisions the AWS-managed control plane. Pass the cluster role, a Kubernetes version, and the VPC networking it should live in.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.create_cluster(
    name="platform",
    roleArn="arn:aws:iam::111122223333:role/eksClusterRole",
    version="1.30",
    resourcesVpcConfig={
        "subnetIds": ["subnet-0aaa", "subnet-0bbb"],
        "endpointPublicAccess": True,
        "endpointPrivateAccess": True,
    },
)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, CreateClusterCommand } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new CreateClusterCommand({
  name: "platform",
  roleArn: "arn:aws:iam::111122223333:role/eksClusterRole",
  version: "1.30",
  resourcesVpcConfig: {
    subnetIds: ["subnet-0aaa", "subnet-0bbb"],
    endpointPublicAccess: true,
    endpointPrivateAccess: true,
  },
}));

roleArn is the cluster role, not a node role; the control plane assumes it.
version pins the Kubernetes minor version; omit it to get the current default.
resourcesVpcConfig.subnetIds must span at least two AZs.
The call returns immediately with status: CREATING - it is not usable yet.

2. Wait for the Cluster to Become Active

Use a waiter instead of a sleep loop. It polls DescribeCluster until status is ACTIVE.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.get_waiter("cluster_active").wait(name="platform")
print("cluster is ACTIVE")

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, waitUntilClusterActive } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await waitUntilClusterActive({ client: eks, maxWaitTime: 900 }, { name: "platform" });
console.log("cluster is ACTIVE");

Control-plane creation typically takes several minutes, so allow a generous maxWaitTime.
boto3 waiters have sensible built-in delays and attempt counts.
The v3 waiter needs an explicit maxWaitTime in seconds.
Only after this returns can you attach node groups or connect with kubectl.

3. Describe the Cluster

DescribeCluster returns the fields you need to connect and to wire IRSA later.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
c = eks.describe_cluster(name="platform")["cluster"]
print(c["endpoint"])                        # API server URL
print(c["certificateAuthority"]["data"])    # base64 CA cert
print(c["identity"]["oidc"]["issuer"])      # OIDC issuer for IRSA

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, DescribeClusterCommand } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
const c = (await eks.send(new DescribeClusterCommand({ name: "platform" }))).cluster;
console.log(c?.endpoint);                       // API server URL
console.log(c?.certificateAuthority?.data);     // base64 CA cert
console.log(c?.identity?.oidc?.issuer);         // OIDC issuer for IRSA

endpoint plus certificateAuthority.data are exactly what a kubeconfig needs.
identity.oidc.issuer is the trust anchor for IAM Roles for Service Accounts.
status here also reports UPDATING during an in-place version or config change.
version and platformVersion tell you the Kubernetes and EKS platform levels.

4. List Clusters

ListClusters returns cluster names in the region; page through if you run many.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
for page in eks.get_paginator("list_clusters").paginate():
    for name in page["clusters"]:
        print(name)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, paginateListClusters } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
for await (const page of paginateListClusters({ client: eks }, {})) {
  for (const name of page.clusters ?? []) console.log(name);
}

ListClusters returns names only; call DescribeCluster per name for details.
Both SDKs offer paginators so you never manage nextToken by hand.
Results are region-scoped, like nearly every EKS operation.
It also lists connected (EKS Anywhere) clusters registered to the region.

Intermediate Examples

5. Create a Managed Node Group

CreateNodegroup attaches worker capacity. It needs the node role, subnets, and a scalingConfig.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.create_nodegroup(
    clusterName="platform",
    nodegroupName="general",
    nodeRole="arn:aws:iam::111122223333:role/eksNodeRole",
    subnets=["subnet-0aaa", "subnet-0bbb"],
    scalingConfig={"minSize": 2, "maxSize": 5, "desiredSize": 2},
    instanceTypes=["t3.large"],
    amiType="AL2023_x86_64_STANDARD",
    capacityType="ON_DEMAND",
)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, CreateNodegroupCommand } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new CreateNodegroupCommand({
  clusterName: "platform",
  nodegroupName: "general",
  nodeRole: "arn:aws:iam::111122223333:role/eksNodeRole",
  subnets: ["subnet-0aaa", "subnet-0bbb"],
  scalingConfig: { minSize: 2, maxSize: 5, desiredSize: 2 },
  instanceTypes: ["t3.large"],
  amiType: "AL2023_x86_64_STANDARD",
  capacityType: "ON_DEMAND",
}));

nodeRole is the EC2 instance role for the workers, distinct from the cluster role.
amiType selects the managed AMI family, such as AL2023_x86_64_STANDARD.
capacityType is ON_DEMAND or SPOT.
Like the cluster, a node group starts CREATING and needs a waiter.

6. Wait for the Node Group, Then Build a kubeconfig

Wait on nodegroup_active, then connect. The connect step is a CLI/kubectl action, not an SDK call.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.get_waiter("nodegroup_active").wait(
    clusterName="platform", nodegroupName="general",
)
print("nodes are ACTIVE")

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, waitUntilNodegroupActive } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await waitUntilNodegroupActive(
  { client: eks, maxWaitTime: 900 },
  { clusterName: "platform", nodegroupName: "general" },
);
console.log("nodes are ACTIVE");

Once the nodes are active, get a kubeconfig so kubectl can talk to the cluster. This is a plain shell step:

# NOT an EKS SDK call - this writes a kubeconfig entry for kubectl.
aws eks update-kubeconfig --name platform --region us-east-1
kubectl get nodes   # your managed node group should appear as Ready

The waiter blocks until the EC2 workers join the cluster and report healthy.
update-kubeconfig merges an entry into ~/.kube/config; it does not touch AWS state.
From here on, deploying apps is the Kubernetes API's job, not the EKS SDK's.
If kubectl get nodes is empty, the access side (entry or aws-auth) is usually the cause.

7. Clean Up

Delete the node group first, wait for it to go, then delete the cluster. Order matters.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.delete_nodegroup(clusterName="platform", nodegroupName="general")
eks.get_waiter("nodegroup_deleted").wait(
    clusterName="platform", nodegroupName="general",
)
eks.delete_cluster(name="platform")

// --- TypeScript (AWS SDK v3) ---
import {
  EKSClient, DeleteNodegroupCommand, DeleteClusterCommand, waitUntilNodegroupDeleted,
} from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new DeleteNodegroupCommand({ clusterName: "platform", nodegroupName: "general" }));
await waitUntilNodegroupDeleted(
  { client: eks, maxWaitTime: 900 },
  { clusterName: "platform", nodegroupName: "general" },
);
await eks.send(new DeleteClusterCommand({ name: "platform" }));

DeleteCluster fails while node groups, Fargate profiles, or add-ons still exist - remove them first.
Waiting on nodegroup_deleted ensures the workers are gone before the control plane.
A running control plane bills per hour, so tear down test clusters promptly.
Deleting the cluster does not delete the IAM roles or subnets you supplied.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

EKS via SDK Basics

Buscar na documentação

EKS via SDK Basics