Learn Karpenter - Core Concepts & Main Architecture

#Introduction

In episode 1 you understood why Karpenter exists: replacing the reactive, slow nodegroup model with fast, efficient, and simple provisioning. Now it's time to see how Karpenter works behind the scenes.

This episode breaks down Karpenter's core architecture: the flow from an unscheduled pod to a ready-to-use node, the two key concepts that will stay with us throughout the series — NodePool and NodeClass — as well as the CRD components and labels that form Karpenter's "language".

#How It Works Behind the Scenes

Karpenter runs as a controller inside the cluster. It's not part of the control plane, but a regular deployment you can see in the karpenter namespace. The flow looks like this:

Unscheduled pod (Pending / Unschedulable)
        │
        ▼
Karpenter controller detects the pod
        │
        ▼
Matching NodePool is selected (scheduling & capacity)
        │
        ▼
Cloud provider (AWS) launches the instance
        │
        ▼
Node registers to the cluster, pod gets scheduled

#Step by Step

1. Detection — kube-scheduler fails to place the pod and marks it Unschedulable. The Karpenter controller sees this event via the API server.
2. NodePool selection — Karpenter gathers all queued pods and matches them against the available NodePools. A match means resource requirements, labels, taints, and other constraints are satisfied.
3. Launch — Karpenter calls the cloud provider to launch the most optimal node. On AWS, this is done through mechanisms like CreateFleet, including the Spot option.
4. Registration — the node joins the cluster, kubelet comes up, and the pod gets scheduled. The entire process happens within seconds.

#NodePool and NodeClass

These two concepts are the foundation of all Karpenter configuration. Understanding how their roles are divided will save you from confusion in the upcoming episodes.

#NodePool: Scheduling and Capacity Policy

NodePool answers the question what is allowed to be scheduled. It defines:

• Requirements — instance family, instance size, capacity type (on-demand or Spot), and zones.
• Node template — labels, taints, and kubelet config applied to the node.
• Disruption policy — when a node can be consolidated, when it expires, and its budget.
• Weight — priority when multiple NodePools are equally suitable.

A NodePool points to a NodeClass for infrastructure matters.

#NodeClass: Infrastructure Specification

NodeClass answers the question where and how nodes are created. On AWS, it's EC2NodeClass and defines:

• The AMI and AMI family to use.
• The subnet and security group where instances are launched.
• The instance profile (IAM role) attached to the node.
• userData for bootstrap, and additional tags.

This division lets one NodeClass be used by many NodePools, or one NodePool point to different NodeClasses — a flexible combination for various workload types.

#Main Components and CRDs

Karpenter 1.14.0 works through a set of CustomResourceDefinitions:

• NodePool (karpenter.sh/v1) — scheduling policy, successor to the old provisioner resource.
• EC2NodeClass (karpenter.k8s.aws/v1) — AWS infrastructure specification.
• NodeClaim — representation of a node being processed by Karpenter, from launch until registration.
• Disruption controller — the component that handles consolidation, drift, expiration, and interruption handling.

The v1 API is GA. Since Karpenter 1.1.0, the old v1beta1 API was removed, so all configuration in this series uses the v1 API.

#karpenter.sh Labels and Annotations

When creating nodes, Karpenter attaches labels and annotations that are very useful for operations:

kubectl get nodes -l karpenter.sh/nodepool=default -o wide
kubectl get nodepools
kubectl get nodeclaims

Pay attention to the labels in the output of kubectl get nodes -l karpenter.sh/nodepool=default -o wide — you'll see the instance type, zone, and capacity type Karpenter chose for each node.

#Closing

This episode dissected Karpenter's architecture. Karpenter is an in-cluster controller that detects Unschedulable pods, selects a matching NodePool, then calls the cloud provider to launch the optimal node. The two key concepts you must hold onto are NodePool (scheduling and capacity policy) and NodeClass (infrastructure specification). CRDs like NodeClaim and the disruption controller complete the architecture, while karpenter.sh labels serve as the observability bridge.

Key takeaways:

• Controller architecture — Karpenter runs inside the cluster and reacts to Unschedulable pods.
• NodePool vs NodeClass — scheduling and capacity are separated from infrastructure, giving flexible combinations.
• Four-step flow — detection, pool selection, cloud launch, and node registration.
• v1 API — stable; v1beta1 has been removed since 1.1.0.
• karpenter.sh labels — karpenter.sh/nodepool and karpenter.sh/capacity-type are keys to observability.

In episode 3 we go hands-on: setup and installation. We'll create an EKS cluster from scratch, install the CRDs and Karpenter controller via Helm, build a minimal IAM role, then verify with our first NodePool and EC2NodeClass examples. See you in the next episode!