AWS Cleanup Tool

A comprehensive, production-ready tool for cleaning up AWS resources with intelligent protection removal and multi-region support.

Features • Quick Start • Usage Examples • Safety Features • Documentation

Features

Three Cleanup Modes

Single Resource: Delete one specific resource by ID/name
Multiple Resources: Delete a list of resources at once
Full Cleanup: Delete all resources of a type across regions

Intelligent Protection Removal

Automatically handles protection mechanisms before deletion:

Termination protection (EC2, CloudFormation)
Deletion protection (RDS, S3)
Lifecycle hooks and policies
Versioning and automated backups
Service-specific protections

Multi-Region Support

Clean up resources in specific regions
Clean up across all AWS regions
Region-aware resource detection

Idempotent & Safe

Safe to run multiple times
Graceful error handling
Comprehensive logging
Dry-run mode for testing

Supported Services

Service	Resources Cleaned	Protection Handling
EC2	Instances, Volumes, Snapshots, AMIs, Security Groups, Key Pairs	Termination protection, Volume detachment
ECS	Clusters, Services, Tasks, Task Definitions	Service scaling, Task stopping
Auto Scaling	ASGs, Launch Configurations, Launch Templates	Termination protection, Scaling down
SageMaker	Notebooks, Endpoints, Models, Pipelines, Experiments	Instance stopping, Endpoint deletion
Load Balancers	ALB, NLB, CLB, Target Groups	Listener removal, Policy cleanup
RDS	Instances, Clusters, Snapshots, Parameter Groups	Deletion protection, Backup disabling
S3	Buckets (including versioned)	Versioning suspension, Object deletion
CloudFormation	Stacks, Stack Sets, Change Sets	Termination protection removal

Quick Start

1. Installation

# Clone the repository
git clone <repository-url>
cd aws-cleanup-tool

# Install dependencies
pip install -r requirements.txt

# Configure AWS credentials
aws configure

2. Basic Usage

# See all available options
python aws-cleanup.py --help

# Dry run to see what would be deleted
python aws-cleanup.py ec2 full --dry-run

# Delete a specific EC2 instance
python aws-cleanup.py ec2 single --resource-id i-1234567890abcdef0

Usage Examples

Single Resource Deletion

# Delete a specific EC2 instance
python aws-cleanup.py ec2 single --resource-id i-1234567890abcdef0

# Delete a specific S3 bucket
python aws-cleanup.py s3 single --resource-id my-bucket-name

# Delete a specific RDS instance
python aws-cleanup.py rds single --resource-id my-db-instance

# Delete a specific SageMaker notebook
python aws-cleanup.py sagemaker single --resource-id my-notebook

Multiple Resource Deletion

# Delete multiple ECS clusters
python aws-cleanup.py ecs multiple --resource-ids cluster1,cluster2,cluster3

# Delete multiple S3 buckets
python aws-cleanup.py s3 multiple --resource-ids bucket1,bucket2,bucket3

# Delete multiple Auto Scaling Groups
python aws-cleanup.py asg multiple --resource-ids asg1,asg2,asg3

# Delete multiple RDS instances
python aws-cleanup.py rds multiple --resource-ids db1,db2,db3

Full Cleanup

# Clean up all EC2 resources in us-west-2
python aws-cleanup.py ec2 full --region us-west-2

# Clean up all S3 buckets across all regions
python aws-cleanup.py s3 full --all-regions

# Clean up all SageMaker resources in us-east-1
python aws-cleanup.py sagemaker full --region us-east-1

# Clean up all RDS resources across all regions
python aws-cleanup.py rds full --all-regions

Dry Run Mode

# See what would be deleted without actually deleting
python aws-cleanup.py ec2 full --dry-run

# Dry run for specific resources
python aws-cleanup.py s3 multiple --resource-ids bucket1,bucket2 --dry-run

# Dry run across all regions
python aws-cleanup.py rds full --all-regions --dry-run

Skip Confirmations

# Delete without confirmation prompts
python aws-cleanup.py ec2 full --yes

# Delete specific resources without confirmation
python aws-cleanup.py rds single --resource-id my-db --yes

# Full cleanup without confirmations
python aws-cleanup.py s3 full --all-regions --yes

