EKS via SDK Best Practices

Q: Should I upgrade add-ons when I upgrade the cluster?

Yes. After a control-plane version bump, update vpc-cni, coredns, and kube-proxy to a compatible build via DescribeAddonVersions and UpdateAddon, or you risk incompatibility.

Q: How many OIDC providers do I need?

One per cluster. Register the cluster's issuer once with CreateOpenIDConnectProvider; every IRSA role reuses it, differing only in the trust policy's sub condition.

Q: Which access policy should most principals get?

The least-privilege one that still works - typically AmazonEKSEditPolicy or AmazonEKSViewPolicy scoped to specific namespaces, not cluster-wide AmazonEKSClusterAdminPolicy.

Q: How do I keep the API server from being publicly reachable?

Enable endpointPrivateAccess, and if public access is needed, restrict publicAccessCidrs to known ranges rather than leaving it open to the internet.

EKS is easy to stand up and easy to get subtly wrong: a cluster left on an unsupported version, a node group pinned to one AZ, a pod handed the node's broad role. These are the everyday ways EKS automation becomes fragile or insecure.

Walk this list once now, then use it as a review checklist before shipping any code that provisions, scales, or secures a cluster.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: async correctness and upgrades first, then capacity, access, and cost.
Check the boxes against your own code as a quick audit.
Revisit whenever you add a new cluster workflow or move code to a new account or region.

A - Async Operations & Reliability

Wait on every async operation. Use cluster_active, nodegroup_active, and addon_active waiters (or waitUntilClusterActive and friends) rather than assuming a create returned means ready.
Order teardown correctly. Delete node groups, Fargate profiles, and add-ons before the cluster; DeleteCluster fails while they exist, and waiting on nodegroup_deleted avoids the race.
Poll updates by id, not by guess. Async updates return an update id; check DescribeUpdate for Successful/Failed instead of sleeping a fixed time.
Rely on built-in retries. Both SDKs retry throttling and transient errors with backoff; tune max_attempts rather than reimplementing retries.

Wait for the cluster instead of guessing it finished.

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

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

B - Version & Upgrade Cadence

Upgrade one minor version at a time. EKS supports single-step control-plane upgrades (1.29 -> 1.30); skipping versions is not allowed, so stay current enough to hop one at a time.
Stay on a supported version. Kubernetes minors leave standard support on a schedule; falling behind risks forced upgrades and extended-support charges.
Upgrade add-ons alongside the control plane. After a version bump, update vpc-cni, coredns, and kube-proxy to a compatible build via DescribeAddonVersions + UpdateAddon.
Roll node groups after the control plane. Bring workers to the new version with UpdateNodegroupVersion, which drains gradually; the control plane can lead nodes by one minor, not more.
Test upgrades in non-prod first. Run the same SDK upgrade path against a staging cluster before production.

Update the control plane, then bring add-ons to a compatible version.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.update_cluster_version(name="platform", version="1.30")
eks.get_waiter("cluster_active").wait(name="platform")
eks.update_addon(clusterName="platform", addonName="vpc-cni",
                 addonVersion="v1.18.1-eksbuild.3", resolveConflicts="PRESERVE")

// --- TypeScript (AWS SDK v3) ---
import {
  EKSClient, UpdateClusterVersionCommand, UpdateAddonCommand, waitUntilClusterActive,
} from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new UpdateClusterVersionCommand({ name: "platform", version: "1.30" }));
await waitUntilClusterActive({ client: eks, maxWaitTime: 1800 }, { name: "platform" });
await eks.send(new UpdateAddonCommand({
  clusterName: "platform", addonName: "vpc-cni",
  addonVersion: "v1.18.1-eksbuild.3", resolveConflicts: "PRESERVE",
}));

C - Node Groups & Capacity

Set a sensible min and max. scalingConfig bounds protect you from both starvation and runaway cost; pick a max you are willing to pay for.
Let an autoscaler own desiredSize. With Cluster Autoscaler or Karpenter running, do not set desiredSize by hand - it fights the controller.
Spread subnets across AZs. List subnets in multiple Availability Zones on the node group so a single-AZ event does not take the tier down.
Use Spot for interruptible tiers. Set capacityType: SPOT for batch, CI, and stateless workloads to cut cost, with interruption handling in place.
Prefer managed node groups or Fargate over self-managed. Let EKS handle bootstrap, health, and upgrades unless you truly need custom node config.

D - Pod Access: IRSA First

Give pods AWS access with IRSA, not the node role. A per-service-account role scopes credentials to one workload instead of sharing the node's broad role.
Register the OIDC provider once per cluster. All IRSA roles reuse a single CreateOpenIDConnectProvider registration of the cluster issuer.
Pin the trust policy to one service account. Use StringEquals on sub (system:serviceaccount:ns:name) and aud = sts.amazonaws.com; never a wildcard.
One narrow role per workload. Roles are free; a role per service account keeps least privilege instead of a shared god-role.
Consider EKS Pod Identity for scale. For many clusters, CreatePodIdentityAssociation avoids per-cluster OIDC and per-role trust wiring and is easier to automate.

