Skip to content

Runbooks - Quickstart Guide

1. Choose Your Path

Setup Time Personas Jump To
Tier 1: Single Account 2 min Developer, SRE Single Account
Tier 2: Multi-Account Landing Zone 5 min FinOps, Architect Multi-Account
Tier 3: Enterprise Cross-Validated 15 min CFO, CTO, Compliance Enterprise

2. Prerequisites

Required (all tiers)
  • runbooks v1.3.17+ installed: pip install runbooks (or uv pip install runbooks)
  • AWS CLI configured with SSO profiles
  • At least one active AWS SSO session
## Verify installation. Expected: runbooks, version 1.3.17 (or higher)
runbooks --version

## Verify AWS access. Expected: JSON with Account, UserId, Arn
aws sts get-caller-identity --profile $AWS_PROFILE
Profile Requirements by Tier
Profile Variable Purpose Required By
AWS_PROFILE Single-account operations Tier 1
AWS_BILLING_PROFILE Cost Explorer (billing-readonly) Tier 2, 3
AWS_MANAGEMENT_PROFILE AWS Organizations (management-readonly) Tier 2, 3
AWS_OPERATIONS_PROFILE Resource discovery (operations-readonly) Tier 2, 3

Tier 1: Single Account (2 min)

Persona: Developer or SRE doing a quick cost and resource check on one account.

pip install runbooks  # or: uv pip install runbooks
export AWS_PROFILE="your-profile"

## Confirm version
runbooks --version

## Run the FinOps dashboard for your account
runbooks finops dashboard --profile $AWS_PROFILE
Expected output [illustrative example] 
runbooks v1.3.17
FinOps Dashboard — Account: [Account ID] (your-region)
─────────────────────────────────────────────────
Top Services by Cost (MTD)
  EC2       [Monthly cost]
  RDS       [Monthly cost]
  S3        [Monthly cost]
─────────────────────────────────────────────────
Total MTD:  [Total from Cost Explorer]

Tier 2: Multi-Account Landing Zone (5 min)

Persona: FinOps engineer or cloud architect managing a multi-account AWS Landing Zone.

export AWS_BILLING_PROFILE="billing-readonly"
export AWS_MANAGEMENT_PROFILE="management-readonly"
export AWS_OPERATIONS_PROFILE="operations-readonly"

## FinOps: monthly cost summary exported as JSON and CSV
runbooks finops dashboard \
  --profile $AWS_BILLING_PROFILE \
  --timeframe monthly \
  --export json \
  --export csv

## Inventory: collect EC2, RDS, S3 across the operations account
runbooks inventory collect \
  --profile $AWS_OPERATIONS_PROFILE \
  --resources ec2 \
  --resources rds \
  --resources s3 \
  --csv
Expected output (finops dashboard) 
FinOps Dashboard — Multi-Account (monthly)
─────────────────────────────────────────────────────────────
Account                   MTD Cost    MoM Change
billing-account           $18,420      +3.2%
operations-account        $ 9,110      -1.1%
sandbox-account           $   840      +12%
─────────────────────────────────────────────────────────────
Organisation Total:       $28,370
Exports: finops-dashboard.json, finops-dashboard.csv
Azure support 
export AZURE_SUBSCRIPTION_ID="your-subscription-id"
runbooks finops azure monthly

Tier 3: Enterprise Cross-Validated (15 min)

Persona: Enterprise architect, CFO, or compliance team requiring MCP-validated results at 99.5% accuracy.

export AWS_BILLING_PROFILE="billing-readonly"
export AWS_OPERATIONS_PROFILE="operations-readonly"

## Step 1: MCP-validated FinOps dashboard (≥99.5% accuracy gate)
runbooks finops dashboard \
  --profile $AWS_BILLING_PROFILE \
  --validation-level mcp \
  --export json

## Step 2: Cross-validate inventory against MCP (EC2, threshold 99.5%)
runbooks inventory validate-mcp \
  --resource-type ec2 \
  --profile $AWS_OPERATIONS_PROFILE \
  --threshold 99.5

## Step 3: Architect-mode activity analysis
runbooks finops dashboard \
  --profile $AWS_BILLING_PROFILE \
  --activity-analysis \
  --mode architect

## Step 4: Executive report (markdown export)
runbooks finops dashboard \
  --profile $AWS_BILLING_PROFILE \
  --mode executive \
  --export markdown

## Step 5: SRE report with anomaly detection
runbooks finops dashboard \
  --profile $AWS_BILLING_PROFILE \
  --mode sre \
  --validation-level mcp
Expected output (MCP validation) 
MCP Cross-Validation — EC2 (ap-southeast-2)
─────────────────────────────────────────────────────────────
Native API:   N instances
MCP result:   N instances
Accuracy:     100.0% ✅  (threshold: 99.5%)
─────────────────────────────────────────────────────────────
Validation PASSED. Evidence written to tmp/runbooks/cross-validation/

3. Real-World Example: 4-Way Cross-Validation Results

Scenario: Enterprise estate with 68 AWS accounts, 276,604 cloud resources discovered via real-time 4-source cross-validation.