Advanced Filtering System

The AWS Cleanup Tool includes a comprehensive filtering system that allows you to precisely select which resources to clean up based on various criteria. This prevents accidental deletion of important resources and gives you fine-grained control over the cleanup process.

1. Tag-Based Filtering

Filter resources based on their AWS tags.

Include Tags

# Include resources with specific tag key-value pairs
python aws-cleanup.py ec2 full --include-tags Environment=production Project=myproject

# Include resources with any tag containing "backup"
python aws-cleanup.py s3 full --include-tags backup

# Include resources with specific tag keys
python aws-cleanup.py ec2 full --include-tags Owner Environment

Exclude Tags

# Exclude resources with specific tag key-value pairs
python aws-cleanup.py ec2 full --exclude-tags Environment=development Protected=true

# Exclude resources with any tag containing "test"
python aws-cleanup.py ec2 full --exclude-tags test

# Exclude resources with specific tag keys
python aws-cleanup.py ec2 full --exclude-tags Backup Critical

2. Name-Based Filtering

Filter resources based on their names using wildcards and regex patterns.

Include Names

# Include resources with names starting with "prod-"
python aws-cleanup.py ec2 full --include-names "prod-*"

# Include resources with names matching multiple patterns
python aws-cleanup.py ec2 full --include-names "prod-*" "myapp-*" "production-*"

# Use regex patterns (must start with ^ or contain .*)
python aws-cleanup.py ec2 full --include-names "^production-.*" ".*-backup"

Exclude Names

# Exclude resources with names starting with "test-"
python aws-cleanup.py ec2 full --exclude-names "test-*"

# Exclude resources with names ending with "-backup"
python aws-cleanup.py s3 full --exclude-names "*-backup"

# Exclude resources with names containing "temp"
python aws-cleanup.py ec2 full --exclude-names "*temp*"

3. Age-Based Filtering

Filter resources based on their creation/launch time.

Minimum Age

# Only include resources older than 7 days
python aws-cleanup.py ec2 full --min-age-days 7

# Only include resources older than 30 days
python aws-cleanup.py rds full --min-age-days 30

Maximum Age

# Only include resources newer than 365 days
python aws-cleanup.py ec2 full --max-age-days 365

# Only include resources between 7 and 30 days old
python aws-cleanup.py ec2 full --min-age-days 7 --max-age-days 30

4. State-Based Filtering

Filter resources based on their current state.

Include States

# Only include running instances
python aws-cleanup.py ec2 full --include-states running

# Only include available volumes
python aws-cleanup.py ec2 full --include-states available

# Only include active services
python aws-cleanup.py ecs full --include-states active

Exclude States

# Exclude stopped instances
python aws-cleanup.py ec2 full --exclude-states stopped terminated

# Exclude deleted resources
python aws-cleanup.py s3 full --exclude-states deleted

5. Size-Based Filtering

Filter resources based on their size (for applicable resources).

Size Filters

# Only include volumes larger than 100GB
python aws-cleanup.py ec2 full --min-size-gb 100

# Only include volumes smaller than 1000GB
python aws-cleanup.py ec2 full --max-size-gb 1000

# Only include volumes between 50GB and 500GB
python aws-cleanup.py ec2 full --min-size-gb 50 --max-size-gb 500

6. Common Use Cases

Clean Up Development Resources

# Clean up all development resources
python aws-cleanup.py ec2 full --include-tags Environment=development

# Clean up test resources but keep production
python aws-cleanup.py ec2 full --include-names "test-*" "dev-*" --exclude-tags Environment=production

Clean Up Old Resources

# Clean up resources older than 30 days
python aws-cleanup.py ec2 full --min-age-days 30

# Clean up old test resources
python aws-cleanup.py ec2 full --include-tags Environment=test --min-age-days 7

Clean Up Stopped Resources

# Clean up all stopped instances
python aws-cleanup.py ec2 full --include-states stopped

# Clean up stopped instances but keep production
python aws-cleanup.py ec2 full --include-states stopped --exclude-tags Environment=production

Clean Up Large Resources

# Clean up large volumes (over 100GB)
python aws-cleanup.py ec2 full --min-size-gb 100

