# aws/aws-node-termination-handler architecture

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

- Interactive diagram: https://gitdiagram.com/aws/aws-node-termination-handler
- Repository: https://github.com/aws/aws-node-termination-handler

## Overview

##### Main Components
- Kubernetes Cluster – This is the runtime environment where the termination handler is deployed. Represent the cluster with nodes (each running Kubernetes, e.g., EC2 instances).
- AWS Node Termination Handler – It has two modes:
- IMDS Processor Mode: Deployed as a DaemonSet on all cluster nodes. It polls EC2 instance metadata endpoints (like /spot, /events, etc.) on every node.
- Queue Processor Mode: Deployed as a Deployment (potentially with multiple replicas) that listens to an SQS queue for termination events via Amazon EventBridge or direct ASG lifecycle hook messages.
- AWS Services:
- EC2 Instance Metadata (IMDS) – This is where each node fetches local instance metadata about scheduled terminations or state changes.
- Amazon Simple Queue Service (SQS) – Used by Queue Processor mode to receive messages about termination events.
- Amazon EventBridge and ASG lifecycle hooks – These services generate and forward notifications (via EventBridge rules, lifecycle hooks) that are eventually posted into SQS.
- Auto Scaling Group (ASG) – Manages EC2 instances and uses lifecycle hooks to delay termination until the node is cordoned/drained.
- Kubernetes API – The termination handler uses the Kubernetes API to cordon (prevent new pods from being scheduled) and drain nodes when an interruption is detected.
- Additional Infrastructure/Integration:
- Helm charts & Config files – As shown in the config/helm folder, which help deploy and configure the application.
- Logging and Observability Components – Exposed Prometheus metrics, as well as integrations with webhook endpoints (e.g., Slack notifications).

##### Relationships and Data Flow
- For IMDS Processor Mode:
- Each node (represented as a pod running the IMDS handler) polls the EC2 instance metadata endpoints.
- When a termination event (spot interruption, scheduled maintenance, or rebalance recommendation) is detected, the pod issues a call to the Kubernetes API to cordon and drain its own node.
- For Queue Processor Mode:
- An AWS SQS queue collects events from EventBridge or ASG lifecycle hooks.
- The Queue Processor (running as a Deployment) reads messages from SQS.
- Once a termination message is received, it triggers an action via the Kubernetes API to cordon and drain the associated node.
- Additionally, if enabled, the handler sends periodic heartbeats back to ASG (extending termination wait as necessary).
- Additional flows include logging, metric collection (via Prometheus endpoints), and optional webhook notifications.

##### Architectural Patterns and Technologies
- Separation of Concerns – The design clearly separates the monitoring (via IMDS for each node) and event processing (via Queue Processor) into distinct deployment patterns.
- Kubernetes Native Deployment Patterns – Use of DaemonSets for node-local monitoring and Deployments for centralized event processing.
- Cloud Integration – Use of AWS services (EC2, SQS, EventBridge, ASG) integrated tightly with Kubernetes for life‐cycle management.
- Extensibility – The helm charts and configuration files (in config/helm) demonstrate how the project can be easily configured and extended.

