Learn Karpenter - Setup & Installation

#Introduction

In episode 2 you understood Karpenter's architecture: a controller that detects Unschedulable pods, selects a NodePool, then launches nodes via the cloud provider. Now it's time for real practice. This episode guides you from zero — creating an EKS cluster, installing the CRDs and Karpenter controller via Helm, building a minimal IAM role, all the way to verification with your first NodePool and EC2NodeClass examples.

Make sure the tools from episode 0 are installed and your AWS credentials are valid. Let's start with cluster creation.

#Creating an EKS Cluster

Karpenter 1.14.0 supports Kubernetes 1.29 to 1.36. Create a cluster with one managed nodegroup that acts as a vended nodegroup — the term for eksctl's built-in nodegroup that delivers a usable cluster before Karpenter takes over. This nodegroup is intentionally kept small and only runs system pods.

eksctl create cluster \
  --name learn-karpenter \
  --version 1.32 \
  --region ap-southeast-1 \
  --nodegroup-name system \
  --node-type m5.large \
  --nodes 1 \
  --nodes-min 1 \
  --nodes-max 1 \
  --managed

The process takes 10-15 minutes. Once finished, make sure the cluster is healthy:

kubectl cluster-info
kubectl get nodes

#Building an IAM Role with a Minimal Policy

Karpenter calls the AWS API to launch and terminate instances. The IAM role for the controller is created on the least-privilege principle and attached via IRSA (IAM Roles for Service Accounts).

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances",
        "ec2:CreateFleet",
        "ec2:TerminateInstances",
        "ec2:DescribeInstances",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeInstanceTypes"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": ["iam:PassRole"],
      "Resource": "arn:aws:iam::ACCOUNT_ID:role/KarpenterNodeRole-*"
    }
  ]
}

Create the policy via the aws CLI, then attach it to the service account:

aws iam create-policy \
  --policy-name KarpenterControllerPolicy \
  --policy-document file://policy.json
 
eksctl create iamserviceaccount \
  --cluster learn-karpenter \
  --namespace karpenter \
  --name karpenter \
  --role-name karpenter-irsa \
  --attach-policy-arn arn:aws:iam::ACCOUNT_ID:policy/KarpenterControllerPolicy \
  --approve

Nodes launched by Karpenter also need an instance profile with a role to communicate with EKS — this role is usually named KarpenterNodeRole-... . In episode 5 we'll see how EC2NodeClass points to this instance profile via the role field.

#Installing the Karpenter CRDs and Controller

The karpenter Helm chart installs the controller along with the NodePool, NodeClaim, and EC2NodeClass CRDs.

helm upgrade --install karpenter oci://ghcr.io/aws/karpenter/charts/karpenter \
  --namespace karpenter \
  --create-namespace \
  --set serviceAccount.annotations."eks\.amazonaws\.com/role-arn"=arn:aws:iam::ACCOUNT_ID:role/karpenter-irsa \
  --set controller.resources.requests.cpu=1 \
  --set controller.resources.requests.memory=1Gi \
  --version 1.14.0

Verify the controller and CRDs:

kubectl get pods -n karpenter
kubectl get crd nodepools.karpenter.sh
kubectl get crd nodeclaims.karpenter.sh
kubectl get crd ec2nodeclasses.karpenter.k8s.aws

A healthy controller is marked by pods in Running status. To confirm the version, check the image section on the deployment kubectl get deployment -n karpenter karpenter -o yaml — it should be tagged 1.14.0.

#Setting Up Tag Discovery for Subnet and Security Group

Before creating Karpenter resources, make sure the subnet and security group can be "discovered" by Karpenter. The most common method is tag discovery:

aws ec2 create-tags \
  --resources SUBNET_ID SECURITY_GROUP_ID \
  --tags Key=karpenter.sh/discovery,Value=learn-karpenter

Replace SUBNET_ID and SECURITY_GROUP_ID with the values in your cluster. This is how Karpenter learns which subnets and security groups it's allowed to use — we'll study the selector details in episode 5.

#Minimal NodePool and EC2NodeClass Examples

Now define your first two resources. The EC2NodeClass first, because the NodePool points to it.

apiVersion: karpenter.k8s.aws/v1
kind: EC2NodeClass
metadata:
  name: default
spec:
  amiFamily: AL2
  role: "KarpenterNodeRole-eks-learn-karpenter"
  subnetSelectorTerms:
    - tags:
        karpenter.sh/discovery: learn-karpenter
  securityGroupSelectorTerms:
    - tags:
        karpenter.sh/discovery: learn-karpenter

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: default
spec:
  template:
    spec:
      nodeClassRef:
        group: karpenter.k8s.aws
        kind: EC2NodeClass
        name: default
      requirements:
        - key: karpenter.sh/capacity-type
          operator: In
          values: ["on-demand"]
  disruption:
    consolidationPolicy: WhenUnderutilized
    expireAfter: 720h

Apply both:

kubectl apply -f ec2nodeclass.yaml
kubectl apply -f nodepool.yaml
kubectl get nodepools

Notice the YAML structure: the NodePool points to the EC2NodeClass via nodeClassRef, while the capacity-type requirement is set to on-demand. We'll dissect the full NodePool structure in episode 4.

#Verifying with a Test Workload

Now prove that Karpenter works. Deploy a workload that doesn't fit on the system nodegroup, then observe:

kubectl create deployment nginx --image=nginx --replicas=3
kubectl get pods -o wide
kubectl get nodeclaims

If everything is correct, Karpenter will create a NodeClaim, launch a new instance, and the nginx pods will be scheduled onto that node. The label karpenter.sh/nodepool=default will appear on the new node — check with kubectl get nodes -l karpenter.sh/nodepool=default -o wide.

#Closing

Episode 3 guided you from zero until Karpenter actually provisions nodes. You created an EKS cluster, built a minimal IAM role, installed the CRDs and controller via Helm, set up tag discovery, then applied your first NodePool and EC2NodeClass, which were immediately tested with an nginx deployment.

Key takeaways:

• Vended nodegroup — one system nodegroup is enough to deliver the cluster before Karpenter takes over.
• Least privilege — a minimal IAM role via IRSA, never storing access keys in the cluster.
• Tag discovery — subnets and security groups must be tagged so Karpenter can find them.
• Two key resources — the NodePool points to the EC2NodeClass via nodeClassRef, and capacity-type is set in requirements.
• Verification — nodeclaims appear and the new node carries the karpenter.sh/nodepool label.

In episode 4 we break down NodePool and scheduling: the spec.template structure, requirements, disruption, weight, and how Karpenter matches pods with pools — including the karpenter.sh labels and annotations attached to nodes. See you in the next episode!