# Clean up large volumes but keep production
python aws-cleanup.py ec2 full --min-size-gb 100 --exclude-tags Environment=production

Clean Up Specific Projects

# Clean up resources for a specific project
python aws-cleanup.py ec2 full --include-tags Project=myproject

# Clean up resources for multiple projects
python aws-cleanup.py ec2 full --include-tags Project=project1 Project=project2

Clean Up Backup Resources

# Clean up backup resources
python aws-cleanup.py s3 full --include-names "*backup*" "*snapshot*"

# Clean up old backup resources
python aws-cleanup.py s3 full --include-names "*backup*" --min-age-days 30

7. Configuration File Filtering

You can also define filters in a configuration file:

filters:
  tags:
    include:
      - "Environment=production"
      - "Project=myproject"
    exclude:
      - "Protected=true"
      - "Critical=true"
  
  names:
    include_patterns:
      - "prod-*"
      - "myapp-*"
    exclude_patterns:
      - "test-*"
      - "dev-*"
  
  age:
    min_age_days: 7
    max_age_days: 365
  
  states:
    include:
      - "running"
      - "available"
    exclude:
      - "stopped"
      - "terminated"

Then use it with:

python aws-cleanup.py ec2 full --config my-config.yaml

8. Safety Tips

Always Use Dry Run First

# Test your filters with dry run
python aws-cleanup.py ec2 full --include-tags Environment=test --dry-run

Start with Specific Filters

# Start with very specific filters
python aws-cleanup.py ec2 full --include-names "test-instance-*" --dry-run

Use Exclude Filters for Safety

# Exclude important resources
python aws-cleanup.py ec2 full --exclude-tags Protected=true Critical=true

Combine Multiple Filters

# Use multiple filters for precision
python aws-cleanup.py ec2 full --include-tags Environment=test --exclude-tags Protected=true --min-age-days 7

9. Debugging Filters

Enable Verbose Logging

# See which resources are filtered out
python aws-cleanup.py ec2 full --include-tags Environment=test --verbose

Check Filter Results

The tool will show you:

Total resources found
Resources after filtering
Which resources were filtered out (in debug mode)

10. Filter Performance

Tag Filters: Fast, uses AWS API filtering
Name Filters: Fast, uses pattern matching
Age Filters: Medium speed, requires date parsing
State Filters: Fast, uses AWS API filtering
Size Filters: Medium speed, requires size calculation

11. Best Practices

Always test with --dry-run first
Use specific filters rather than broad ones
Combine include and exclude filters for precision
Use configuration files for complex filtering
Monitor the filtering results with verbose logging
Start with small, specific cleanup operations
Keep important resources tagged appropriately

This filtering system gives you complete control over which resources are cleaned up, making the tool safe and precise for production use!

Safety Features

Automatic Protection Removal

The tool automatically handles various protection mechanisms:

Service	Protections Removed
EC2	Termination protection, Volume detachment
RDS	Deletion protection, Automated backups
S3	Versioning, Lifecycle policies, Public access blocks
CloudFormation	Termination protection
ECS	Service scaling to 0, Task stopping
ASG	Termination protection, Scaling to 0

Confirmation Prompts

By default, the tool asks for confirmation before deleting each resource:

Delete EC2 instance 'i-1234567890abcdef0'? (y/N): y
Delete S3 bucket 'my-bucket'? (y/N): n

Skip confirmations with --yes:

python aws-cleanup.py ec2 full --yes

Dry Run Mode

Preview what would be deleted without actually performing the deletion:

python aws-cleanup.py ec2 full --dry-run

Sample Output:

[DRY RUN] Would delete instance i-1234567890abcdef0
[DRY RUN] Would delete volume vol-1234567890abcdef0
[DRY RUN] Would delete snapshot snap-1234567890abcdef0

Comprehensive Logging

The tool provides detailed logging at multiple levels:

# Normal logging
python aws-cleanup.py ec2 full

# Verbose logging
python aws-cleanup.py ec2 full --verbose

Log Levels:

INFO: Progress and actions
WARNING: Non-fatal issues
ERROR: Failures
DEBUG: Detailed information (with --verbose)

Command Reference

Basic Syntax

