Karpenter Issues

Karpenter is a Kubernetes node provisioning controller.

The purpose of Karpenter is to dynamically create and remove Kubernetes nodes in response to workload demand. Instead of scaling fixed node groups, Karpenter observes pods that cannot be placed and provisions nodes that are an exact fit for those pods.

This guide is intended for application developers and platform users who are not Kubernetes or cloud infrastructure experts.

Quick Troubleshooting Checklist

If you just want a fast checklist without detailed explanations, follow these steps in order:

1. Describe the pod

   kubectl describe pod <pod-name> -n <namespace>

   • Look for explicit Karpenter errors or capacity messages

2. Check NodeClaims

   kubectl get nodeclaims

   • No NodeClaims → Karpenter is not attempting to create capacity
   • NodeClaims exist but nodes are NotReady → node startup / networking issue

3. Check node readiness

   kubectl get nodes

   • Nodes stuck NotReady usually indicate CNI or node-level issues

4. If only one workload is affected

   • Check resource requests, selectors, affinities, and tolerations

5. If many workloads are affected

   • Check the Karpenter controller and logs

6. If nodes are actively launching

   • Wait a few minutes before intervening

If these steps do not identify the issue, collect the escalation information listed in When to Escalate.

Deep Dive Topics

• Concepts - How Karpenter works, architecture, what it controls
• Workload Design - Designing workloads for spot and high-churn environments
• When to Escalate - Corrective actions and escalation criteria