# aws-samples/ec2-spot-interruption-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/ec2-spot-interruption-dashboard
- Repository: https://github.com/aws-samples/ec2-spot-interruption-dashboard

## Overview

##### Project type and purpose
- Type: A serverless, event-driven AWS solution implemented with the AWS Serverless Application Model (SAM).
- Purpose: Capture EC2 Spot instance life-cycle events (launch, state change, interruption, termination), enrich and store them (in DynamoDB, CloudWatch Metrics, S3), and surface insights via a CloudWatch Dashboard and Athena queries.

##### Main architectural components
- Event Sources (Amazon EventBridge / CloudWatch Events)
– Spot Launch events
– State Change events
– Spot Interruption events
– Spot Termination events
- Lambda “Trigger” Functions
– SpotLaunchTriggerFunction
– StateChangeTriggerFunction
– SpotInterruptionTriggerFunction
– SpotLaunchTriggerFunction
– SpotRebalanceTriggerFunction
- Instance Metadata Enrichment
– InstanceMetadataEnrichmentFunction (invoked on new item in DynamoDB)
– DynamoDB table for instance metadata
- Data Sink State Machine (AWS Step Functions)
– Orchestrates enrichment and sink flows for interruptions and terminations
– Sub-workflows (DataSinkInterruptionFunction, DataSinkInterruptionEnrichmentFunction, DataSinkTerminationFunction, DataSinkTerminationEnrichmentFunction, DataSinkRunningFunction, DataSinkRunningEnrichmentFunction, etc.)
- Storage & Metrics
– DynamoDB: current instance metadata
– CloudWatch Custom Metrics: interruption events
– S3 bucket: JSON records of termination events
– Athena: query layer over S3 data
– CloudWatch Dashboard: visualization of interruption metrics

##### Relationships and data flow
1. EventBridge rule triggers the appropriate “TriggerFunction” Lambda.
2. TriggerFunction writes a record to DynamoDB stream or directly to Step Function.
3. DynamoDB stream (for inserts) invokes InstanceMetadataEnrichmentFunction to call DescribeInstances, then writes enriched metadata back to DynamoDB.
4. For interruption events: TriggerFunction starts the Data Sink Step Function execution.
5. Inside Step Function: enrichment Lambda (optional) → CloudWatch PutMetricData for interruption.
6. For termination events: Step Function branching → enrichment Lambda → writes JSON to S3.
7. Athena is configured over the S3 bucket; CloudWatch Dashboard reads the custom metrics directly.

##### Architectural patterns and design principles
- Event-driven, asynchronous processing
- Single-purpose, small Lambda functions (micro-functions)
- State machine orchestration for complex data-sink workflows
- Separation of concerns:
– Trigger layer (event ingestion)
– Enrichment layer (instance description)
– Sink layer (metrics, persistence)
- IaC via SAM in template.yaml

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Event Ingestion Layer"
        EB["EventBridge"]:::event
        SL["SpotLaunchTriggerFunction"]:::trigger
        SC["StateChangeTriggerFunction"]:::trigger
        SI["SpotInterruptionTriggerFunction"]:::trigger
        SR["SpotRebalanceTriggerFunction"]:::trigger
        DST["DataSinkTriggerFunction"]:::trigger
        EB -->|Spot Launch| SL
        EB -->|State Change| SC
        EB -->|Interruption| SI
        EB -->|Rebalance| SR
        EB -->|Interruption/Termination| DST
    end

    subgraph "DynamoDB Metadata Store"
        DDB["DynamoDB (Metadata)"]:::storage
        DDB_Stream["DynamoDB Stream"]:::storage
        SL -->|"Write to DynamoDB"| DDB
        SC -->|"Write to DynamoDB"| DDB
        SR -->|"Write to DynamoDB"| DDB
        DDB -->|Stream Event| DDB_Stream
    end

    subgraph "Enrichment Layer"
        IMEF["InstanceMetadataEnrichmentFunction"]:::enrichment
        DDB_Stream -.->|Invoke| IMEF
        IMEF -->|"DescribeInstances"| AWSAPI["AWS EC2 API"]:::storage
        IMEF -->|"Write to DynamoDB"| DDB
    end

    subgraph "Data Sink Orchestration"
        SF["Step Functions"]:::orchestrator
        DST -->|"Start Execution"| SF
        SF -->|"Interruption Path"| DI["DataSinkInterruptionFunction"]:::orchestrator
        SF -->|"Running Path"| DR["DataSinkRunningFunction"]:::orchestrator
        SF -->|"Termination Path"| DT["DataSinkTerminationFunction"]:::orchestrator

        subgraph "Interruption Branch"
            DI --> DEI["DataSinkInterruptionEnrichmentFunction"]:::enrichment
            DEI -->|"PutMetricData"| CW["CloudWatch Metrics"]:::storage
        end

        subgraph "Running Branch"
            DR --> DER["DataSinkRunningEnrichmentFunction"]:::enrichment
            DER -->|"PutMetricData"| CW
        end

        subgraph "Termination Branch"
            DT --> DET["DataSinkTerminationEnrichmentFunction"]:::enrichment
            DET -->|"Write JSON"| S3["S3 Bucket"]:::storage
        end
    end

    subgraph "Analytics & Dashboard"
        CW -->|"Dashboard Visual"| Dashboard["CloudWatch Dashboard"]:::storage
        S3 -->|"Athena Query"| Athena["Athena"]:::storage
    end

    CF["SAM Template (template.yaml)"]:::iac

    click SL "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/SpotLaunchTriggerFunction/app.py"
    click SC "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/StateChangeTriggerFunction/app.py"
    click SI "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/SpotInterruptionTriggerFunction/app.py"
    click SR "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/SpotRebalanceTriggerFunction/app.py"
    click DST "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/DataSinkTriggerFunction/app.py"
    click IMEF "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/InstanceMetadataEnrichmentFunction/app.py"
    click DI "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/DataSinkStateMachine/DataSinkInterruptionFunction/app.py"
    click DEI "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/DataSinkStateMachine/DataSinkInterruptionEnrichmentFunction/app.py"
    click DR "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/DataSinkStateMachine/DataSinkRunningFunction/app.py"
    click DER "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/DataSinkStateMachine/DataSinkRunningEnrichmentFunction/app.py"
    click DT "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/DataSinkStateMachine/DataSinkTerminationFunction/app.py"
    click DET "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/source/DataSinkStateMachine/DataSinkTerminationEnrichmentFunction/app.py"
    click CF "https://github.com/aws-samples/ec2-spot-interruption-dashboard/blob/master/template.yaml"

    classDef event fill:#FFE4C4,stroke:#D2B48C,color:#000
    classDef trigger fill:#FFDEAD,stroke:#DAA520,color:#000
    classDef enrichment fill:#E0FFFF,stroke:#20B2AA,color:#000
    classDef orchestrator fill:#E6E6FA,stroke:#9370DB,color:#000
    classDef storage fill:#F0FFF0,stroke:#32CD32,color:#000
    classDef iac fill:#FFFACD,stroke:#FFD700,color:#000
```