python aws-cleanup.py <service> <mode> [options]

Arguments

Argument	Description	Required
`service`	AWS service (`ec2`, `ecs`, `asg`, `sagemaker`, `elb`, `rds`, `s3`, `cloudformation`)	Yes
`mode`	Cleanup mode (`single`, `multiple`, `full`)	Yes

Options

Option	Description	Default
`--resource-id`	Single resource ID (for single mode)	-
`--resource-ids`	Comma-separated resource IDs (for multiple mode)	-
`--region`	AWS region	`us-east-1`
`--all-regions`	Clean up across all regions (for full mode)	`False`
`--dry-run`	Show what would be deleted without deleting	`False`
`--yes`	Skip confirmation prompts	`False`
`--verbose`	Enable verbose logging	`False`

Service-Specific Examples

EC2 Cleanup

# Delete all EC2 resources (instances, volumes, snapshots, AMIs)
python aws-cleanup.py ec2 full --region us-west-2

# Delete specific EC2 instance
python aws-cleanup.py ec2 single --resource-id i-1234567890abcdef0

# Delete multiple volumes
python aws-cleanup.py ec2 multiple --resource-ids vol-123,vol-456,vol-789

# Delete all EC2 resources across all regions
python aws-cleanup.py ec2 full --all-regions

ECS Cleanup

# Delete all ECS resources (clusters, services, tasks)
python aws-cleanup.py ecs full --region us-east-1

# Delete specific ECS cluster
python aws-cleanup.py ecs single --resource-id my-cluster

# Delete multiple ECS services
python aws-cleanup.py ecs multiple --resource-ids service1,service2

S3 Cleanup

# Delete all S3 buckets (including versioned buckets)
python aws-cleanup.py s3 full --all-regions

# Delete specific S3 bucket
python aws-cleanup.py s3 single --resource-id my-bucket

# Delete multiple S3 buckets
python aws-cleanup.py s3 multiple --resource-ids bucket1,bucket2

RDS Cleanup

# Delete all RDS resources (instances, clusters, snapshots)
python aws-cleanup.py rds full --region us-west-2

# Delete specific RDS instance
python aws-cleanup.py rds single --resource-id my-db-instance

# Delete specific RDS cluster
python aws-cleanup.py rds single --resource-id my-db-cluster

SageMaker Cleanup

# Delete all SageMaker resources
python aws-cleanup.py sagemaker full --region us-east-1

# Delete specific SageMaker notebook
python aws-cleanup.py sagemaker single --resource-id my-notebook

# Delete multiple SageMaker endpoints
python aws-cleanup.py sagemaker multiple --resource-ids endpoint1,endpoint2

Permissions

The tool requires appropriate AWS permissions. Here's a sample IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:*",
                "ecs:*",
                "autoscaling:*",
                "sagemaker:*",
                "elasticloadbalancing:*",
                "rds:*",
                "s3:*",
                "cloudformation:*",
                "sts:GetCallerIdentity"
            ],
            "Resource": "*"
        }
    ]
}

Minimal Permissions (if you want to restrict access):

ec2:Describe*, ec2:ModifyInstanceAttribute, ec2:TerminateInstances, ec2:DeleteVolume, etc.
s3:ListBucket, s3:DeleteObject, s3:DeleteBucket, etc.
Similar patterns for other services

Testing

Test the Installation

# Run the test script
python test_cleanup.py

Test with Dry Run

# Test EC2 cleanup
python aws-cleanup.py ec2 full --dry-run

# Test S3 cleanup
python aws-cleanup.py s3 full --dry-run --region us-west-2

Test Single Resource

# Test with a specific resource
python aws-cleanup.py ec2 single --resource-id i-1234567890abcdef0 --dry-run

Error Handling

The tool is designed to be robust and handle errors gracefully:

Common Error Scenarios

Resource not found: Logs info and continues
Permission denied: Logs error and continues with other resources
Protection enabled: Automatically removes protection and retries
Network issues: Retries with exponential backoff
Invalid resource ID: Logs warning and continues

Error Recovery

Continues processing other resources if one fails
Provides detailed error messages
Skips resources that don't exist
Handles permission errors appropriately

Project Structure

