What the EKS SDK Actually Manages

Amazon EKS runs the Kubernetes control plane for you. The EKS SDK is how your code creates and operates that AWS-managed piece - but it stops at a hard boundary that trips up almost everyone new to it.

This page draws that boundary clearly, so every other page in this section reads as "which side of the line is this operation on?"

Summary

• The EKS SDK (@aws-sdk/client-eks, boto3 eks) manages the AWS-facing shell of a Kubernetes cluster: the managed control plane, managed node groups, Fargate profiles, add-ons, access entries, and the IAM/OIDC plumbing.
• Insight: it does not manage anything inside Kubernetes. Deployments, Pods, Services, ConfigMaps, and Secrets live behind the Kubernetes API server and are reached with kubectl or a Kubernetes client, never the AWS SDK.
• Key Concepts: control plane, data plane, cluster endpoint, kubeconfig, OIDC issuer, access entry.
• When to Use: provisioning a cluster, scaling worker capacity, installing AWS-owned add-ons, and granting AWS principals access - all from application or platform code.
• Limitations/Trade-offs: the SDK is imperative and AWS-scoped; declaring desired cluster state is a job for IaC, and deploying apps is a job for the Kubernetes API.
• Related Topics: node groups and Fargate, IRSA, access entries, and add-on management.

Foundations

A Kubernetes cluster has two halves. The control plane is the brain: the API server, etcd, the scheduler, and the controllers. The data plane is the muscle: the worker nodes that actually run your containers.

With self-managed Kubernetes you own both halves. With EKS, AWS runs the control plane as a managed service across multiple Availability Zones, patches it, and scales it. You never SSH into it. You reach it only through its Kubernetes API endpoint.

The EKS SDK is the API for the AWS envelope around that control plane. It answers questions like "does a cluster exist," "what version is it," "how many worker nodes, and of what type," "which AWS add-ons are installed," and "which AWS principals may talk to the cluster." It does not answer "what is deployed on the cluster."

Here is the single call that creates the whole managed control plane.

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

// --- TypeScript (AWS SDK v3) ---
import { EKSClient, CreateClusterCommand } from "@aws-sdk/client-eks";
 
const eks = new EKSClient({ region: "us-east-1" });
const resp = 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,
  },
}));
console.log(resp.cluster?.status);   // CREATING

Notice the inputs: an IAM role, a Kubernetes version, and VPC networking. Every parameter is about the AWS environment the control plane lives in. Nothing here describes a workload.

Mechanics & Interactions

CreateCluster returns almost immediately with status: CREATING, but the control plane takes several minutes to become reachable. That gap is why the SDK ships waiters: cluster_active in boto3, waitUntilClusterActive in SDK v3. You call the create, then block on the waiter until the status flips to ACTIVE.

# --- Python (boto3) ---
eks.get_waiter("cluster_active").wait(name="platform")
info = eks.describe_cluster(name="platform")["cluster"]
print(info["endpoint"])                       # https://XXXX.gr7.us-east-1.eks.amazonaws.com
print(info["identity"]["oidc"]["issuer"])     # OIDC issuer URL for IRSA

// --- TypeScript (AWS SDK v3) ---
import { waitUntilClusterActive, DescribeClusterCommand } from "@aws-sdk/client-eks";
 
await waitUntilClusterActive({ client: eks, maxWaitTime: 900 }, { name: "platform" });
const info = (await eks.send(new DescribeClusterCommand({ name: "platform" }))).cluster;
console.log(info?.endpoint);                   // https://XXXX.gr7.us-east-1.eks.amazonaws.com
console.log(info?.identity?.oidc?.issuer);     // OIDC issuer URL for IRSA

DescribeCluster is the bridge between the two planes. It hands back three things you need to cross the boundary: the API endpoint, the base64 certificateAuthority.data, and the identity.oidc.issuer. The first two build a kubeconfig so kubectl can authenticate to the cluster; the third is the trust anchor for IRSA (covered on its own page).

This is the crucial mental picture. The SDK gets you to the front door - it provisions the cluster and tells you its address - but walking through the door to create a Deployment means switching tools to kubectl or a Kubernetes client library. That handoff usually looks like this, and note it is a plain shell snippet, not an SDK call:

# Build a kubeconfig entry from the cluster the SDK just created,
# then everything past this line is the Kubernetes API, not AWS.
aws eks update-kubeconfig --name platform --region us-east-1
kubectl apply -f deployment.yaml   # this NEVER goes through the EKS SDK

Advanced Considerations & Applications

Where exactly does the line fall? A short inventory settles most questions.

A handful of operations straddle the line, which is where confusion peaks. Access entries are set with the EKS SDK but govern who can call the Kubernetes API - AWS-side configuration of a Kubernetes-side permission. Add-ons are installed with the SDK but result in real Pods (like the CNI DaemonSet) running in the data plane. IRSA is set up partly with the IAM SDK (an OIDC provider and a role) and partly with kubectl (annotating a service account). Each of these gets its own page precisely because it lives on the seam.

The practical rule: if the thing you want to change would still exist if you deleted every workload - the cluster itself, its nodes, its add-ons, its access list - the EKS SDK owns it. If it only exists because you deployed it, the Kubernetes API owns it, and the AWS SDK cannot see it.

Common Misconceptions

• "I can deploy my app with the EKS SDK." - No. There is no CreateDeployment in @aws-sdk/client-eks. Workloads go through the Kubernetes API via kubectl or a client library.
• "CreateCluster gives me a ready cluster." - It returns CREATING; the control plane needs several minutes. Wait on cluster_active / waitUntilClusterActive before using it.
• "The EKS SDK manages my nodes' operating system." - It manages the node group (count, type, AMI family, scaling), but what runs inside each node is Kubernetes' job.
• "aws-auth ConfigMap edits are an SDK call." - Historically that ConfigMap was edited with kubectl. Access entries moved that concern onto the EKS SDK, but the legacy path was pure Kubernetes.
• "One tool does everything." - EKS deliberately splits AWS concerns (SDK) from cluster concerns (kubectl). Expect to use both.

FAQs

Related

• EKS via SDK Basics - create a cluster and a node group hands-on in both SDKs.
• Managed Node Groups & Fargate Profiles - the two ways to provide worker capacity.
• IAM Roles for Service Accounts (IRSA) - how the OIDC issuer bridges pods to IAM roles.
• EKS Access Entries & aws-auth Migration - the access operation that straddles the boundary.

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