Learn Karpenter - NodeClass (EC2NodeClass)

#Introduction

In episode 4 you understood how the NodePool determines what is allowed to be scheduled via requirements, disruption, and weight. But a NodePool doesn't work alone — every launched node needs infrastructure configuration: which AMI, which subnet, which security group, and what role is attached. All of that is handled by EC2NodeClass.

This episode dissects EC2NodeClass thoroughly: AMI selection, security groups, subnets, instance profile, userData, additional tags, and how to combine multiple NodeClasses for different workloads.

#What Is an EC2NodeClass

EC2NodeClass is an AWS-owned CRD (karpenter.k8s.aws/v1) that answers the question where and how nodes are created. It contains all the AWS details needed to launch an instance:

apiVersion: karpenter.k8s.aws/v1
kind: EC2NodeClass
metadata:
  name: default
spec:
  amiFamily: AL2023
  role: "KarpenterNodeRole-eks-learn-karpenter"
  subnetSelectorTerms:
    - tags:
        karpenter.sh/discovery: learn-karpenter
  securityGroupSelectorTerms:
    - tags:
        karpenter.sh/discovery: learn-karpenter
  tags:
    Environment: production
    ManagedBy: karpenter
  userData: |
    #!/bin/bash
    sysctl -w fs.inotify.max_user_instances=1024

Each NodePool points to one EC2NodeClass via nodeClassRef. One EC2NodeClass can be used by many NodePools — for example, an on-demand pool and a Spot pool sharing the same infrastructure.

#AMI Selection

Karpenter selects an AMI through two mechanisms: amiFamily and amiSelectorTerms.

#amiFamily

amiFamily provides AMIs that are managed and bootstrapped automatically by Karpenter. Available options:

With amiFamily, Karpenter manages the kubelet bootstrap userData automatically — you just add your custom parts via the userData field.

#amiSelectorTerms

For full control, use amiSelectorTerms. Karpenter searches for AMIs matching an alias or tags. Example using an alias for a Bottlerocket version:

spec:
  amiSelectorTerms:
    - alias: bottlerocket@latest

Selectors can be based on alias, name, id, or tags. Combining amiFamily: Custom with a tag selector is the most common way to use corporate internal AMIs.

#Security Groups and Subnets

Karpenter discovers security groups and subnets via selector terms based on tags. This replaces the need to list IDs one by one.

spec:
  subnetSelectorTerms:
    - tags:
        karpenter.sh/discovery: learn-karpenter
        env: prod
  securityGroupSelectorTerms:
    - tags:
        karpenter.sh/discovery: learn-karpenter

#Multiple Subnets and AZs

A subnet selector can select many subnets at once — this is how Karpenter gains Availability Zone flexibility. During launch, Karpenter picks the AZ and subnet with sufficient capacity:

spec:
  subnetSelectorTerms:
    - tags:
        karpenter.sh/discovery: learn-karpenter
    - tags:
        karpenter.sh/discovery: data-plane

The two selectors above are combined with OR logic: a subnet holding either tag will be selected. The result is nodes spread across several AZs, and resilience to zone outages improves.

#Instance Profile

The role field on an EC2NodeClass points to the instance profile IAM attached to every node. This role is what gives kubelet, CNI, and workloads permission to talk to AWS.

spec:
  role: "KarpenterNodeRole-eks-learn-karpenter"

This role is usually built alongside eksctl or Terraform, and differs from the Karpenter controller role we created in episode 3 — one is for Karpenter's control plane, the other for the nodes.

#userData: Bootstrap and Customization

userData lets you inject scripts or cloud-config at instance boot time, on top of the default userData generated by Karpenter. On Amazon Linux, just use a bash shebang:

spec:
  userData: |
    #!/bin/bash
    echo "EBS-optimized node" > /etc/motd
    sysctl -w fs.inotify.max_user_watches=524288
    systemctl restart kubelet

Karpenter merges custom userData with its default bootstrap automatically. On Bottlerocket, the format uses TOML — make sure you use the format matching the chosen amiFamily.

#Additional Tags

The tags field adds EC2 tags to every instance, volume, and network interface created. This is very useful for cost tagging:

spec:
  tags:
    Environment: production
    Team: platform
    CostCenter: cc-1201

These additional tags appear in AWS billing and make cost reports per team or per environment easier.

#Combining Multiple NodeClasses

The NodePool + EC2NodeClass combination is very flexible. A real-world example: one cluster with three different node profiles.

One default EC2NodeClass can serve two different pools (on-demand and Spot), while GPU workloads use their own NodeClass with Bottlerocket and special tuning. Example NodeClass for the GPU pool:

apiVersion: karpenter.k8s.aws/v1
kind: EC2NodeClass
metadata:
  name: gpu
spec:
  amiFamily: Bottlerocket
  role: "KarpenterNodeRole-eks-learn-karpenter"
  subnetSelectorTerms:
    - tags:
        karpenter.sh/discovery: learn-karpenter
  securityGroupSelectorTerms:
    - tags:
        karpenter.sh/discovery: learn-karpenter
  amiSelectorTerms:
    - alias: bottlerocket@latest
  tags:
    Team: ml

Quick verification: kubectl get ec2nodeclasses for the list, and kubectl describe ec2nodeclass gpu for the details.

#Closing

Episode 5 completes the foundation of Karpenter configuration on AWS. EC2NodeClass handles the infrastructure side: AMI selection via amiFamily and amiSelectorTerms, security groups and subnets via tag selectors, instance profile via the role field, userData for custom bootstrap, and additional tags for cost. Combining several NodeClasses with several NodePools gives full control over the node profiles in a cluster.

Key takeaways:

• amiFamily vs amiSelectorTerms — automatic and managed, or full control with alias or tags.
• Tag selectors — subnets and security groups are discovered via tags, not static IDs.
• Role — the instance profile gives nodes permission, separate from the controller role.
• userData — custom bootstrap is merged automatically with Karpenter's default.
• Composition — one NodeClass can serve many NodePools; special profiles use their own NodeClass.

In episode 6 we'll move into the second phase: provisioning and binpacking. We'll see how Karpenter combines queued pods into the most densely packed and cost-effective instances. See you in the next episode!