aws-cleanup-tool/
├── aws-cleanup.py              # Main script
├── cleanup_modules/            # Service-specific modules
│   ├── __init__.py
│   ├── base_cleanup.py         # Base class
│   ├── ec2_cleanup.py          # EC2 cleanup
│   ├── ecs_cleanup.py          # ECS cleanup
│   ├── asg_cleanup.py          # Auto Scaling cleanup
│   ├── sagemaker_cleanup.py    # SageMaker cleanup
│   ├── elb_cleanup.py          # Load Balancer cleanup
│   ├── rds_cleanup.py          # RDS cleanup
│   ├── s3_cleanup.py           # S3 cleanup
│   └── cloudformation_cleanup.py # CloudFormation cleanup
├── requirements.txt            # Python dependencies
├── test_cleanup.py             # Test script
└── README.md                   # This file

Contributing

Adding New Services

Create a new module in cleanup_modules/
Inherit from BaseCleanup
Implement required methods:
- get_resource_type()
- get_resources()
- get_resource_id()
- delete_resource()
- handle_protection_removal()
Add the service to the main script

Example New Service Module

from .base_cleanup import BaseCleanup

class NewServiceCleanup(BaseCleanup):
    def get_resource_type(self) -> str:
        return "NewService"
    
    def get_resources(self, region: str, resource_ids: List[str] = None) -> List[Dict[str, Any]]:
        # Implementation here
        pass
    
    # ... other required methods

License

This tool is provided as-is for educational and operational purposes. Use at your own risk and ensure you have appropriate backups before running cleanup operations.

Disclaimer

This tool can delete AWS resources permanently. Always:

Test in a non-production environment first
Ensure you have appropriate backups
Use --dry-run to preview actions
Start with single resource deletions
Verify your AWS credentials and permissions

The authors are not responsible for any data loss or service disruption.

Support

If you encounter issues:

Check the logs for detailed error messages
Verify AWS credentials and permissions
Test with dry run first
Start with single resources before full cleanup
Check the service-specific documentation for your AWS service

Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
cleanup_modules		cleanup_modules
tests		tests
.gitignore		.gitignore
FILTERING_GUIDE.md		FILTERING_GUIDE.md
README.md		README.md
aws-cleanup-config-example.yaml		aws-cleanup-config-example.yaml
aws-cleanup.py		aws-cleanup.py
config.py		config.py
filters.py		filters.py
requirements.txt		requirements.txt
test_cleanup.py		test_cleanup.py

Hyraze/aws-cleanup-tool

Folders and files

Latest commit

History

Repository files navigation

AWS Cleanup Tool

Features

Three Cleanup Modes

Intelligent Protection Removal

Multi-Region Support

Idempotent & Safe

Supported Services

Quick Start

1. Installation

2. Basic Usage

Usage Examples

Single Resource Deletion

Multiple Resource Deletion

Full Cleanup

Dry Run Mode

Skip Confirmations

Advanced Filtering System

1. Tag-Based Filtering

Include Tags

Exclude Tags

2. Name-Based Filtering

Include Names

Exclude Names

3. Age-Based Filtering

Minimum Age

Maximum Age

4. State-Based Filtering

Include States

Exclude States

5. Size-Based Filtering

Size Filters

6. Common Use Cases

Clean Up Development Resources

Clean Up Old Resources

Clean Up Stopped Resources

Clean Up Large Resources

Clean Up Specific Projects

Clean Up Backup Resources

7. Configuration File Filtering

8. Safety Tips

Always Use Dry Run First

Start with Specific Filters

Use Exclude Filters for Safety

Combine Multiple Filters

9. Debugging Filters

Enable Verbose Logging

Check Filter Results

10. Filter Performance

11. Best Practices

Safety Features

Automatic Protection Removal

Confirmation Prompts

Dry Run Mode

Comprehensive Logging

Command Reference

Basic Syntax

Arguments

Options

Service-Specific Examples

EC2 Cleanup

ECS Cleanup

S3 Cleanup

RDS Cleanup

SageMaker Cleanup

Permissions

Testing

Test the Installation

Test with Dry Run

Test Single Resource

Error Handling

Common Error Scenarios

Error Recovery

Project Structure

Contributing

Adding New Services

Packages