# kubernetes-sigs/karpenter architecture

> Architecture diagram of the GitHub repository kubernetes-sigs/karpenter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/karpenter
- Repository: https://github.com/kubernetes-sigs/karpenter

## Overview

Karpenter is Kubernetes cluster autoscaling software: it observes unschedulable workloads, evaluates placement constraints, provisions suitable nodes, and later removes unnecessary or out-of-date capacity. The graph covers the primary provisioning and node lifecycle, plus disruption, capacity buffers, dynamic resource allocation, overlays, and static NodePools. Controller wiring is sampled only in part; unsampled subsystem links are included only where the README or named runtime components support the capability, and uncertain call-level wiring is omitted.

Main entry points: [`pkg/controllers/provisioning/provisioner.go`](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/provisioning/provisioner.go) (Provisioner), [`pkg/controllers/state/cluster.go`](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/state/cluster.go) (Cluster state), [`pkg/cloudprovider/types.go`](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/cloudprovider/types.go) (Cloud provider), [`pkg/controllers/node/termination/controller.go`](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/node/termination/controller.go) (Node termination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provision["Provisioning"]
  node_podtrigger["Pod trigger<br/>[controller.go]"]
  node_provisioner["Provisioner<br/>[provisioner.go]"]
  node_scheduler["Constraint scheduler<br/>[scheduler.go]"]
  node_scheduling["Scheduling rules<br/>[requirements.go]"]
  node_nodeclaimapi["NodeClaim and NodePool<br/>[nodeclaim.go]"]
  node_cloudprovider["Cloud provider<br/>[types.go]"]
  node_dra[("Device allocation<br/>[controller.go]")]
  node_overlay["Node overlays<br/>[controller.go]"]
end

subgraph group_lifecycle["Node lifecycle"]
  node_lifecycle["NodeClaim lifecycle<br/>[controller.go]"]
  node_termination["Node termination<br/>[controller.go]"]
  node_terminator["Drain and eviction<br/>[terminator.go]"]
end

subgraph group_state["Cluster state"]
  node_clusterstate[("Cluster state<br/>[cluster.go]")]
  node_informers["Resource informers<br/>[pod.go]"]
  node_virtualpods[("Virtual pod cache<br/>[virtualpods.go]")]
  node_metrics["Metrics controllers<br/>[controller.go]"]
end

subgraph group_capacity["Capacity management"]
  node_disruption["Disruption controller<br/>[controller.go]"]
  node_consolidation["Consolidation methods<br/>[consolidation.go]"]
  node_static["Static capacity<br/>[controller.go]"]
  node_staticdown["Static deprovisioning<br/>[controller.go]"]
  node_buffer["Capacity buffers<br/>[controller.go]"]
end

node_k8s(("Kubernetes API"))
node_pods(("Workload Pods"))
node_provider(("Provider infrastructure"))
node_node(("Kubernetes Nodes"))

node_pods -->|"submit workloads"| node_k8s
node_k8s -->|"enqueue provisionable pods"| node_podtrigger
node_podtrigger -->|"trigger provisioning"| node_provisioner
node_podtrigger -->|"acknowledge pending pods"| node_clusterstate
node_provisioner -->|"schedule workloads"| node_scheduler
node_scheduler -->|"evaluate constraints"| node_scheduling
node_provisioner -->|"construct claims"| node_nodeclaimapi
node_provisioner -->|"request capacity"| node_cloudprovider
node_cloudprovider -->|"create instances"| node_provider
node_lifecycle -->|"launch claims"| node_cloudprovider
node_lifecycle -->|"patch claim status"| node_k8s
node_provider -->|"register nodes"| node_node
node_k8s -->|"watch resources"| node_informers
node_informers -->|"update state"| node_clusterstate
node_disruption -->|"evaluate candidates"| node_consolidation
node_disruption -->|"inspect cluster"| node_clusterstate
node_disruption -->|"replace capacity"| node_provisioner
node_termination -->|"drain workloads"| node_terminator
node_termination -->|"delete instances"| node_cloudprovider
node_termination -->|"delete claims and nodes"| node_k8s
node_static -->|"manage static capacity"| node_k8s
node_staticdown -->|"select claims"| node_clusterstate
node_staticdown -->|"delete claims"| node_k8s
node_buffer -->|"refresh virtual pods"| node_virtualpods
node_buffer -->|"trigger provisioning"| node_provisioner
node_dra -->|"track resource claims"| node_k8s
node_overlay -->|"read and patch overlays"| node_k8s
node_overlay -->|"invalidate consolidation state"| node_clusterstate
node_metrics -->|"read node state"| node_clusterstate

click node_podtrigger "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/provisioning/controller.go"
click node_provisioner "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/provisioning/provisioner.go"
click node_scheduler "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/provisioning/scheduling/scheduler.go"
click node_scheduling "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/scheduling/requirements.go"
click node_nodeclaimapi "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/apis/v1/nodeclaim.go"
click node_cloudprovider "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/cloudprovider/types.go"
click node_lifecycle "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/nodeclaim/lifecycle/controller.go"
click node_termination "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/node/termination/controller.go"
click node_terminator "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/node/termination/terminator/terminator.go"
click node_clusterstate "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/state/cluster.go"
click node_informers "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/state/informer/pod.go"
click node_disruption "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/disruption/controller.go"
click node_consolidation "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/disruption/consolidation.go"
click node_static "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/static/provisioning/controller.go"
click node_staticdown "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/static/deprovisioning/controller.go"
click node_buffer "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/capacitybuffer/controller.go"
click node_virtualpods "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/state/virtualpods/virtualpods.go"
click node_dra "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/dynamicresources/deviceallocation/controller.go"
click node_overlay "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/nodeoverlay/controller.go"
click node_metrics "https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/metrics/node/controller.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_podtrigger,node_provisioner,node_scheduler,node_scheduling,node_nodeclaimapi,node_cloudprovider,node_dra,node_overlay toneBlue
class node_lifecycle,node_termination,node_terminator toneAmber
class node_clusterstate,node_informers,node_virtualpods,node_metrics,node_k8s toneMint
class node_disruption,node_consolidation,node_static,node_staticdown,node_buffer toneRose
class node_pods,node_provider,node_node toneIndigo
```

## Components

### Provisioning

- [Pod trigger](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/provisioning/controller.go): `pkg/controllers/provisioning/controller.go`
- [Provisioner](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/provisioning/provisioner.go): `pkg/controllers/provisioning/provisioner.go`
- [Constraint scheduler](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/provisioning/scheduling/scheduler.go): `pkg/controllers/provisioning/scheduling/scheduler.go`
- [Scheduling rules](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/scheduling/requirements.go): `pkg/scheduling/requirements.go`
- [NodeClaim and NodePool](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/apis/v1/nodeclaim.go): `pkg/apis/v1/nodeclaim.go`
- [Cloud provider](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/cloudprovider/types.go): `pkg/cloudprovider/types.go`
- [Device allocation](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/dynamicresources/deviceallocation/controller.go): `pkg/controllers/dynamicresources/deviceallocation/controller.go`
- [Node overlays](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/nodeoverlay/controller.go): `pkg/controllers/nodeoverlay/controller.go`

### Node lifecycle

- [NodeClaim lifecycle](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/nodeclaim/lifecycle/controller.go): `pkg/controllers/nodeclaim/lifecycle/controller.go`
- [Node termination](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/node/termination/controller.go): `pkg/controllers/node/termination/controller.go`
- [Drain and eviction](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/node/termination/terminator/terminator.go): `pkg/controllers/node/termination/terminator/terminator.go`

### Cluster state

- [Cluster state](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/state/cluster.go): `pkg/controllers/state/cluster.go`
- [Resource informers](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/state/informer/pod.go): `pkg/controllers/state/informer/pod.go`
- [Virtual pod cache](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/state/virtualpods/virtualpods.go): `pkg/state/virtualpods/virtualpods.go`
- [Metrics controllers](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/metrics/node/controller.go): `pkg/controllers/metrics/node/controller.go`

### Capacity management

- [Disruption controller](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/disruption/controller.go): `pkg/controllers/disruption/controller.go`
- [Consolidation methods](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/disruption/consolidation.go): `pkg/controllers/disruption/consolidation.go`
- [Static capacity](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/static/provisioning/controller.go): `pkg/controllers/static/provisioning/controller.go`
- [Static deprovisioning](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/static/deprovisioning/controller.go): `pkg/controllers/static/deprovisioning/controller.go`
- [Capacity buffers](https://github.com/kubernetes-sigs/karpenter/blob/main/pkg/controllers/capacitybuffer/controller.go): `pkg/controllers/capacitybuffer/controller.go`

### Other components

- **Kubernetes API**
- **Workload Pods**
- **Provider infrastructure**
- **Kubernetes Nodes**

## Connections

- Workload Pods → Kubernetes API: submit workloads
- Kubernetes API → Pod trigger: enqueue provisionable pods
- Pod trigger → Provisioner: trigger provisioning
- Pod trigger → Cluster state: acknowledge pending pods
- Provisioner → Constraint scheduler: schedule workloads
- Constraint scheduler → Scheduling rules: evaluate constraints
- Provisioner → NodeClaim and NodePool: construct claims
- Provisioner → Cloud provider: request capacity
- Cloud provider → Provider infrastructure: create instances
- NodeClaim lifecycle → Cloud provider: launch claims
- NodeClaim lifecycle → Kubernetes API: patch claim status
- Provider infrastructure → Kubernetes Nodes: register nodes
- Kubernetes API → Resource informers: watch resources
- Resource informers → Cluster state: update state
- Disruption controller → Consolidation methods: evaluate candidates
- Disruption controller → Cluster state: inspect cluster
- Disruption controller → Provisioner: replace capacity
- Node termination → Drain and eviction: drain workloads
- Node termination → Cloud provider: delete instances
- Node termination → Kubernetes API: delete claims and nodes
- Static capacity → Kubernetes API: manage static capacity
- Static deprovisioning → Cluster state: select claims
- Static deprovisioning → Kubernetes API: delete claims
- Capacity buffers → Virtual pod cache: refresh virtual pods
- Capacity buffers → Provisioner: trigger provisioning
- Device allocation → Kubernetes API: track resource claims
- Node overlays → Kubernetes API: read and patch overlays
- Node overlays → Cluster state: invalidate consolidation state
- Metrics controllers → Cluster state: read node state
