Search across all documentation pages
A cluster with no worker capacity can schedule nothing. EKS gives you two ways to provide that capacity, and both are created through the EKS SDK: managed node groups (EC2 instances EKS runs for you) and Fargate profiles (serverless capacity billed per pod).
This page shows how to create and operate each, and when to reach for which. Which pods actually land on the capacity is still the Kubernetes scheduler's call - the SDK only provisions the capacity.
A managed node group is a set of EC2 instances that EKS provisions, bootstraps, joins to the cluster, and later upgrades on your behalf. CreateNodegroup needs the node IAM 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": 6, "desiredSize": 3},
instanceTypes=["t3.large"],
amiType="AL2023_x86_64_STANDARD",
capacityType="ON_DEMAND",
labels={"role": "general"},
)// --- 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: 6, desiredSize: 3 },
instanceTypes: ["t3.large"],
amiType: "AL2023_x86_64_STANDARD",
capacityType: "ON_DEMAND",
labels: { role: "general" },
}));The labels become Kubernetes node labels, so workloads can target this group with a node selector. amiType picks the managed AMI family (Amazon Linux 2023, Bottlerocket, or a GPU variant), and EKS keeps that AMI patched when you trigger an upgrade.
Capacity needs change. UpdateNodegroupConfig resizes a group without recreating it, and UpdateNodegroupVersion rolls the AMI to a newer Kubernetes or AMI release, replacing instances gradually.
# --- Python (boto3) ---
import boto3
eks = boto3.client("eks", region_name="us-east-1")
# Resize the group in place.
eks.update_nodegroup_config(
clusterName="platform",
nodegroupName="general",
scalingConfig={"minSize": 3, "maxSize": 10, "desiredSize": 4},
)
# Roll the AMI/K8s version with a gradual, health-aware replacement.
eks.update_nodegroup_version(
clusterName="platform",
nodegroupName="general",
version="1.30",
)// --- TypeScript (AWS SDK v3) ---
import {
EKSClient, UpdateNodegroupConfigCommand, UpdateNodegroupVersionCommand,
} from "@aws-sdk/client-eks";
const eks = new EKSClient({ region: "us-east-1" });
// Resize the group in place.
await eks.send(new UpdateNodegroupConfigCommand({
clusterName: "platform",
nodegroupName: "general",
scalingConfig: { minSize: 3, maxSize: 10, desiredSize: 4 },
}));
// Roll the AMI/K8s version with a gradual, health-aware replacement.
await eks.send(new UpdateNodegroupVersionCommand({
clusterName: "platform",
nodegroupName: "general",
version: "1.30",
}));An update returns an update id and runs asynchronously. UpdateNodegroupVersion cordons and drains old nodes and brings up replacements while respecting a maximum-unavailable setting, so a version bump does not take the whole group down at once. desiredSize is a starting point - if you run the Kubernetes Cluster Autoscaler or Karpenter, that controller adjusts the desired count within the min/max you set here.
A Fargate profile is the serverless alternative: instead of you running EC2 nodes, AWS runs each matching pod on right-sized, isolated capacity and bills per pod. You do not manage or scale nodes at all. The trade-off is per-pod pricing and some feature limits (no DaemonSets, no privileged pods, no host networking).
A profile is a selector: it says "pods in these namespaces, optionally with these labels, run on Fargate." CreateFargateProfile needs a pod execution role and private subnets.
# --- Python (boto3) ---
import boto3
eks = boto3.client("eks", region_name="us-east-1")
eks.create_fargate_profile(
clusterName="platform",
fargateProfileName="serverless-apps",
podExecutionRoleArn="arn:aws:iam::111122223333:role/eksFargatePodRole",
subnets=["subnet-0priv1", "subnet-0priv2"], # private subnets only
selectors=[
{"namespace": "web", "labels": {"compute": "fargate"}},
{"namespace": "batch"},
],
)// --- TypeScript (AWS SDK v3) ---
import { EKSClient, CreateFargateProfileCommand } from "@aws-sdk/client-eks";
const eks = new EKSClient({ region: "us-east-1" });
await eks.send(new CreateFargateProfileCommand({
clusterName: "platform",
fargateProfileName: "serverless-apps",
podExecutionRoleArn: "arn:aws:iam::111122223333:role/eksFargatePodRole",
subnets: ["subnet-0priv1", "subnet-0priv2"], // private subnets only
selectors: [
{ namespace: "web", labels: { compute: "fargate" } },
{ namespace: "batch" },
],
}));A pod matches the profile if its namespace matches and, when labels are given, all of those labels match. A pod in web with compute: fargate runs on Fargate; a pod in batch runs on Fargate regardless of labels; anything not matching any profile falls to your node groups. The pod execution role is what the Fargate infrastructure uses to pull images and write logs, and it must trust eks-fargate-pods.amazonaws.com.
Node groups win when you need DaemonSets (log/metric agents, the CNI), GPU or specialized instances, control over bin-packing, or the lowest cost at steady high utilization. Fargate wins for spiky or bursty workloads, strong per-pod isolation, and eliminating node operations entirely. Many clusters run both: node groups for the system add-ons and steady tier, Fargate profiles for isolated or bursty namespaces.
CreateFargateProfile rejects public subnets. Provide subnets with a route to a NAT gateway, not an internet gateway.ec2.amazonaws.com); a Fargate profile takes a pod execution role (trusts eks-fargate-pods.amazonaws.com). Swapping them fails.desiredSize by hand can cause a tug-of-war. Let the autoscaler own it within min/max.nodegroup_deleted before deleting the cluster.desiredSize by hand.Reach for node groups when you want control and steady-state cost efficiency, Fargate when you want to stop managing nodes, and a controller like Karpenter or Cluster Autoscaler when capacity should track demand automatically.
A set of EC2 worker instances that EKS provisions, bootstraps, joins to the cluster, and upgrades for you. You create it with CreateNodegroup and resize it with UpdateNodegroupConfig.
Call UpdateNodegroupConfig with a new scalingConfig (minSize, maxSize, desiredSize). It changes the group in place without recreating it.
Use UpdateNodegroupVersion. It cordons and drains old nodes and brings up replacements gradually, honoring a maximum-unavailable setting.
A selector that routes matching pods (by namespace and optional labels) to serverless Fargate capacity billed per pod, so you run no EC2 nodes for those pods. Create it with CreateFargateProfile.
Fargate profiles require private subnets. A subnet with a route to an internet gateway (a public subnet) is rejected; use subnets routed through a NAT gateway.
A pod execution role that trusts eks-fargate-pods.amazonaws.com and can pull images and write logs. It is different from the EC2 node role a node group uses.
No. Each Fargate pod runs in its own isolated micro-VM with no shared node, so per-node DaemonSets do not apply. Use sidecars, or run those workloads on node groups.
It is scheduled onto your managed or self-managed node groups like a normal pod. Fargate only claims pods that match a profile's selectors.
Let the autoscaler own the desired count within the min/max you set. Manually setting desiredSize can conflict with the controller and cause thrashing.
Yes, and many do. A common split is node groups for system add-ons and steady workloads, plus Fargate profiles for bursty or strongly isolated namespaces.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Reviewed by Chris St. John·Last updated Jul 23, 2026