# aws/karpenter architecture

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

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

## Overview

##### Main Components (Core Architecture)

- Karpenter Controller (main orchestrator)
- NodeClaim Controller
- NodePool Controller
- NodeClass Controller
- Interruption Controller

- Kubernetes API Server
- AWS Services (EC2, IAM, SQS, SSM, Pricing API)

c. Resource Management (Right side):
- Instance Types Provider
- Launch Template Provider
- AMI Family Provider
- Security Group Provider
- Subnet Provider

##### Data Flow and Interactions

- Watch flows from Kubernetes API Server to Karpenter Controller
- Provisioning flows from Controller to AWS Services
- Event flows from AWS Services through SQS to Interruption Controller
- Configuration flows from NodePools/NodeClaims to the Controller

a. Node Provisioning Flow (Green):
- Unschedulable Pod Detection
- Constraint Evaluation
- Node Creation
- Node Registration

b. Node Deprovisioning Flow (Red):
- Empty Node Detection
- Consolidation Evaluation
- Node Termination

##### Integration Points

Connections to:
- CloudWatch Metrics
- Prometheus Metrics (via ServiceMonitor)
- Helm Controller
- AWS Cloud Provider

##### Component Details

- Component Name
- Key Responsibilities
- Dependencies
- Configuration Sources

##### Architectural Patterns

Highlight:
- Controller Pattern
- Provider Pattern
- Event-Driven Architecture
- Cloud Integration Pattern

Styling Guidelines:

- Infrastructure layer (bottom)
- Core services layer (middle)
- API/Interface layer (top)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Systems"
        K8S[Kubernetes API Server]:::k8s
        subgraph AWS
            EC2[EC2 Service]:::aws
            IAM[IAM Service]:::aws
            SQS[SQS Service]:::aws
            SSM[SSM Service]:::aws
            PRICE[Pricing API]:::aws
        end
    end

    subgraph "Core Controllers"
        MAIN[Karpenter Controller]:::core
        click MAIN "https://github.com/aws/karpenter/blob/main/cmd/controller/main.go"
        
        NC[NodeClaim Controller]:::controller
        click NC "https://github.com/aws/karpenter/tree/main/pkg/controllers/nodeclaim/"
        
        NP[NodePool Controller]:::controller
        
        NCL[NodeClass Controller]:::controller
        click NCL "https://github.com/aws/karpenter/tree/main/pkg/controllers/nodeclass/"
        
        IC[Interruption Controller]:::controller
        click IC "https://github.com/aws/karpenter/blob/main/pkg/controllers/interruption/controller.go"
    end

    subgraph "Resource Providers"
        IT[Instance Types Provider]:::provider
        click IT "https://github.com/aws/karpenter/blob/main/pkg/providers/instancetype/instancetype.go"
        
        LT[Launch Template Provider]:::provider
        click LT "https://github.com/aws/karpenter/blob/main/pkg/providers/launchtemplate/launchtemplate.go"
        
        AMI[AMI Family Provider]:::provider
        click AMI "https://github.com/aws/karpenter/blob/main/pkg/providers/amifamily/ami.go"
        
        SG[Security Group Provider]:::provider
        click SG "https://github.com/aws/karpenter/blob/main/pkg/providers/securitygroup/securitygroup.go"
        
        SUB[Subnet Provider]:::provider
        click SUB "https://github.com/aws/karpenter/blob/main/pkg/providers/subnet/subnet.go"
    end

    subgraph "Resource Definitions"
        NPD["NodePool API"]:::api
        click NPD "https://github.com/aws/karpenter/blob/main/pkg/apis/v1/nodepool_validation_cel_test.go"
        
        NCD["NodeClaim API"]:::api
        click NCD "https://github.com/aws/karpenter/blob/main/pkg/apis/crds/karpenter.sh_nodeclaims.yaml"
        
        NCLD["NodeClass API"]:::api
        click NCLD "https://github.com/aws/karpenter/blob/main/pkg/apis/crds/karpenter.k8s.aws_ec2nodeclasses.yaml"
    end

    subgraph "Monitoring"
        METRICS[Metrics Collection]:::monitoring
        click METRICS "https://github.com/aws/karpenter/blob/main/pkg/controllers/interruption/metrics.go"
        
        SM[Service Monitor]:::monitoring
        click SM "https://github.com/aws/karpenter/blob/main/charts/karpenter/templates/servicemonitor.yaml"
    end

    %% Core Interactions
    K8S --> MAIN
    MAIN --> NC
    MAIN --> NP
    MAIN --> NCL
    MAIN --> IC

    %% AWS Integration
    SQS --> IC
    EC2 --> MAIN
    IAM --> MAIN
    SSM --> MAIN
    PRICE --> MAIN

    %% Provider Interactions
    NC --> IT
    NC --> LT
    NC --> AMI
    NC --> SG
    NC --> SUB

    %% Resource Definition Usage
    NPD --> MAIN
    NCD --> NC
    NCLD --> NCL

    %% Monitoring Flow
    MAIN --> METRICS
    METRICS --> SM

    %% Styling
    classDef core fill:#2374ab
    classDef controller fill:#4a90e2
    classDef provider fill:#45b7d1
    classDef api fill:#98c1d9
    classDef monitoring fill:#bee9e8
    classDef aws fill:#ff9900
    classDef k8s fill:#326ce5

    %% Legend
    subgraph Legend
        L1[Core Component]:::core
        L2[Controller]:::controller
        L3[Provider]:::provider
        L4[API Definition]:::api
        L5[Monitoring]:::monitoring
        L6[AWS Service]:::aws
        L7[Kubernetes]:::k8s
    end
```
