🚀 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)

uv tool install runbooks        # recommended (isolated, on PATH)
# or: pipx install runbooks
# or: pip install runbooks
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

Every module README under src/runbooks/<module>/ is a short pointer to its hub in docs/modules/ and its generated CLI reference in docs/reference/cli/.

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, RDS and S3 in your account
runbooks inventory collect --profile $AWS_PROFILE --resources ec2,rds,s3

# Analyze EC2 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 the 3 Landing Zone hub profiles once; `--all-profile` reads them
export AWS_MANAGEMENT_PROFILE="your-management-readonly-profile"   # Organizations API
export AWS_BILLING_PROFILE="your-billing-readonly-profile"         # Cost Explorer API
export AWS_OPERATIONS_PROFILE="your-operations-readonly-profile"   # Config Aggregator / Resource Explorer

The API a command calls decides which hub profile --all-profile resolves to (Organizations → management, Cost Explorer → billing, org-wide discovery → operations). Details: docs/reference/profile-semantics.md.

Usage Example - Multi-Account:

# Org-wide cost dashboard (Cost Explorer via $AWS_BILLING_PROFILE)
runbooks finops dashboard --all-profile --mode executive --top-n 10

# Org-wide EC2 decommission scoring from an inventory export
runbooks finops ec2-decommission-analysis --all-profile --input data/resources.xlsx

# Discover resources across all organization accounts (Config Aggregator via $AWS_OPERATIONS_PROFILE)
runbooks inventory collect --all-profile --all-regions

# List accounts (Organizations via $AWS_MANAGEMENT_PROFILE)
runbooks inventory list-org-accounts --all-profile --format json --output accounts.json

⚡ Essential Commands Reference

Every command and flag below exists today; confirm with runbooks <group> <command> --help.

🔍 Discovery & Inventory

# Multi-service resource discovery
runbooks inventory collect --profile $AWS_PROFILE --resources ec2,s3,rds --csv

# Org-wide discovery through the Config Aggregator
runbooks inventory config-aggregator --all-profile --resource-types AWS::Lambda::Function

# Organization structure as a Mermaid diagram
runbooks inventory draw-org --all-profile --format mermaid

💰 Cost Management

# Multi-account cost dashboard
runbooks finops dashboard --all-profile --timeframe monthly

# Orphaned resources in one account
runbooks finops detect-orphans --profile $AWS_PROFILE --resource-type ebs

# Savings Plans + RI recommendations
runbooks finops optimize-savings-plans --all-profile --lookback-days 30

🔒 Security & Compliance

# Security baseline assessment
runbooks security assess --profile $AWS_PROFILE --framework soc2 --language EN

# Well-Architected assessment across all pillars
runbooks cfat assess --all-profile --all-pillars

# Findings for one host (Security Hub + GuardDuty + Inspector)
runbooks security host-findings --profile $AWS_PROFILE --resource-id i-1234567890abcdef0

⚙️ Resource Operations

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

# S3 bucket with encryption, versioning and public-access block
runbooks operate s3 create-bucket --profile $AWS_PROFILE --bucket-name my-bucket --encryption --versioning --public-access-block

# CloudFormation deployment
runbooks operate cloudformation deploy --profile $AWS_PROFILE --stack-name app --template-file app.yaml --dry-run

🏗️ 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

# Landing Zone hub profiles (read by --all-profile)
export AWS_MANAGEMENT_PROFILE="your-management-readonly-profile"
export AWS_BILLING_PROFILE="your-billing-readonly-profile"
export AWS_OPERATIONS_PROFILE="your-operations-readonly-profile"

# Two flags only
runbooks finops dashboard --all-profile              # org-wide (hub profiles above)
runbooks inventory collect --profile $AWS_PROFILE    # one workload account

The older per-purpose profile flags (billing / management / ops) still parse with a deprecation warning and are removed in the next major version; new scripts use the two flags above.

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

🔧 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 AWS_OPERATIONS_PROFILE="my-account-profile"
export AWS_MANAGEMENT_PROFILE="my-account-profile"
export AWS_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

See CHANGELOG.md for the current release and migration notes.

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

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