Read the issuer, register it once, then reuse it for every IRSA role.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
issuer = eks.describe_cluster(name="platform")["cluster"]["identity"]["oidc"]["issuer"]
 
iam = boto3.client("iam")
iam.create_open_id_connect_provider(
    Url=issuer,
    ClientIDList=["sts.amazonaws.com"],
    ThumbprintList=["9e99a48a9960b14926bb7f3b02e22da2b0ab7280"],
)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, DescribeClusterCommand } from "@aws-sdk/client-eks";
import { IAMClient, CreateOpenIDConnectProviderCommand } from "@aws-sdk/client-iam";
 
const eks = new EKSClient({ region: "us-east-1" });
const issuer = (await eks.send(new DescribeClusterCommand({ name: "platform" })))
  .cluster?.identity?.oidc?.issuer;
 
const iam = new IAMClient({});
await iam.send(new CreateOpenIDConnectProviderCommand({
  Url: issuer,
  ClientIDList: ["sts.amazonaws.com"],
  ThumbprintList: ["9e99a48a9960b14926bb7f3b02e22da2b0ab7280"],
}));

E - Human Access & Security

Use access entries, not aws-auth. Manage cluster access from the EKS SDK with CreateAccessEntry + AssociateAccessPolicy instead of the fragile, kubectl-edited ConfigMap.
Move clusters to authenticationMode API. Once every mapping is an access entry, switch off CONFIG_MAP so aws-auth cannot silently grant access - remembering the switch is one-way.
Grant least-privilege access policies. Prefer AmazonEKSEditPolicy or AmazonEKSViewPolicy scoped to namespaces over cluster-wide AmazonEKSClusterAdminPolicy.
Scope endpoints deliberately. Enable endpointPrivateAccess and restrict publicAccessCidrs so the API server is not reachable from anywhere.
Enable control-plane logging and encrypt secrets. Turn on the relevant logging types and use a KMS key for envelope encryption of Kubernetes secrets.

F - Cost & Cleanup

Tear down idle clusters. A control plane bills per hour whether or not it runs workloads; delete test and ephemeral clusters promptly.
Right-size before scaling out. Pick instance types that fit the workload; oversized nodes are the most common EKS waste.
Sweep for orphans. List clusters, node groups, and Fargate profiles by tag and age, and clean up anything past its purpose.
Tag clusters and node groups. A consistent tag schema (Environment, Owner, Cost-Center) makes cost allocation and cleanup possible.
Log the request id on failure. Capture ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) for support and correlation.

FAQs

Why wait on EKS operations instead of assuming they finished?

Cluster, node group, and add-on operations are asynchronous and take minutes. A returned create call only means "accepted." Use the *_active waiters so you act on a ready resource, not a pending one.

Can I skip Kubernetes versions when upgrading?

No. EKS control-plane upgrades are one minor version at a time (for example 1.29 to 1.30). Stay current enough that you can always hop a single version.

Should I upgrade add-ons when I upgrade the cluster?

Yes. After a control-plane version bump, update vpc-cni, coredns, and kube-proxy to a compatible build via DescribeAddonVersions and UpdateAddon, or you risk incompatibility.

Do I set desiredSize on a node group?

Only if no autoscaler manages the group. With Cluster Autoscaler or Karpenter running, set minSize and maxSize and let the controller own desiredSize to avoid a tug-of-war.

Why IRSA instead of the node role for pod credentials?

The node role is shared by every pod on the node, which violates least privilege. IRSA gives each service account its own scoped, short-lived role so a compromise is contained.

How many OIDC providers do I need?

One per cluster. Register the cluster's issuer once with CreateOpenIDConnectProvider; every IRSA role reuses it, differing only in the trust policy's sub condition.

Should I still use the aws-auth ConfigMap?

Prefer access entries. They put access decisions on the EKS SDK, avoid the fragile ConfigMap, and support least-privilege access policies. Migrate existing mappings and move to authenticationMode: API.

Which access policy should most principals get?

The least-privilege one that still works - typically AmazonEKSEditPolicy or AmazonEKSViewPolicy scoped to specific namespaces, not cluster-wide AmazonEKSClusterAdminPolicy.

How do I keep the API server from being publicly reachable?

Enable endpointPrivateAccess, and if public access is needed, restrict publicAccessCidrs to known ranges rather than leaving it open to the internet.

What is the biggest hidden EKS cost?

Idle control planes. A cluster bills per hour even with no workloads, so ephemeral and test clusters left running are a common surprise. Tear them down and sweep by tag and age.

Should I write my own retry logic for EKS calls?

