ECR Inventory REAMD

gistfile1.txt

# ECR Image Inventory Script

A comprehensive Python tool for analyzing Docker images in Amazon ECR repositories, showing which images are currently in use by ECS services and which are candidates for cleanup.

## 🎯 Purpose

Managing ECR repositories can be challenging when you have multiple services and frequent deployments. This script helps you:

- **Identify which images are actively used** by ECS services and task definitions
- **Find cleanup candidates** based on age and usage patterns
- **Estimate storage savings** from removing unused images
- **Export detailed inventory** for analysis and reporting

## 🚀 Features

- ✅ **Smart Classification**: Categorizes images as Referenced, Unreferenced, or Garbage candidates
- ✅ **Multi-Source Analysis**: Checks ECS services, task definitions, and CodeDeploy deployments
- ✅ **Flexible Output**: Supports both formatted table and CSV export
- ✅ **Configurable Thresholds**: Adjustable garbage age threshold (default: 7 days)
- ✅ **Error Handling**: Gracefully handles missing CodeDeploy applications and other edge cases
- ✅ **Quiet Mode**: Suppress warnings for automated usage

## 📊 Image Classifications

### 🟢 **REFERENCED**
Images currently in use by:
- Running ECS services
- Current task definitions
- Active CodeDeploy deployments

**Action**: ❌ Never delete - these power your live services

### 🟡 **UNREFERENCED** 
Images not currently in use but younger than the garbage age threshold.

**Action**: ⚠️ Keep for rollbacks - useful for quick rollbacks if current deployment fails

### 🔴 **GARBAGE**
Images not in use and older than the garbage age threshold.

**Action**: ✅ Safe to delete - prime cleanup candidates

## 🛠️ Requirements

```bash
pip install boto3 tabulate
```

**AWS Permissions Required:**
- `ecr:DescribeRepositories`
- `ecr:DescribeImages`
- `ecs:ListClusters`
- `ecs:DescribeServices`
- `ecs:ListTaskDefinitions`
- `ecs:DescribeTaskDefinition`
- `codedeploy:GetApplication`
- `codedeploy:GetDeploymentGroup`
- `codedeploy:ListDeployments`
- `codedeploy:GetDeployment`

## 📖 Usage

### Basic Usage
```bash
# Analyze ECR images with default 7-day garbage threshold
python3 ecr-inventory.py --region us-west-2
```

### Export to CSV
```bash
# Export detailed inventory to CSV
python3 ecr-inventory.py --format csv --output ecr_inventory.csv
```

### Custom Garbage Age
```bash
# Conservative cleanup (14-day threshold)
python3 ecr-inventory.py --garbage-age 14

# Aggressive cleanup (3-day threshold)
python3 ecr-inventory.py --garbage-age 3 --quiet
```

### All Options
```bash
python3 ecr-inventory.py --help
```

## 📋 Sample Output

```
🔍 ECR Image Inventory for AWS ECS Environment
Region: us-west-2
================================================================================

📊 Analyzing image usage...
Analyzing service: my-app
Analyzing service: api-gateway
Analyzing service: worker-service

📦 Scanning ECR repositories...
Scanning ECR repository: my-app
Scanning ECR repository: api-gateway
Scanning ECR repository: worker-service

📋 ECR Image Inventory (45 images)
Total size: 8.32 GB
Garbage age threshold: 7 days

+-------------+----------+----------+-----+----------+-----------+------------------+
| Repository  | Tag      | Digest   | Age | Size     | Status    | Used By          |
+=============+==========+==========+=====+==========+===========+==================+
| my-app      | v1.2.3   | sha256:a | 1d  | 245.1 MB | 🟢 REF     | ECS Service: ... |
| my-app      | v1.2.2   | sha256:b | 3d  | 244.8 MB | 🟡 UNREF   | None             |
| my-app      | <untagged| sha256:c | 12d | 243.2 MB | 🔴 GARBAGE | None             |
+-------------+----------+----------+-----+----------+-----------+------------------+

📊 Image Status Summary:
  🟢 Referenced images:     8 (17.8%) - Currently in use by ECS/TaskDef
  🟡 Unreferenced images:  15 (33.3%) - Not in use, age < 7 days
  🔴 Garbage candidates:   22 (48.9%) - Not in use, age ≥ 7 days

💰 Garbage cleanup potential: 3.45 GB (22 images)
```

## 🔧 Configuration

### Environment Variables
```bash
export AWS_REGION=us-west-2
export AWS_PROFILE=my-profile
```

### AWS CLI Configuration
```bash
aws configure set region us-west-2
aws configure set output json
```

## 📈 Use Cases

### 1. Regular Cleanup Maintenance
```bash
# Weekly cleanup of images older than 14 days
python3 ecr-inventory.py --garbage-age 14 --format csv --output weekly_cleanup.csv
```

### 2. Storage Cost Analysis
```bash
# Identify storage savings opportunities
python3 ecr-inventory.py --garbage-age 7 --format csv --output cost_analysis.csv
```

### 3. Automated Cleanup Pipeline
```bash
# Generate cleanup candidates for automation
python3 ecr-inventory.py --quiet --garbage-age 30 --format csv --output cleanup_candidates.csv
```

### 4. Compliance Reporting
```bash
# Generate comprehensive inventory for compliance
python3 ecr-inventory.py --format csv --output compliance_report.csv
```

## 🔍 CSV Output Fields

When using `--format csv`, the output includes these fields:

| Field | Description |
|-------|-------------|
| `repository` | ECR repository name |
| `tag` | Image tag (or `<untagged>`) |
| `digest` | Shortened image digest |
| `full_digest` | Complete image digest |
| `age_days` | Age in days since push |
| `size_mb` | Image size in MB |
| `size_bytes` | Image size in bytes |
| `status` | REFERENCED/UNREFERENCED/GARBAGE |
| `is_referenced` | Boolean: currently in use |
| `primary_usage` | Primary usage description |
| `all_usage` | All usage descriptions |
| `image_uri` | Complete image URI |
| `pushed_at` | ISO timestamp of push |
| `is_tagged` | Boolean: has tags |

## ⚠️ Important Notes

### Safety Considerations
- **Always test in non-production first**
- **Verify garbage candidates before deletion**
- **Consider keeping recent images for rollbacks**
- **Check for external references** (CI/CD, documentation, etc.)

### Performance
- Script analyzes all ECR repositories in the region
- Large environments may take several minutes
- Use `--quiet` flag to reduce output in automated scenarios

### Limitations
- Only analyzes ECS-based usage (not Lambda, Batch, etc.)
- CodeDeploy analysis requires inline AppSpec content
- Does not check external references outside AWS

## 🤝 Contributing

This script was developed for the Muppet Platform but is designed to be generic for any ECS environment. Feel free to adapt it for your specific needs.

### Common Customizations
- Modify cluster naming patterns in `get_image_usage_details()`
- Adjust task definition retention in `_analyze_task_definitions()`
- Add support for other AWS services (Lambda, Batch, etc.)

## 📄 License

MIT License - feel free to use and modify for your organization.

## 🔗 Related Tools

- [AWS ECR Lifecycle Policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/LifecyclePolicies.html)
- [ECR Image Scanning](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-scanning.html)
- [ECS Task Definition Management](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html)

---

**💡 Pro Tip**: Run this script regularly (weekly/monthly) to maintain clean ECR repositories and optimize storage costs!