🚀 CloudOps/FinOps Runbooks - Enterprise AWS Automation

Enterprise-Grade Production-Ready AWS automation toolkit for DevOps and SRE teams managing Multi-Account Hybrid-Cloud environments at Scale 🏢⚡

Quick Value: Discover, analyze, and optimize AWS resources across multi-account AWS environments with production-validated automation patterns.

Runbooks FinOps & AWS MCP Servers

The hybrid approach (Runbooks CloudOps/FinOps & AWS MCPs) leverages the strengths of both solutions: AWS MCPs for real-time accuracy data access and Runbooks FinOps for business intelligence and visualization, ensuring optimal cost optimization results for your enterprise environment.

🏆 5-Minute Success Path

Installation (30 seconds)

pip install runbooks==1.5.7
runbooks --version

Choose Your Path

Pick a quickstart matching your role:

• 💼 Finance Leaders: CFO Quickstart — Monthly cost visibility + savings opportunities
• 🏗️ Technical Leaders: CTO Quickstart — Cloud Foundations assessment + compliance
• ☁️ CloudOps Engineers: CloudOps Quickstart — Multi-account resource discovery
• 🔄 DevOps Engineers: DevOps Quickstart — Validation + safe operations
• 🚨 SREs: SRE Quickstart — Security baseline + automated remediation

Each quickstart gets you to first working command in <5 minutes.

🎯 Why Runbooks?

📦 Core Modules

Configuration

🎯 Choose Your Setup Path

💡 Quick Decision:

• Have 1 AWS account? → Use Path 1 (Single-Account Setup - 2 minutes)
• Have AWS Organizations with multiple accounts? → Use Path 2 (Multi-Account Setup - 5 minutes)

Path 1: Single-Account Setup (Quickstart - 2 minutes)

For developers, testing, or single AWS account operations:

# Set your AWS profile (ONE profile only)
export AWS_PROFILE="my-account-profile"

# Verify access
aws sts get-caller-identity --profile $AWS_PROFILE

# Expected output:
# {
#   "UserId": "AIDAI...",
#   "Account": "123456789012",
#   "Arn": "arn:aws:iam::123456789012:user/yourname"
# }

Usage Example - Single Account:

# Discover EC2 instances in your account
runbooks inventory collect \
  --profile $AWS_PROFILE \
  --regions ap-southeast-2

# Analyze costs (single account)
runbooks finops analyze-ec2 \
  --profile $AWS_PROFILE \
  --output data/cost-analysis.json

Path 2: Multi-Account Setup (Enterprise - 5 minutes)

For organizations with AWS Organizations and multiple accounts:

# Set up 3 specialized profiles for different AWS APIs
export AWS_BILLING_PROFILE="your-billing-readonly-profile"
export AWS_MANAGEMENT_PROFILE="your-management-readonly-profile"
export AWS_OPERATIONS_PROFILE="your-operations-readonly-profile"

# Why 3 profiles?
# - BILLING: Cost Explorer API requires billing account access
# - MANAGEMENT: AWS Organizations API requires management account access
# - OPERATIONS: Resource discovery across member accounts

# Profile capability matrix (ACTUAL tested results):
# - BILLING: Cost Explorer ✅, Organizations ✅, Multi-account discovery ✅
# - MANAGEMENT: Organizations ✅, Cost Explorer ✅, Account management ✅
# - OPERATIONS: Single-account resources ✅, Limited multi-account ⚠️

Usage Example - Multi-Account:

# Organization-wide resource discovery with cost data
runbooks finops analyze-ec2 \
  --input data/resources.xlsx \
  --billing-profile $AWS_BILLING_PROFILE \
  --management-profile $AWS_MANAGEMENT_PROFILE \
  --operational-profile $AWS_OPERATIONS_PROFILE \
  --enable-cost \
  --include-12month-cost

# Discover resources across all organization accounts
runbooks inventory collect \
  --all-accounts \
  --management-profile $AWS_MANAGEMENT_PROFILE \
  --regions ap-southeast-2,us-east-1

🧰 Core Modules

⚡ Essential Commands Reference

🔍 Discovery & Inventory

# Multi-service resource discovery
runbooks inventory collect -r ec2,s3,rds --profile production

# Cross-account organization scan
runbooks scan --all-accounts --include-cost-analysis

# Specialized discovery operations
runbooks inventory collect -r lambda --include-code-analysis

💰 Cost Management

# Interactive cost dashboard
runbooks finops --profile your-billing-profile

# Cost optimization analysis
runbooks finops --optimize --target-savings 30

# Multi-account cost aggregation
runbooks finops --all-accounts --breakdown-by service,account,region

🔒 Security & Compliance

# Security baseline assessment
runbooks security assess --profile production --language EN

# Multi-framework compliance check
runbooks cfat assess --compliance-framework "AWS Well-Architected"

# Specialized security operations
runbooks security check root_mfa --profile management

⚙️ Resource Operations

# Safe EC2 operations (dry-run by default)
runbooks operate ec2 stop --instance-ids i-1234567890abcdef0 --dry-run

# S3 security hardening
runbooks operate s3 set-public-access-block --account-id 123456789012

# CloudFormation operations
runbooks operate cloudformation move-stack-instances \
  --source-stackset old-baseline --target-stackset new-baseline --dry-run

🎨 CLI Parameter Flexibility (v1.1.10+)