Usually no. Both SDKs retry throttling and transient errors with backoff. Tune retry mode and max attempts instead of reimplementing it.

What is the safe order to delete a cluster?

Remove node groups, Fargate profiles, and add-ons first (waiting on their deletion), then call DeleteCluster. It fails while dependents exist.

EKS via SDK Basics - the create-and-wait patterns group A formalizes.
Managed Node Groups & Fargate Profiles - the capacity sizing behind group C.
IAM Roles for Service Accounts (IRSA) - the IRSA-first design in group D.
EKS Access Entries & aws-auth Migration - the access-entry rules in group E.

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

Walk this list once now, then use it as a review checklist before shipping any code that provisions, scales, or secures a cluster.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: async correctness and upgrades first, then capacity, access, and cost.
Check the boxes against your own code as a quick audit.
Revisit whenever you add a new cluster workflow or move code to a new account or region.

A - Async Operations & Reliability

Wait on every async operation. Use cluster_active, nodegroup_active, and addon_active waiters (or waitUntilClusterActive and friends) rather than assuming a create returned means ready.
Order teardown correctly. Delete node groups, Fargate profiles, and add-ons before the cluster; DeleteCluster fails while they exist, and waiting on nodegroup_deleted avoids the race.
Poll updates by id, not by guess. Async updates return an update id; check DescribeUpdate for Successful/Failed instead of sleeping a fixed time.
Rely on built-in retries. Both SDKs retry throttling and transient errors with backoff; tune max_attempts rather than reimplementing retries.

Wait for the cluster instead of guessing it finished.

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

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

B - Version & Upgrade Cadence

Upgrade one minor version at a time. EKS supports single-step control-plane upgrades (1.29 -> 1.30); skipping versions is not allowed, so stay current enough to hop one at a time.
Stay on a supported version. Kubernetes minors leave standard support on a schedule; falling behind risks forced upgrades and extended-support charges.
Upgrade add-ons alongside the control plane. After a version bump, update vpc-cni, coredns, and kube-proxy to a compatible build via DescribeAddonVersions + UpdateAddon.
Roll node groups after the control plane. Bring workers to the new version with UpdateNodegroupVersion, which drains gradually; the control plane can lead nodes by one minor, not more.
Test upgrades in non-prod first. Run the same SDK upgrade path against a staging cluster before production.

Update the control plane, then bring add-ons to a compatible version.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
eks.update_cluster_version(name="platform", version="1.30")
eks.get_waiter("cluster_active").wait(name="platform")
eks.update_addon(clusterName="platform", addonName="vpc-cni",
                 addonVersion="v1.18.1-eksbuild.3", resolveConflicts="PRESERVE")

// --- TypeScript (AWS SDK v3) ---
import {
  EKSClient, UpdateClusterVersionCommand, UpdateAddonCommand, waitUntilClusterActive,
} from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new UpdateClusterVersionCommand({ name: "platform", version: "1.30" }));
await waitUntilClusterActive({ client: eks, maxWaitTime: 1800 }, { name: "platform" });
await eks.send(new UpdateAddonCommand({
  clusterName: "platform", addonName: "vpc-cni",
  addonVersion: "v1.18.1-eksbuild.3", resolveConflicts: "PRESERVE",
}));

C - Node Groups & Capacity

Set a sensible min and max. scalingConfig bounds protect you from both starvation and runaway cost; pick a max you are willing to pay for.
Let an autoscaler own desiredSize. With Cluster Autoscaler or Karpenter running, do not set desiredSize by hand - it fights the controller.
Spread subnets across AZs. List subnets in multiple Availability Zones on the node group so a single-AZ event does not take the tier down.
Use Spot for interruptible tiers. Set capacityType: SPOT for batch, CI, and stateless workloads to cut cost, with interruption handling in place.
Prefer managed node groups or Fargate over self-managed. Let EKS handle bootstrap, health, and upgrades unless you truly need custom node config.

D - Pod Access: IRSA First

Give pods AWS access with IRSA, not the node role. A per-service-account role scopes credentials to one workload instead of sharing the node's broad role.
Register the OIDC provider once per cluster. All IRSA roles reuse a single CreateOpenIDConnectProvider registration of the cluster issuer.
Pin the trust policy to one service account. Use StringEquals on sub (system:serviceaccount:ns:name) and aud = sts.amazonaws.com; never a wildcard.
One narrow role per workload. Roles are free; a role per service account keeps least privilege instead of a shared god-role.
Consider EKS Pod Identity for scale. For many clusters, CreatePodIdentityAssociation avoids per-cluster OIDC and per-role trust wiring and is easier to automate.

Read the issuer, register it once, then reuse it for every IRSA role.

# --- Python (boto3) ---
import boto3
 
