Skip to main content
Karpenter uses NodeClaims to manage the lifecycle of Kubernetes nodes with the underlying cloud provider. Karpenter creates and deletes NodeClaims in response to pending pods, evaluates their requirements against available NodePools and NodeClasses, and creates a NodeClaim that satisfies both sets of constraints. NodeClaims are immutable resources managed by Karpenter. You can monitor them to track node status. In addition to tracking node lifecycle, NodeClaims serve as capacity requests. Karpenter creates NodeClaims for both provisioning new capacity and pre-spinning replacements during disruption.

​
NodeClaim lifecycle

Each NodeClaim progresses through four phases:
1

Launched

Karpenter finds the new NodeClaim and calls the cloud provider API to create an instance. If the API returns an unrecoverable error (such as InsufficientCapacityError), Karpenter deletes the NodeClaim, marks that instance type as temporarily unavailable, and creates another NodeClaim if necessary.
{
  "level": "INFO",
  "message": "launched nodeclaim",
  "controller": "nodeclaim.lifecycle",
  "NodeClaim": { "name": "default-sfpsl" },
  "provider-id": "aws:///us-west-2b/i-01234567adb205c7e",
  "instance-type": "c3.2xlarge",
  "zone": "us-west-2b",
  "capacity-type": "spot"
}
2

Registered

Karpenter watches for the instance to register itself as a Kubernetes node and updates the node’s labels, annotations, taints, owner references, and finalizer to match the NodePool and NodeClaim spec. Karpenter removes the karpenter.sh/unregistered taint once registration is complete.If registration doesn’t complete within 15 minutes, Karpenter deletes the NodeClaim and underlying instance.
{
  "level": "INFO",
  "message": "registered nodeclaim",
  "controller": "nodeclaim.lifecycle",
  "NodeClaim": { "name": "default-sfpsl" },
  "Node": { "name": "ip-xxx-xxx-xx-xxx.us-west-2.compute.internal" }
}
3

Initialized

Karpenter watches the node until it becomes ready, all startup taints are removed, and all requested resources are registered.
{
  "level": "INFO",
  "message": "initialized nodeclaim",
  "controller": "nodeclaim.lifecycle",
  "NodeClaim": { "name": "default-sfpsl" },
  "allocatable": {
    "cpu": "7910m",
    "memory": "13215Mi",
    "pods": "58"
  }
}
4

Ready

The node is fully initialized and the NodeClaim’s Ready condition is set to True. Pods can now schedule to the node.

​
How Karpenter creates NodeClaims

  1. Watches for provisionable pods — monitors pending pods and checks their scheduling constraints and resource requests against available NodePools and NodeClasses. 
    {
  "level": "INFO",
  "message": "found provisionable pod(s)",
  "Pods": "default/inflate-66fb68585c-xvs86, ...",
  "duration": "100.761702ms"
}
  2. Computes NodeClaim shape — determines the right instance type and size to fit the set of pods. 
    {
  "level": "INFO",
  "message": "computed new nodeclaim(s) to fit pod(s)",
  "controller": "provisioner",
  "nodeclaims": 1,
  "pods": 5
}
  3. Creates the NodeClaim object — commits the NodeClaim to the cluster. 
    {
  "level": "INFO",
  "message": "created nodeclaim",
  "controller": "provisioner",
  "NodePool": { "name": "default" },
  "NodeClaim": { "name": "default-sfpsl" },
  "requests": { "cpu": "5150m", "pods": "8" },
  "instance-types": "c3.2xlarge, c4.2xlarge, c5.2xlarge and 55 other(s)"
}
  4. Launches the instance — translates the NodeClaim into a cloud provider API call.
  5. Registers and initializes — waits for the node to join the cluster and become ready.

​
Inspecting NodeClaims

List all NodeClaims and their linked nodes: 
kubectl get nodeclaims
Example output: 
NAME            TYPE               ZONE         NODE                                           READY   AGE
default-m6pzn   c7i-flex.2xlarge   us-west-1a   ip-xxx-xxx-xx-xxx.us-west-1.compute.internal   True    7m50s
Describe a specific NodeClaim: 
kubectl describe nodeclaim default-m6pzn
Watch Karpenter logs: 
export KARPENTER_NAMESPACE="kube-system"
kubectl logs -f -n "${KARPENTER_NAMESPACE}" \
   -l app.kubernetes.io/name=karpenter

​
NodeClaim example

The following is an example of a NodeClaim in a running cluster. 
Name:         default-x9wxq
Labels:       karpenter.k8s.aws/instance-category=c
              karpenter.k8s.aws/instance-cpu=8
              karpenter.k8s.aws/instance-family=c5a
              karpenter.k8s.aws/instance-generation=5
              karpenter.k8s.aws/instance-hypervisor=nitro
              karpenter.k8s.aws/instance-memory=16384
              karpenter.sh/capacity-type=spot
              karpenter.sh/nodepool=default
              kubernetes.io/arch=amd64
              kubernetes.io/os=linux
              node.kubernetes.io/instance-type=c5a.2xlarge
              topology.kubernetes.io/zone=us-west-2c
API Version:  karpenter.sh/v1
Kind:         NodeClaim
Metadata:
  Finalizers:
    karpenter.sh/termination
  Owner References:
    Kind:   NodePool
    Name:   default
Spec:
  Expire After:  720h0m0s
  Node Class Ref:
    Kind:   EC2NodeClass
    Name:   default
  Requirements:
    Key: kubernetes.io/arch, Operator: In, Values: [amd64]
    Key: karpenter.sh/capacity-type, Operator: In, Values: [spot]
    Key: karpenter.k8s.aws/instance-category, Operator: In, Values: [c, m, r]
  Resources:
    Requests:
      Cpu:   3150m
      Pods:  6
  Termination Grace Period:  1h0m0s
Status:
  Allocatable:
    Cpu:     7910m
    Memory:  14162Mi
    Pods:    58
  Conditions:
    Type: Launched,     Status: True
    Type: Registered,   Status: True
    Type: Initialized,  Status: True
    Type: Ready,        Status: True
  Node Name:   ip-xxx-xxx-xxx-xxx.us-west-2.compute.internal
  Provider ID: aws:///us-west-2c/i-01234567890123
  Image ID:    ami-08946d4d49fc3f27b

​
Status conditions

ConditionDescription
LaunchedThe cloud provider instance was successfully created
RegisteredThe node registered with the Kubernetes API server
InitializedThe node is ready and all resources are available
ReadyThe NodeClaim is fully operational
ConsolidatableThe node is eligible for consolidation
DriftedThe node has drifted from its NodePool or EC2NodeClass spec
If a node is NotReady, check the NodeClaim conditions to determine which phase failed. Karpenter also emits logs at each lifecycle stage to aid troubleshooting.

Build docs developers (and LLMs) love

Get started for freeTalk to us