# aws/karpenter-provider-aws architecture

> Architecture diagram of the GitHub repository aws/karpenter-provider-aws, 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/aws/karpenter-provider-aws
- Repository: https://github.com/aws/karpenter-provider-aws

## Overview

This repository is the AWS cloud provider for Karpenter, which provisions and removes Kubernetes nodes to satisfy unschedulable workloads. The principal flow runs from Karpenter’s scheduling/provisioning engine through the provider’s cloud-provider interface, AWS instance-type and launch configuration resolution, and EC2 fleet operations; resulting NodeClaims and Nodes are managed through Kubernetes. Separate branches cover NodeClass reconciliation, interruption handling, capacity reservations, zonal-shift awareness, pricing, and metrics. The README describes the overall workflow; sampled controller excerpts support selected reconciliation and integration links, so unsampled wiring is left out.

Main entry points: [`pkg/cloudprovider/cloudprovider.go`](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/cloudprovider/cloudprovider.go) (AWS cloud provider), [`pkg/operator/operator.go`](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/operator/operator.go) (Provider operator), [`pkg/controllers/controllers.go`](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/controllers.go) (Controller registration), [`pkg/providers/launchtemplate/launchtemplate.go`](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/launchtemplate/launchtemplate.go) (Launch templates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and API"]
  node_operator["Provider operator<br/>[operator.go]"]
  node_apis["Provider APIs<br/>[ec2nodeclass.go]"]
  node_cloudprovider["AWS cloud provider<br/>[cloudprovider.go]"]
  node_controllers["Controller registration<br/>[controllers.go]"]
end

subgraph group_config["NodeClass configuration"]
  node_nodeclass["NodeClass reconciliation<br/>[controller.go]"]
  node_classproviders["Class resource providers"]
  node_ami["AMI and bootstrap"]
end

subgraph group_provision["Instance provisioning"]
  node_instancetype["Instance type offerings<br/>[instancetype.go]"]
  node_launchtemplate["Launch templates<br/>[launchtemplate.go]"]
  node_batcher["EC2 request batching<br/>[ec2api.go]"]
  node_instance["Instance provider<br/>[instance.go]"]
end

subgraph group_lifecycle["Node lifecycle"]
  node_gc["NodeClaim cleanup<br/>[controller.go]"]
  node_tagging["NodeClaim tagging<br/>[controller.go]"]
  node_interruptions["Interruption handling<br/>[controller.go]"]
  node_status["Instance health checks"]
  node_capacity["Reservation lifecycle<br/>[controller.go]"]
  node_zonalshift["Zonal shift detection<br/>[controller.go]"]
end

subgraph group_observability["Capacity signals"]
  node_pricing["Pricing provider<br/>[pricing.go]"]
  node_metrics["Offering metrics<br/>[controller.go]"]
end

node_workloads(("Unschedulable pods"))
node_karpenter(("Karpenter engine"))
node_kubernetes[("Kubernetes API")]
node_ec2["Amazon EC2"]
node_sqs["Interruption queue<br/>[sqs.go]"]
node_awsservices["AWS services"]

node_workloads -->|"trigger scheduling"| node_karpenter
node_karpenter -->|"read workloads"| node_kubernetes
node_karpenter -->|"request capacity"| node_cloudprovider
node_operator -->|"register controllers"| node_controllers
node_operator -->|"initialize provider"| node_cloudprovider
node_operator -->|"install API types"| node_apis
node_controllers -->|"register reconciliation"| node_nodeclass
node_controllers -->|"register handling"| node_interruptions
node_cloudprovider -->|"read NodeClaims"| node_kubernetes
node_cloudprovider -->|"resolve offerings"| node_instancetype
node_cloudprovider -->|"build launch data"| node_launchtemplate
node_cloudprovider -->|"create or terminate"| node_batcher
node_instancetype -->|"query capacity data"| node_awsservices
node_launchtemplate -->|"resolve bootstrap"| node_ami
node_launchtemplate -->|"resolve class resources"| node_classproviders
node_batcher -->|"submit fleet requests"| node_ec2
node_instance -->|"query and tag instances"| node_ec2
node_gc -->|"list and delete claims"| node_cloudprovider
node_gc -->|"read and delete Nodes"| node_kubernetes
node_tagging -->|"inspect and tag"| node_instance
node_tagging -->|"patch NodeClaim"| node_kubernetes
node_interruptions -->|"consume notices"| node_sqs
node_interruptions -->|"cordon or drain"| node_kubernetes
node_status -->|"poll instance status"| node_awsservices
node_status -->|"handle unhealthy nodes"| node_kubernetes
node_capacity -->|"check reservations"| node_awsservices
node_capacity -->|"delete expiring claims"| node_kubernetes
node_zonalshift -->|"inspect shifted zones"| node_awsservices
node_zonalshift -->|"read NodePools and NodeClasses"| node_kubernetes
node_metrics -->|"list NodePools"| node_kubernetes
node_metrics -->|"get instance types"| node_cloudprovider
node_cloudprovider -->|"resolve offering prices"| node_pricing
node_classproviders -->|"resolve AWS resources"| node_awsservices

click node_operator "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/operator/operator.go"
click node_apis "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/apis/v1/ec2nodeclass.go"
click node_cloudprovider "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/cloudprovider/cloudprovider.go"
click node_controllers "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/controllers.go"
click node_nodeclass "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/nodeclass/controller.go"
click node_classproviders "https://github.com/aws/karpenter-provider-aws/tree/main/pkg/controllers/nodeclass"
click node_ami "https://github.com/aws/karpenter-provider-aws/tree/main/pkg/providers/amifamily"
click node_instancetype "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/instancetype/instancetype.go"
click node_launchtemplate "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/launchtemplate/launchtemplate.go"
click node_batcher "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/batcher/ec2api.go"
click node_instance "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/instance/instance.go"
click node_gc "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/nodeclaim/garbagecollection/controller.go"
click node_tagging "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/nodeclaim/tagging/controller.go"
click node_interruptions "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/interruption/controller.go"
click node_sqs "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/sqs/sqs.go"
click node_status "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/interruption/instancestatus_controller.go"
click node_capacity "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/capacityreservation/expiration/controller.go"
click node_zonalshift "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/arczonalshift/controller.go"
click node_pricing "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/pricing/pricing.go"
click node_metrics "https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/metrics/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_operator,node_apis,node_cloudprovider,node_controllers toneBlue
class node_nodeclass,node_classproviders,node_ami,node_kubernetes toneAmber
class node_instancetype,node_launchtemplate,node_batcher,node_instance toneMint
class node_gc,node_tagging,node_interruptions,node_status,node_capacity,node_zonalshift,node_sqs toneRose
class node_pricing,node_metrics,node_workloads,node_karpenter,node_ec2,node_awsservices toneIndigo
```

## Components

### Runtime and API

- [Provider operator](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/operator/operator.go): `pkg/operator/operator.go`
- [Provider APIs](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/apis/v1/ec2nodeclass.go): `pkg/apis/v1/ec2nodeclass.go`
- [AWS cloud provider](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/cloudprovider/cloudprovider.go): `pkg/cloudprovider/cloudprovider.go`
- [Controller registration](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/controllers.go): `pkg/controllers/controllers.go`

### NodeClass configuration

- [NodeClass reconciliation](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/nodeclass/controller.go): `pkg/controllers/nodeclass/controller.go`
- [Class resource providers](https://github.com/aws/karpenter-provider-aws/tree/main/pkg/controllers/nodeclass): `pkg/controllers/nodeclass`
- [AMI and bootstrap](https://github.com/aws/karpenter-provider-aws/tree/main/pkg/providers/amifamily): `pkg/providers/amifamily`

### Instance provisioning

- [Instance type offerings](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/instancetype/instancetype.go): `pkg/providers/instancetype/instancetype.go`
- [Launch templates](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/launchtemplate/launchtemplate.go): `pkg/providers/launchtemplate/launchtemplate.go`
- [EC2 request batching](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/batcher/ec2api.go): `pkg/batcher/ec2api.go`
- [Instance provider](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/instance/instance.go): `pkg/providers/instance/instance.go`

### Node lifecycle

- [NodeClaim cleanup](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/nodeclaim/garbagecollection/controller.go): `pkg/controllers/nodeclaim/garbagecollection/controller.go`
- [NodeClaim tagging](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/nodeclaim/tagging/controller.go): `pkg/controllers/nodeclaim/tagging/controller.go`
- [Interruption handling](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/interruption/controller.go): `pkg/controllers/interruption/controller.go`
- [Instance health checks](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/interruption/instancestatus_controller.go): `pkg/controllers/interruption/instancestatus_controller.go`
- [Reservation lifecycle](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/capacityreservation/expiration/controller.go): `pkg/controllers/capacityreservation/expiration/controller.go`
- [Zonal shift detection](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/arczonalshift/controller.go): `pkg/controllers/arczonalshift/controller.go`

### Capacity signals

- [Pricing provider](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/pricing/pricing.go): `pkg/providers/pricing/pricing.go`
- [Offering metrics](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/controllers/metrics/controller.go): `pkg/controllers/metrics/controller.go`

### Other components

- **Unschedulable pods**
- **Karpenter engine**
- **Kubernetes API**
- **Amazon EC2**
- [Interruption queue](https://github.com/aws/karpenter-provider-aws/blob/main/pkg/providers/sqs/sqs.go): `pkg/providers/sqs/sqs.go`
- **AWS services**

## Connections

- Unschedulable pods → Karpenter engine: trigger scheduling
- Karpenter engine → Kubernetes API: read workloads
- Karpenter engine → AWS cloud provider: request capacity
- Provider operator → Controller registration: register controllers
- Provider operator → AWS cloud provider: initialize provider
- Provider operator → Provider APIs: install API types
- Controller registration → NodeClass reconciliation: register reconciliation
- Controller registration → Interruption handling: register handling
- AWS cloud provider → Kubernetes API: read NodeClaims
- AWS cloud provider → Instance type offerings: resolve offerings
- AWS cloud provider → Launch templates: build launch data
- AWS cloud provider → EC2 request batching: create or terminate
- Instance type offerings → AWS services: query capacity data
- Launch templates → AMI and bootstrap: resolve bootstrap
- Launch templates → Class resource providers: resolve class resources
- EC2 request batching → Amazon EC2: submit fleet requests
- Instance provider → Amazon EC2: query and tag instances
- NodeClaim cleanup → AWS cloud provider: list and delete claims
- NodeClaim cleanup → Kubernetes API: read and delete Nodes
- NodeClaim tagging → Instance provider: inspect and tag
- NodeClaim tagging → Kubernetes API: patch NodeClaim
- Interruption handling → Interruption queue: consume notices
- Interruption handling → Kubernetes API: cordon or drain
- Instance health checks → AWS services: poll instance status
- Instance health checks → Kubernetes API: handle unhealthy nodes
- Reservation lifecycle → AWS services: check reservations
- Reservation lifecycle → Kubernetes API: delete expiring claims
- Zonal shift detection → AWS services: inspect shifted zones
- Zonal shift detection → Kubernetes API: read NodePools and NodeClasses
- Offering metrics → Kubernetes API: list NodePools
- Offering metrics → AWS cloud provider: get instance types
- AWS cloud provider → Pricing provider: resolve offering prices
- Class resource providers → AWS services: resolve AWS resources
