AWS FinOps Monthly Report
Generate a cross-validated AWS cost report with Rich CLI output, interactive Vizro dashboard, CxO executive summary, and stakeholder email — for a single account or a full multi-account Landing Zone — in under 15 minutes.
Quickstart (2 steps)
# Install
pip install runbooks
# Single account (use python -m if runbooks resolves to ADLC framework CLI)
uv run python -m runbooks.main finops dashboard --profile $AWS_PROFILE --timeframe monthly
# Multi-account Landing Zone
uv run python -m runbooks.main finops dashboard --all --timeframe monthly
# CxO persona
uv run python -m runbooks.main finops dashboard --all --timeframe monthly --mode cfo
5W1H
| Question | Answer |
|---|---|
| Who | FinOps team, CloudOps engineers, CFO/CTO/CxO stakeholders |
| What | Monthly AWS cost report: Rich CLI summary, Vizro dashboard, CxO executive summary, cross-validation evidence |
| When | 1st of each month (prior month) + mid-month budget check |
| Where | Local terminal → git-tracked projects/<project>/finops-reports/YYYY-MM/ |
| Why | Evidence-based spend visibility, savings identification, stakeholder alignment |
| How | uv run python -m runbooks.main finops dashboard reads Cost Explorer (org-wide) + Config Aggregator (inventory) → 4-way SSOT cross-validation |
Prerequisites
| Requirement | How to Verify |
|---|---|
| Python 3.11+ | python --version |
| runbooks installed | pip install runbooks then runbooks --version |
| AWS CLI configured | aws --version |
| Authenticated | aws sso login --profile YOUR_PROFILE then aws sts get-caller-identity |
The ADLC framework registers a runbooks Node.js CLI. If which runbooks shows a Node.js path, use the Python module invocation shown below. In a dedicated Python virtualenv, pip install runbooks registers the correct entry point.
Environment Variables (Single Account)
export AWS_PROFILE=your-billing-readonly
export AWS_REGION=ap-southeast-2
export AWS_DEFAULT_REGION=ap-southeast-2
Environment Variables (Multi-Account Landing Zone)
export AWS_MANAGEMENT_PROFILE=your-management-readonly # Organizations API + --all mode trigger
export BILLING_PROFILE=your-billing-readonly # Cost Explorer billing queries
export CENTRALISED_OPS_PROFILE=your-ops-readonly # CloudWatch, EC2, resource APIs
export AWS_REGION=ap-southeast-2
Monthly Process (6 Steps)
Step 1: Authenticate
# Single account
aws sso login --profile $AWS_PROFILE
# Multi-account LZ (authenticate all three profiles)
aws sso login --profile $BILLING_PROFILE
aws sso login --profile $AWS_MANAGEMENT_PROFILE
aws sso login --profile $CENTRALISED_OPS_PROFILE
Step 2: Run FinOps Report
Single account:
uv run python -m runbooks.main finops dashboard \
--profile $AWS_PROFILE \
--timeframe monthly
Multi-account Landing Zone:
uv run python -m runbooks.main finops dashboard \
--all \
--billing-profile $BILLING_PROFILE \
--ops-profile $CENTRALISED_OPS_PROFILE \
--timeframe monthly
The Rich CLI renders a formatted cost summary table in the terminal. For the full 7-file pipeline (HTML dashboard, CxO report, email, CSVs, cross-validation JSON), use the /finops:aws-monthly ADLC command (see Deliverables below).
Use --mode to tailor the CxO executive summary to your audience:
| Mode | Audience | Focus |
|---|---|---|
--mode cfo | CFO, Finance | Spend vs budget, savings pipeline, unit economics |
--mode cto | CTO, Engineering | Service breakdown, architecture cost drivers, rightsizing |
--mode executive | Board, Executive | KPIs, trend, strategic recommendations |
--mode technical | CloudOps, FinOps | Resource-level detail, reservation gaps, anomalies |
--mode architect | Architect, SRE | Multi-account patterns, dependency costs |
--mode ceo | CEO, Board | Top 3 KPIs, strategic trend |
--mode sre | SRE, Ops | Anomaly detection, cost spike alerts, performance thresholds |
uv run python -m runbooks.main finops dashboard --all --timeframe monthly --mode cfo
Step 3: Review Vizro Dashboard
Open aws-finops-dashboard.html in your browser. The Vizro-powered dashboard includes:
- Budget gauge (actual vs target)
- Account cost breakdown (bar + pie charts)
- Service spend treemap
- Month-over-month trend line
- Cost Explorer recommendations panel
The interactive dashboard is built with Plotly/Vizro. All charts are filterable and exportable. No server required — open the HTML file directly.
Step 4: Review CxO Executive Summary
Open aws-cxo-report.md. Verify:
- Total spend matches Cost Explorer org-wide total (not CLI profile-scoped)
- Savings recommendations are sourced from Cost Explorer + Trusted Advisor (with recommendation IDs)
- Account breakdown covers all accounts in the Organization
Never include savings estimates from pricing pages, calculations, or agent-generated numbers. Cost Explorer and Trusted Advisor recommendations are evidence-based and include recommendation IDs for independent verification.
Step 5: Cross-Validate with 4-Way SSOT
Every monthly report includes a cross-validation check comparing four sources:
L1: Cost Explorer (org-wide billing) ← AUTHORITATIVE
L2: AWS CLI per-profile totals ← PROFILE-SCOPED (may be partial)
L3: Config Aggregator account count ← INVENTORY VALIDATION
L4: Trusted Advisor findings ← RECOMMENDATIONS LAYER
The cross-validation evidence is saved as aws-cross-validation-YYYY-MM-DD.json with:
- L1–L4 values and variance percentages
- Root cause for any delta
- 5-why analysis for material gaps
When L2 total < L1 total: An account exists in the Organization that the current profile cannot access. Document the gap with account-level reconciliation.
Use aws configservice list-discovered-resources against the Aggregator index to enumerate all accounts and resources before running cost queries. This prevents the NARROW_SEARCH_SCOPE anti-pattern (searching 3 of 67 accounts manually when org-wide tools exist).
Anti-pattern: FINOPS_API_SSOT_MISMATCH — presenting profile-scoped CLI totals as authoritative without stating the RBAC/SCP caveat.
Step 6: Send Email + Archive Evidence
Copy aws-email.txt to your email client. Attach:
aws-finops-dashboard.html(interactive Vizro dashboard)aws-cxo-report.md(executive summary)account-costs.csv+service-breakdown.csv
# Evidence is auto-saved to:
# Git-tracked: projects/<project>/finops-reports/YYYY-MM/
# Ephemeral: tmp/cloud-infrastructure/finops/aws/
Deliverables
Quick CLI (uv run python -m runbooks.main finops dashboard)
| Output | Format | Description |
|---|---|---|
| Terminal table | Rich CLI | Service costs, account breakdown, MoM trends |
| Excel workbook | XLSX (via --export) | Multi-sheet cost analysis |
Full Pipeline (/finops:aws-monthly)
| File | Format | Audience | Content |
|---|---|---|---|
aws-finops-dashboard.html | HTML (Vizro) | CxO, FinOps | Interactive charts, KPIs, budget gauge |
aws-cxo-report.md | Markdown | CFO, CTO | Executive summary, top accounts, services |
aws-email.txt | Plain text | Stakeholders | Copy-paste email with key figures |
account-costs.csv | CSV | Analytics | Per-account breakdown |
service-breakdown.csv | CSV | Analytics | Per-service breakdown |
aws-cross-validation.json | JSON | QA | 4-way SSOT evidence |
Configuration
| Parameter | CLI Flag | Environment Variable | Description |
|---|---|---|---|
| Single profile | --profile | AWS_PROFILE | SSO profile for single-account use |
| Org-wide mode | --all | AWS_MANAGEMENT_PROFILE | Trigger org-wide mode; Organizations API profile |
| Billing profile | --billing-profile | BILLING_PROFILE | Cost Explorer billing queries |
| Operations profile | --ops-profile | CENTRALISED_OPS_PROFILE | CloudWatch, EC2, resource APIs |
| Timeframe | --timeframe | — | monthly, quarterly, or YYYY-MM |
| Persona mode | --mode | — | cfo, cto, executive, technical, architect, ceo, sre |
| Region | — | AWS_REGION | Primary region (default: ap-southeast-2) |
Monthly Cadence
| Timing | Action | Command |
|---|---|---|
| 1st of month | Authenticate all profiles | aws sso login --profile ... |
| 1st of month | Generate prior-month report | uv run python -m runbooks.main finops dashboard --all --timeframe monthly |
| 1st of month | Review Cost Explorer recommendations | Manual (AWS Console > Cost Management) |
| 1st of month | Send stakeholder email | Copy aws-email.txt |
| Mid-month | Check current month MTD spend | uv run python -m runbooks.main finops dashboard --all --timeframe monthly |
| Mid-month | Review prior month final | uv run python -m runbooks.main finops dashboard --all --previous-month |