Methodology

Source Purpose Profile Example Query
Cost Explorer Monthly run-rate + tagging coverage $AWS_BILLING_PROFILE aws ce get-cost-and-usage --group-by Type=TAG
Organizations Account count + policy ground truth $AWS_MANAGEMENT_PROFILE aws organizations list-accounts
Resource Explorer Organization-wide resource discovery $AWS_OPERATIONS_PROFILE Cross-account ARN aggregator
Config Aggregator Compliance rate + resource count $AWS_OPERATIONS_PROFILE aws config describe-configuration-aggregator

Accuracy: All 4 sources return data consistently. 0 cross-source contradictions detected. Account count reconciles: 68 org accounts = 67 billed (1 zero-spend account). Resource count: 276,604 total discovered. Run-rate: significant monthly spend identified via Cost Explorer.

Persona Cards — Key Numbers & Gate Status

CEO: Data-Loss Exposure

The Risk: 52 of 68 accounts (76.5%) have no AWS Backup vault — a single region-wide disaster has no automated recovery path for over three-quarters of your workload.

Metric Value Gate
Accounts with zero backup 52 / 68 FAIL
Backup vault coverage 16 / 68 (23.5%) BELOW TARGET
Path to close Org backup policy attachment (1 policy, propagates to all 66 active accounts) 90 days

CFO: Cost Attribution Crisis

The Problem: $143,495 monthly run-rate, but $122,395 (85.3%) is unattributed. Your finance team cannot link cloud spend to any product line or business unit.

Metric Value Gate
Monthly cloud spend Multi-account consolidated ACTIVE
Unattributed spend Majority of monthly spend (85%+) FAIL
Tagged spend (4 apps) Minority (14.7%) BELOW SHOWBACK THRESHOLD
Top driver EC2, Tax, and RDS clusters visible in Cost Explorer VISIBILITY REQUIRED

CTO: Patch Compliance Collapse

The Alert: Only 8 of 76 Config patch evaluations are compliant (10.5% pass rate). Most compute resources are running without verified security patches.

Metric Value Gate
Patch compliance 8 / 76 evaluations = 10.5% FAIL
CTO target >80% NOT MET
Trend Down from 11.7% in prior snapshot — flat to declining without intervention AT RISK
Recovery path Patch Manager baseline + scheduled maintenance windows (Weeks 5–12) WITHIN LANDING ZONE PHASE 2

CDO: Discovery Completeness

The Validation: Four independent AWS data sources were queried in real-time. All returned data. No access denials. No silent-zero errors. The estate's discoverable resource count is trustworthy.

Metric Value Status
Total resources discovered 276,604 VERIFIED
Organization accounts 68 GROUND TRUTH
Active accounts 66 ✅ HEALTHY
Config rule compliance 51.4% MEASURED
Cross-source contradictions 0 ✅ CONSISTENT

CSO: Backup & Detection Gaps

The Vulnerabilities: 52 accounts (76.5%) have no AWS Backup vault. Backup policy type is enabled at the org root, but zero backup policies have been created — meaning no org-wide enforcement pathway exists. GuardDuty and SecurityHub are active but coverage cannot be verified from the 3 authorized profiles (delegated admin resides in a separate account).

Control Status Evidence
Backup vaults 16/68 accounts (23.5%) FAIL — BC Stage 3
Backup policy at root Enabled, 0 policies created BLOCKED PATH
GuardDuty Enabled, centrally delegated ✅ ACTIVE
SecurityHub Enabled, centrally delegated ✅ ACTIVE
Recovery path Single policy attachment propagates to all 66 accounts 1 Policy Write = 100% Coverage

4. Troubleshooting

SSO session expired 
Error: Token has expired and refresh failed

Fix: Re-authenticate with AWS SSO.

aws sso login --profile $AWS_PROFILE
## For multi-account setups, login to each profile:
aws sso login --profile $AWS_BILLING_PROFILE
aws sso login --profile $AWS_OPERATIONS_PROFILE
Wrong region — no results 
No resources found

Fix: Specify your primary region explicitly.

runbooks finops dashboard --profile $AWS_PROFILE --regions ap-southeast-2
Missing Cost Explorer permissions 
Error: AccessDeniedException — ce:GetCostAndUsage

Fix: The billing profile requires ce:GetCostAndUsage and ce:GetCostForecast. Ask your AWS administrator to attach the AWSBillingReadOnlyAccess managed policy to the SSO permission set.

MCP validation fails (SRE mode)

Use --validation-level basic as a fallback until MCP validation is stable in your environment.

runbooks finops dashboard --profile $AWS_BILLING_PROFILE --validation-level basic

5. Next Steps

Goal Reference
Cloud Foundations by role Functional Area Catalog ← Copy your area's command or /adlc prompt
Full FinOps command options FinOps CLI Reference
Full Inventory command options Inventory CLI Reference
All 115 CLI commands All Commands
FinOps Dashboard deep-dive FinOps Dashboard
Getting started guide CLI Getting Started