##### Detailed Elements
- Kubernetes Cluster:
- Nodes (EC2 instances) with “aws-node-termination-handler” running in two possible modes (DaemonSet for IMDS; Deployment for Queue Processing).
- Kubernetes API server, which is the target for node cordoning/draining.
- AWS Components:
- EC2 Instance Metadata Service (illustrate the metadata endpoints being polled by the IMDS mode).
- ASG and Lifecycle Hooks, with notes about termination grace periods and heartbeat extension.
- Integration/Monitoring:
- How Prometheus metrics are collected (via PodMonitor/ServiceMonitor).
- Optionally, show external webhooks for notifications.
- Data/Control Flows:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        main_app["AWS Node Termination Handler"] 
        imds_processor["IMDS Processor (DaemonSet)"]
        queue_processor["Queue Processor (Deployment)"]
        k8s_api["Kubernetes API Server"]
        observability["Logging & Observability (Prometheus, Webhooks)"]
    end

    %% AWS External Services
    subgraph "AWS Services"
        ec2_metadata["EC2 Instance Metadata Service"]
        eventbridge_asg["Amazon EventBridge & ASG Lifecycle Hooks"]
        sqs_queue["Amazon SQS Queue"]
    end

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        helm_charts["Helm Charts & Config"]
    end

    %% Core Application Flow
    main_app -->|"deploys"| imds_processor
    main_app -->|"deploys"| queue_processor
    imds_processor -->|"cordon/drain"| k8s_api
    queue_processor -->|"cordon/drain"| k8s_api

    %% Observability connections
    imds_processor -->|"metrics"| observability
    queue_processor -->|"metrics"| observability

    %% AWS Services Flow
    ec2_metadata -->|"polls"| imds_processor
    eventbridge_asg -->|"sends_events"| sqs_queue
    sqs_queue -->|"messages"| queue_processor
    queue_processor -->|"heartbeat"| eventbridge_asg

    %% Helm deploying processors
    helm_charts -->|"deploys"| imds_processor
    helm_charts -->|"deploys"| queue_processor

    %% Click Events for Main Application
    click main_app "https://github.com/aws/aws-node-termination-handler/blob/main/cmd/node-termination-handler.go"
    
    %% Click Events for IMDS Processor Mode
    click imds_processor "https://github.com/aws/aws-node-termination-handler/blob/main/config/helm/aws-node-termination-handler/templates/daemonset.linux.yaml"
    click imds_processor "https://github.com/aws/aws-node-termination-handler/blob/main/config/helm/aws-node-termination-handler/templates/daemonset.windows.yaml"
    click imds_processor "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/ec2metadata/ec2metadata.go"

    %% Click Events for Queue Processor Mode
    click queue_processor "https://github.com/aws/aws-node-termination-handler/blob/main/config/helm/aws-node-termination-handler/templates/deployment.yaml"
    click queue_processor "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/monitor/sqsevent/sqs-monitor.go"
    click queue_processor "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/monitor/sqsevent/asg-lifecycle-event.go"
    click queue_processor "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/monitor/sqsevent/spot-itn-event.go"

    %% Click Events for Kubernetes API Interaction
    click k8s_api "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/node/node.go"
    click k8s_api "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/interruptionevent/draincordon/handler.go"

    %% Click Events for AWS Services Integration
    click eventbridge_asg "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/monitor/asglifecycle/asg-lifecycle-monitor.go"
    click eventbridge_asg "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/interruptionevent/asg/launch/handler.go"

    %% Click Events for Helm Charts & Configuration
    click helm_charts "https://github.com/aws/aws-node-termination-handler/tree/main/config/helm/aws-node-termination-handler"
    click helm_charts "https://github.com/aws/aws-node-termination-handler/blob/main/config/helm/aws-node-termination-handler/example-values-imds-linux.yaml"
    click helm_charts "https://github.com/aws/aws-node-termination-handler/blob/main/config/helm/aws-node-termination-handler/example-values-imds-windows.yaml"
    click helm_charts "https://github.com/aws/aws-node-termination-handler/blob/main/config/helm/aws-node-termination-handler/example-values-queue.yaml"

    %% Click Events for Logging and Observability
    click observability "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/observability/k8s-events.go"
    click observability "https://github.com/aws/aws-node-termination-handler/blob/main/pkg/observability/opentelemetry.go"
    click observability "https://github.com/aws/aws-node-termination-handler/blob/main/config/helm/aws-node-termination-handler/templates/podmonitor.yaml"
    click observability "https://github.com/aws/aws-node-termination-handler/blob/main/config/helm/aws-node-termination-handler/templates/servicemonitor.yaml"

    %% Styling
    class main_app,imds_processor,queue_processor,k8s_api,observability cluster
    class ec2_metadata,eventbridge_asg,sqs_queue aws
    class helm_charts config
    class observability observ

%% Define class styles
classDef cluster fill:#C2E7FF,stroke:#333,stroke-width:2px;
classDef aws fill:#FFE0B3,stroke:#333,stroke-width:2px;
classDef config fill:#E1FFC2,stroke:#333,stroke-width:2px;
classDef observ fill:#F5F5A4,stroke:#333,stroke-width:2px;
```
