AWS EBS Stale Snapshot Cleaner

A serverless AWS Lambda function written in Python that automatically identifies and deletes stale EBS snapshots to reduce unnecessary AWS storage costs. Deployed and scheduled via AWS SAM (Serverless Application Model).

---

Architecture

  ┌─────────────────────────────────┐
  │  Amazon EventBridge (Cron)      │
  │  Runs every Sunday @ 2 AM UTC   │
  └────────────────┬────────────────┘
                   │ triggers
                   ▼
  ┌─────────────────────────────────┐
  │   AWS Lambda (Python 3.9)       │
  │   stale_ebs_snapshots_remover   │
  │                                 │
  │  1. describe_snapshots()  ──────┼──► All EBS Snapshots (paginated)
  │  2. describe_instances()  ──────┼──► Running EC2 Instances (paginated)
  │  3. describe_volumes()    ──────┼──► Volume attachment status
  │  4. delete_snapshot()     ──────┼──► Delete stale snapshots
  └──────────┬──────────────────────┘
             │
      ┌──────┴──────┐
      ▼             ▼
  CloudWatch     Amazon SNS
    Logs       (Email Alert)

---

What is a Stale Snapshot?

A snapshot is considered stale and is safely removed when:

Condition	Action
Snapshot has no associated volume ID	Delete
Associated volume no longer exists	Delete
Volume exists but is not attached to any instance	Delete
Volume is attached to a stopped/terminated instance	Delete
Volume is attached to a running instance	Keep

---

Key Features

Feature	Details
Stale Snapshot Detection	Validates relationships across snapshots, volumes, and EC2 instances
Boto3 Pagination	Handles large AWS accounts with thousands of snapshots using AWS paginators
Dry-Run Mode	Set DRY_RUN=true to log what would be deleted without actually deleting
SNS Email Alerts	Sends a cleanup summary email via Amazon SNS after each execution
CloudWatch Logging	All actions are streamed to CloudWatch Logs for monitoring and audit
Automated Scheduling	Triggered weekly via Amazon EventBridge (CloudWatch Events) cron

---

AWS Services Used

1. AWS Lambda — Serverless compute to run the Python function
2. Amazon EC2 API — Describes and manages snapshots, volumes, and instances
3. Amazon CloudWatch Logs — Operational monitoring and troubleshooting
4. Amazon SNS — Email notification on cleanup completion
5. Amazon EventBridge — Automated weekly cron schedule

---

IAM Permissions Required

The Lambda execution role needs the following minimum permissions:

{
  "Effect": "Allow",
  "Action": [
    "ec2:DescribeSnapshots",
    "ec2:DescribeInstances",
    "ec2:DescribeVolumes",
    "ec2:DeleteSnapshot",
    "sns:Publish"
  ],
  "Resource": "*"
}

These are automatically provisioned by the SAM template.

---

Deployment (AWS SAM)

Prerequisites

• AWS CLI configured (aws configure)
• AWS SAM CLI installed

Steps

# 1. Clone the repository
git clone https://github.com/Yogesh-rana-2301/AWS-EBS-Stale-Snapshot-Cleaner.git
cd AWS-EBS-Stale-Snapshot-Cleaner

# 2. Build the SAM application
sam build

# 3. Deploy (first time — interactive guided setup)
sam deploy --guided \
  --parameter-overrides \
    AlertEmail=your-email@example.com \
    DryRun=true

#   After deploying, confirm the SNS subscription from your email inbox.

# 4. Once validated, redeploy with DryRun=false for live deletions
sam deploy \
  --parameter-overrides \
    AlertEmail=your-email@example.com \
    DryRun=false

---

Environment Variables

Variable	Default	Description
DRY_RUN	false	Set true to log deletions without executing them
SNS_TOPIC_ARN	(empty)	ARN of the SNS topic for email alerts — auto-set by SAM

---

Local Testing (LocalStack)

LocalStack lets you simulate AWS services locally at zero cost.

# 1. Start LocalStack
pip install localstack
localstack start

# 2. Create test resources via AWS CLI (pointed at LocalStack)
export AWS_DEFAULT_REGION=us-east-1
export AWS_ENDPOINT_URL=http://localhost:4566

# Create a test EC2 instance, volume, and snapshot
aws ec2 run-instances --image-id ami-12345678 --instance-type t2.micro
aws ec2 create-volume --availability-zone us-east-1a --size 8
aws ec2 create-snapshot --volume-id vol-xxxxxxxx --description "test snapshot"

# 3. Run the Lambda locally with DRY_RUN=true first
DRY_RUN=true python stale_ebs_snapshots_remover.py

Note: Always test in LocalStack or with DRY_RUN=true before running against real AWS resources to prevent accidental data loss.

---

Cleanup (Avoid AWS Charges)

After testing, delete all deployed resources:

sam delete

This removes the Lambda function, SNS topic, EventBridge schedule, and IAM role.

---

Project Structure

AWS-EBS-Stale-Snapshot-Cleaner/
├── stale_ebs_snapshots_remover.py   # Main Lambda function
├── template.yaml                    # AWS SAM infrastructure template
├── boto3-learner-file.py            # Boto3 reference/learning notes
└── README.md                        # This file