Enhanced UX: All commands now support flexible format specification with short flag support

Triple Alias Pattern

Choose your preferred parameter style - all forms work identically:

Examples - All Three Forms Work

Organization Visualization:

# All three commands produce identical output
runbooks inventory draw-org -f graphviz --profile $MANAGEMENT_PROFILE
runbooks inventory draw-org --format graphviz --profile $MANAGEMENT_PROFILE
runbooks inventory draw-org --export-format graphviz --profile $MANAGEMENT_PROFILE

Cost Analysis Export:

# Choose your preferred style
runbooks finops analyze -f csv --profile $BILLING_PROFILE
runbooks finops analyze --format csv --profile $BILLING_PROFILE
runbooks finops analyze --export-format csv --profile $BILLING_PROFILE

Account Inventory:

# Short form for interactive use (NEW in v1.1.10)
runbooks inventory list-org-accounts -f json --output accounts.json

# Standard form for scripts
runbooks inventory list-org-accounts --format csv --output accounts.csv

# Legacy form (fully supported)
runbooks inventory list-org-accounts --export-format markdown --output accounts.md

Supported Commands (13 Total)

Migration Guide

Zero Breaking Changes: All existing scripts continue working without modification

Adoption Path:

• ✅ Now: All parameter forms work (choose preferred style)
• 💡 Recommended: Adopt -f for interactive CLI usage (faster typing)
• 📝 Scripts: Update at your convenience (no urgency)
• 🔄 Future: v1.2.0 will show deprecation warnings for legacy parameters

🏗️ Architecture Highlights

Modern Stack

• 🐍 Python 3.11+: Modern async capabilities
• ⚡ UV + Ruff: 10x faster dependency resolution & linting
• 🎨 Rich CLI: Beautiful terminal interfaces
• 📊 Pydantic V2: Type-safe data models
• 🔗 boto3: Native AWS SDK integration
• 🤖 MCP Servers: Real-time AWS API access (MCP Specification)

Enterprise Features

• 🔐 Multi-Profile AWS: Seamless account switching
• 🌐 Multi-Language Reports: EN/JP/KR/VN support
• 📈 DORA Metrics: DevOps performance tracking
• 🚨 Safety Controls: Dry-run defaults, approval workflows
• 📊 Executive Dashboards: Business-ready reporting

📚 Documentation

Quick Links

• 🏠 Homepage - Official project website
• 📖 Documentation - Complete guides
• 🐛 Issues - Bug reports & features
• 💬 Discussions - Community support

Enterprise Module Documentation

🔧 Configuration

AWS Profiles Setup

# Environment variables for enterprise setup
export AWS_BILLING_PROFILE="your-billing-readonly-profile"
export AWS_MANAGEMENT_PROFILE="your-management-readonly-profile"
export AWS_OPERATIONS_PROFILE="your-operations-readonly-profile"

# Universal profile usage patterns
runbooks finops --profile $AWS_BILLING_PROFILE      # Cost analysis
runbooks inventory collect --profile $AWS_MANAGEMENT_PROFILE  # Discovery
runbooks operate --profile $AWS_OPERATIONS_PROFILE   # Operations

Advanced Configuration

# Custom configuration directory
export RUNBOOKS_CONFIG_DIR="/path/to/config"

# Performance tuning
export RUNBOOKS_PARALLEL_WORKERS=10
export RUNBOOKS_TIMEOUT=300

🛡️ Security & Compliance

🚦 Roadmap

🔧 Troubleshooting

Configuration Issues

Problem: "I set up 3 profiles but I only have 1 AWS account"

Solution: Single-account users only need 1 profile:

# ✅ CORRECT (Single Account):
export AWS_PROFILE="my-account-profile"
runbooks inventory collect --profile $AWS_PROFILE

# ❌ INCORRECT (don't do this for single account):
export CENTRALISED_OPS_PROFILE="my-account-profile"
export MANAGEMENT_PROFILE="my-account-profile"
export BILLING_PROFILE="my-account-profile"

When to use which setup:

• 1 Profile (AWS_PROFILE): You have a single AWS account for development/testing
• 3 Profiles (MANAGEMENT + BILLING + OPERATIONS): You have AWS Organizations with multiple member accounts

See Configuration section above for detailed setup instructions.

Problem: "Command fails with 'profile not found'"

Solution: Verify your AWS credentials are configured:

# Check if profile exists
aws configure list-profiles

# Verify profile access
aws sts get-caller-identity --profile YOUR_PROFILE_NAME

# Expected output should show Account ID and User ARN

If profile doesn't exist, configure it:

aws configure --profile YOUR_PROFILE_NAME

🆘 Support Options

Community Support (Free)

• 🐛 GitHub Issues - Bug reports & feature requests
• 💬 GitHub Discussions - Community Q&A

Enterprise Support

• 🏢 Professional Services - Custom deployment assistance
• 🎓 Training Programs - Team enablement workshops
• 🛠️ Custom Development - Tailored collector modules
• 📧 Email: https://www.linkedin.com/in/nnthanh/

📄 License

Apache License 2.0 - See LICENSE file for details.

📋 Release Notes

Latest Release: See v1.5.0 Release Notes for detailed changes and migration guide.

🏗️ Built with ❤️ by the xOps team at OceanSoft

Transform your AWS operations from reactive to proactive with enterprise-grade automation 🚀