How aws-samples/ec2-spot-interruption-dashboard works
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