eks = boto3.client("eks", region_name="us-east-1")
issuer = eks.describe_cluster(name="platform")["cluster"]["identity"]["oidc"]["issuer"]
 
iam = boto3.client("iam")
iam.create_open_id_connect_provider(
    Url=issuer,
    ClientIDList=["sts.amazonaws.com"],
    ThumbprintList=["9e99a48a9960b14926bb7f3b02e22da2b0ab7280"],
)

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, DescribeClusterCommand } from "@aws-sdk/client-eks";
import { IAMClient, CreateOpenIDConnectProviderCommand } from "@aws-sdk/client-iam";
 
const eks = new EKSClient({ region: "us-east-1" });
const issuer = (await eks.send(new DescribeClusterCommand({ name: "platform" })))
  .cluster?.identity?.oidc?.issuer;
 
const iam = new IAMClient({});
await iam.send(new CreateOpenIDConnectProviderCommand({
  Url: issuer,
  ClientIDList: ["sts.amazonaws.com"],
  ThumbprintList: ["9e99a48a9960b14926bb7f3b02e22da2b0ab7280"],
}));

E - Human Access & Security

Use access entries, not aws-auth. Manage cluster access from the EKS SDK with CreateAccessEntry + AssociateAccessPolicy instead of the fragile, kubectl-edited ConfigMap.
Move clusters to authenticationMode API. Once every mapping is an access entry, switch off CONFIG_MAP so aws-auth cannot silently grant access - remembering the switch is one-way.
Grant least-privilege access policies. Prefer AmazonEKSEditPolicy or AmazonEKSViewPolicy scoped to namespaces over cluster-wide AmazonEKSClusterAdminPolicy.
Scope endpoints deliberately. Enable endpointPrivateAccess and restrict publicAccessCidrs so the API server is not reachable from anywhere.
Enable control-plane logging and encrypt secrets. Turn on the relevant logging types and use a KMS key for envelope encryption of Kubernetes secrets.

F - Cost & Cleanup

Tear down idle clusters. A control plane bills per hour whether or not it runs workloads; delete test and ephemeral clusters promptly.
Right-size before scaling out. Pick instance types that fit the workload; oversized nodes are the most common EKS waste.
Sweep for orphans. List clusters, node groups, and Fargate profiles by tag and age, and clean up anything past its purpose.
Tag clusters and node groups. A consistent tag schema (Environment, Owner, Cost-Center) makes cost allocation and cleanup possible.
Log the request id on failure. Capture ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) for support and correlation.

FAQs

Why wait on EKS operations instead of assuming they finished?

Can I skip Kubernetes versions when upgrading?

No. EKS control-plane upgrades are one minor version at a time (for example 1.29 to 1.30). Stay current enough that you can always hop a single version.

Should I upgrade add-ons when I upgrade the cluster?

Yes. After a control-plane version bump, update vpc-cni, coredns, and kube-proxy to a compatible build via DescribeAddonVersions and UpdateAddon, or you risk incompatibility.

Do I set desiredSize on a node group?

Only if no autoscaler manages the group. With Cluster Autoscaler or Karpenter running, set minSize and maxSize and let the controller own desiredSize to avoid a tug-of-war.

Why IRSA instead of the node role for pod credentials?

The node role is shared by every pod on the node, which violates least privilege. IRSA gives each service account its own scoped, short-lived role so a compromise is contained.

How many OIDC providers do I need?

One per cluster. Register the cluster's issuer once with CreateOpenIDConnectProvider; every IRSA role reuses it, differing only in the trust policy's sub condition.

Should I still use the aws-auth ConfigMap?

Which access policy should most principals get?

The least-privilege one that still works - typically AmazonEKSEditPolicy or AmazonEKSViewPolicy scoped to specific namespaces, not cluster-wide AmazonEKSClusterAdminPolicy.

How do I keep the API server from being publicly reachable?

Enable endpointPrivateAccess, and if public access is needed, restrict publicAccessCidrs to known ranges rather than leaving it open to the internet.

What is the biggest hidden EKS cost?

Idle control planes. A cluster bills per hour even with no workloads, so ephemeral and test clusters left running are a common surprise. Tear them down and sweep by tag and age.

Should I write my own retry logic for EKS calls?

Usually no. Both SDKs retry throttling and transient errors with backoff. Tune retry mode and max attempts instead of reimplementing it.

What is the safe order to delete a cluster?

Remove node groups, Fargate profiles, and add-ons first (waiting on their deletion), then call DeleteCluster. It fails while dependents exist.

EKS via SDK Basics - the create-and-wait patterns group A formalizes.
Managed Node Groups & Fargate Profiles - the capacity sizing behind group C.
IAM Roles for Service Accounts (IRSA) - the IRSA-first design in group D.
EKS Access Entries & aws-auth Migration - the access-entry rules in group E.

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 Best Practices

Buscar en la documentación

EKS via SDK Best Practices