Inventory Module - Production Quickstart Guide¶

🎯 1. Choose Your Quickstart Path 🚀¶

How many AWS accounts do you manage?

Workflow (Use Case)	Profile Source	Jump To (Quickstart)	Persona
🚀 `workflow-single-account`	`AWS_PROFILE` (1 profile)	🟢 Single-Account Quickstart - 5 min	💻 Developer, 🔧 SRE
🏢 `workflow-multi-account`	`CENTRALISED_OPS_PROFILE` `MANAGEMENT_PROFILE` `BILLING_PROFILE`	🟡 Multi-Account Quickstart - 15 min	💼 Executive, 💰 FinOps, 🏗️ Architect

What's your primary goal?
- Quick resource check → Scenario 1: EC2 with Costs
- Cost optimization → Scenario 2: Decommission Candidates
- Compliance audit → Scenario 3: Organization Validation
- Network analysis → Scenario 4: VPC Discovery
Test with 1 region with --regions ap-southeast-2 or run production discovery scan (all enabled regions)

2. Prerequisites (Quick Check)¶

Required & Recommended

✅ AWS CLI configured with SSO profiles
✅ runbooks package installed (pip install runbooks or uv pip install runbooks)
✅ Access to AWS profiles with appropriate permissions

☑️ ${AWS_PROFILE}: Your AWS SSO profile or configured profile

☑️ MANAGEMENT_PROFILE: AWS Organizations management account profile (for multi-account)
☑️ BILLING_PROFILE: Cost Explorer billing profile ( Cost Explorer enabled for financial intelligence)
☑️ CENTRALISED_OPS_PROFILE: Centralized operations/Resource Explorer profile (Resource Explorer aggregator index for cross-account discovery)

N instances/accounts/resources = Varies by your environment
$XX.XX = Calculated based on your usage
${ACCOUNT_ID} = Your 12-digit AWS account identifier
123456789012 = Placeholder for AWS account ID

Profile Requirements Matrix

Category	Single-Account	Multi-Account	Required Profile(s)	Compatibility
1️⃣ Discovery 🔍	✅ Full	✅ Full	`AWS_PROFILE` / `CENTRALISED_OPS_PROFILE`	Both
2️⃣ Organizations 🏢	⚠️ Limited	✅ Full	`MANAGEMENT_PROFILE`	Multi only
3️⃣ Cost Enrichment 💰	✅ Account-level	✅ Org-wide	`AWS_PROFILE` / `BILLING_PROFILE`	Both (different scope)
4️⃣ Activity & Scoring 📊	✅ Full	✅ Full	`AWS_PROFILE` / `CENTRALISED_OPS_PROFILE`	Both
5️⃣ Pipelines 🚀	✅ workflow-single	✅ workflow-multi	1 profile / 3 profiles	Both
6️⃣ Security 🔒	✅ Full	✅ Full	`AWS_PROFILE` / `MANAGEMENT_PROFILE`	Both
7️⃣ Workflows ⚡	✅ Single-account	✅ Multi-account	1 profile / 3 profiles	Both
8️⃣ Validation ✅	✅ Full	✅ Full	`AWS_PROFILE` / `BILLING_PROFILE`	Both
9️⃣ Utilities 🛠️	✅ Full	✅ Full	None (no AWS required)	Both

## Verify runbooks installation. Expected: runbooks, version 1.1.22 (or higher)
runbooks --version

## Verify AWS CLI access. Expected: JSON with Account, UserId, Arn
aws sts get-caller-identity --profile ${AWS_PROFILE}

## Verify Task runner. Expected: Task version X.X.X
task --version

📋 Inventory Command Categories - Quick Reference¶

🔍 Click to view all 9 command categories (40 operations)

Category	Task Count	Business Value	Profile Required	Badge
1️⃣ Discovery	6	Multi-account resource discovery (88 AWS types)	`CENTRALISED_OPS_PROFILE`	🔐
2️⃣ Organizations	6	Organization structure & account management	`MANAGEMENT_PROFILE`	🔐
3️⃣ Cost & Enrichment	2	Financial intelligence & account metadata	`BILLING_PROFILE` + `MANAGEMENT_PROFILE`	🔐
4️⃣ Activity & Scoring	3	Decommission candidate identification	`CENTRALISED_OPS_PROFILE` + `BILLING_PROFILE`	🔐
5️⃣ Pipeline Operations	3	Automated multi-layer enrichment workflows	Multiple profiles	🔐
6️⃣ Validation	2	MCP cross-validation & accuracy checks (≥99.5%)	`BILLING_PROFILE`	🔐
7️⃣ Workflow Templates	2	Best-practice single/multi-account patterns	Multiple profiles	🔐
8️⃣ Utility Operations	3	Helper commands & output management	Any	✅
9️⃣ Integration	13	Advanced patterns & troubleshooting	Varies	📚

Legend:

✅ No AWS Required - Executable without AWS credentials
🔐 AWS Credentials Required - Requires configured AWS profile
📚 Documentation - Reference material and patterns

3. 💼 Business Scenarios¶

Scenario 1: Executive Cost Visibility 💼¶

Question: "Show me all resources with costs"

🚀 Single-Account Solution (expand for details)

Scope: Account-level visibility

Commands:

task -t Taskfile.inventory.yaml workflow-single-account

Output: Resources in your account with 12-month costs

Categories Used: 1️⃣ Discovery 🔍 + 3️⃣ Cost 💰 + 7️⃣ Workflows ⚡

runbooks finops dashboard --executive --profile $AWS_PROFILE

runbooks finops dashboard --output-format=tree --profile $AWS_PROFILE

# Example usage combinations:
runbooks finops dashboard --top-n 5 --summary-mode table
runbooks finops dashboard --output-format tree --tree-style nested
runbooks finops dashboard --top-n 20 --summary-mode both --cost-threshold 100

runbooks finops dashboard --executive --profile $AWS_PROFILE

🏢 Multi-Account Solution (expand for details)

Scope: Organization-wide visibility

Commands:

task -t Taskfile.inventory.yaml workflow-multi-account

Output: Resources across all accounts with org context

Categories Used: 1️⃣ Discovery 🔍 + 2️⃣ Organizations 🏢 + 3️⃣ Cost 💰 + 7️⃣ Workflows ⚡

Scenario 2: FinOps Decommission Identification 💰¶

Question: "Which resources can we decommission for savings?"

🚀 Single-Account Solution (expand for details)

Commands:

task -t Taskfile.inventory.yaml pipeline-5-layer
# Filter MUST tier instances
awk -F',' 'NR==1 || $30=="MUST"' data/outputs/ec2-scored.csv > /tmp/must-tier.csv

Savings: Calculated for single account

Categories Used: 1️⃣ Discovery 🔍 + 3️⃣ Cost 💰 + 4️⃣ Activity/Scoring 📊

🏢 Multi-Account Solution (expand for details)

Commands:

task -t Taskfile.inventory.yaml pipeline-5-layer
# Filter org-wide MUST tier
awk -F',' 'NR==1 || $30=="MUST"' data/outputs/ec2-scored.csv > /tmp/must-tier-org.csv

Savings: Calculated across organization with account ownership

Categories Used: 1️⃣ Discovery 🔍 + 2️⃣ Organizations 🏢 + 3️⃣ Cost 💰 + 4️⃣ Activity/Scoring 📊

Scenario 3: SRE Security Baseline Validation 🔧¶

Question: "Validate security and compliance posture"

🚀 Single-Account Solution (expand for details)

Commands:

task -t Taskfile.inventory.yaml check-security-baseline

Scope: Single account audit

Categories Used: 6️⃣ Security 🔒 + 8️⃣ Validation ✅

🏢 Multi-Account Solution (expand for details)

Commands:

task -t Taskfile.inventory.yaml check-control-tower
task -t Taskfile.inventory.yaml check-landing-zone

Scope: Org-wide compliance validation

Categories Used: 6️⃣ Security 🔒 + 2️⃣ Organizations 🏢 + 8️⃣ Validation ✅

Scenario 4: Architect Network Analysis 🏗️¶

Question: "Analyze VPC architecture and network topology"

🚀 Single-Account Solution (expand for details)

Commands:

task -t Taskfile.inventory.yaml list-vpcs

Output: VPC architecture diagram for account

Categories Used: 9️⃣ Integration 🛠️ (VPC)

🏢 Multi-Account Solution (expand for details)

Commands:

task -t Taskfile.inventory.yaml draw-org
task -t Taskfile.inventory.yaml list-vpcs --all-accounts

Output: Organization network topology with cross-account flows

Categories Used: 9️⃣ Integration 🛠️ (VPC) + 2️⃣ Organizations 🏢

Scenario 5: Developer Testing 💻¶

Question: "Test infrastructure changes before production"

🚀 Single-Account Solution (Preferred) ✅

Commands:

task -t Taskfile.inventory.yaml discover-ec2
task -t Taskfile.inventory.yaml discover-rds
task -t Taskfile.inventory.yaml discover-lambda

Scope: Development account inventory

Note: ✅ Primary use case for single-account workflows

Categories Used: 1️⃣ Discovery 🔍 + 9️⃣ Utilities 🛠️

🏢 Multi-Account Solution (Not Typical)

Note: Multi-account discovery not typical for developer testing. Use single-account workflows for development environments.

Common Use Cases¶

Use Case 1: Cost Optimization Initiative¶

Objective: Identify idle EC2 instances for decommissioning

Commands:

# Step 1: Complete 5-layer pipeline
task -t Taskfile.inventory.yaml pipeline-5-layer

# Step 2: Filter MUST tier instances (80-100 score)
awk -F',' 'NR==1 || $30=="MUST"' data/outputs/ec2-scored.csv > /tmp/ec2-decommission-must.csv

# Step 3: Review decommission signals
head -20 /tmp/ec2-decommission-must.csv | cut -d',' -f1,5,15,30,31,32

# Expected Columns:
# resource_arn, resource_id, monthly_cost, decommission_tier, decommission_score, signal_breakdown

Business Outcome: - ✅ Prioritized list of N instances (MUST tier) for immediate decommissioning - ✅ $XX.XX/month savings ($YY.YY/year calculated) - ✅ Evidence-based justification (Compute Optimizer idle findings + low CPU/network + no CloudTrail activity)

Use Case 2: Compliance Audit¶

Objective: Validate resource ownership and tagging compliance

Commands:

# Step 1: Discover resources with account metadata
task -t Taskfile.inventory.yaml discover-ec2
task -t Taskfile.inventory.yaml enrich-accounts

# Step 2: Check account ownership population
tail -n +2 data/outputs/ec2-org.csv | cut -d',' -f8,9,13 | head -10

# Expected Columns:
# account_name, account_email, account_owner

Business Outcome: - ✅ Complete resource-to-account mapping - ✅ Identify untagged resources (ownership gaps) - ✅ Compliance reporting for governance audits

Use Case 3: Multi-Resource Discovery¶

Objective: Discover EC2, RDS, WorkSpaces, and Lambda across organization

Commands:

# Discover all resource types in parallel
task -t Taskfile.inventory.yaml discover-ec2 &
task -t Taskfile.inventory.yaml discover-rds &
task -t Taskfile.inventory.yaml discover-workspaces &
task -t Taskfile.inventory.yaml discover-lambda &
wait

# View all discoveries
ls -lh data/outputs/*-discovered.csv

# Expected Output:
# ec2-discovered.csv        (N resources)
# rds-discovered.csv        (N resources)
# workspaces-discovered.csv (N resources)
# lambda-discovered.csv     (N resources)

Business Outcome: - ✅ Complete infrastructure inventory across 4 service types - ✅ Foundation for multi-service cost optimization - ✅ N total resources discovered (varies by environment)

💼 Business Scenarios - Executable Examples¶

Scenario 1: Discover All EC2 Instances with Cost Analysis¶

Business Value: Identify decommission candidates, optimize EC2 spend

Single-Account Execution¶

## Step 1: Verify profile access. Expected: JSON with Account, UserId, Arn (12-digit account ID visible)
aws sts get-caller-identity --profile ${AWS_PROFILE}

## Step 2: Execute discovery + cost workflow. Expected: 4-layer pipeline (Discovery → Costs → Activity → Scoring)
## Duration: 5-10 minutes depending on resource count
task -t Taskfile.inventory.yaml workflow-single-account

## Step 3: Validate results. Expected: N+1 lines (N instances + 1 header row)
wc -l data/outputs/ec2-scored.csv

## Step 4: Preview key columns. Expected: Columns showing resource_arn, instance_id, monthly_cost, decommission_tier, score
head -5 data/outputs/ec2-scored.csv | cut -d',' -f1,5,15,30,31

Expected Output Pattern:

🔍 Layer 1: Discovery (N EC2 instances discovered)
💰 Layer 3: Cost Enrichment (12-month cost data added)
📊 Layer 4: Activity Analysis (CloudTrail + CloudWatch + SSM + Compute Optimizer)
🎯 Layer 5: Scoring (MUST/SHOULD/COULD/KEEP tiers assigned)
✅ Pipeline complete: data/outputs/ec2-scored.csv

Multi-Account Execution¶

## Step 1: Verify all 3 profiles. 

## Expected: Management account details
aws sts get-caller-identity --profile ${MANAGEMENT_PROFILE}
## Expected: Billing account details
aws sts get-caller-identity --profile ${BILLING_PROFILE}
## Expected: Centralized ops account details
aws sts get-caller-identity --profile ${CENTRALISED_OPS_PROFILE}

## Step 2: Execute 5-layer workflow. Duration: 10-20 minutes depending on account count
## Expected: 5-layer pipeline (Discovery → Organizations → Costs → Activity → Scoring)
task -t Taskfile.inventory.yaml workflow-multi-account

## Step 3: Validate organization enrichment. Expected: Count of active accounts in organization
grep -c "ACTIVE" data/outputs/ec2-org.csv

## Step 4: Check decommission tier distribution. Expected:
tail -n +2 data/outputs/ec2-scored.csv | cut -d',' -f30 | sort | uniq -c
## Expected:
##   X MUST      (high-confidence decommissioning)
##   Y SHOULD    (strong candidates)
##   Z COULD     (possible optimization)
##   W KEEP      (active resources)

Troubleshooting:

Empty CSV (only header): No resources in account/region → Try --all-regions flag
Permission denied: Add resource-explorer-2:Search permission to profile
Cost data missing: Wait 24 hours for Cost Explorer availability on new resources

Scenario 2: Decommission Candidates for Cost Savings¶

Business Value: Identify high-confidence idle resources with calculated savings

Single-Account Execution¶

# Step 1: Verify Cost Explorer access
aws ce get-cost-and-usage \
  --time-period Start=2025-10-01,End=2025-11-01 \
  --granularity MONTHLY \
  --metrics AmortizedCost \
  --profile ${AWS_PROFILE}
# Expected: JSON with cost results (not AccessDenied)

# Step 2: Run complete pipeline with scoring
task -t Taskfile.inventory.yaml pipeline-5-layer
# Expected: 5-layer pipeline execution
# Duration: 10-15 minutes

# Step 3: Filter MUST tier candidates (score 80-100)
awk -F',' 'NR==1 || $30=="MUST"' data/outputs/ec2-scored.csv > /tmp/must-tier.csv
# Expected: Header + N MUST tier instances

# Step 4: Calculate monthly savings potential
awk -F',' 'NR>1 && $30=="MUST" {sum+=$15; count++} END {
  printf "MUST tier: %d instances = $%.2f/month savings\n", count, sum
}' data/outputs/ec2-scored.csv
# Expected: MUST tier: N instances = $XXX.XX/month savings

# Step 5: Review decommission signals
head -10 /tmp/must-tier.csv | cut -d',' -f5,15,30,31,32
# Expected: instance_id, monthly_cost, tier, score, signal_breakdown

Expected Output Pattern:

MUST tier: 8 instances = $1,247.50/month savings
SHOULD tier: 15 instances = $2,368.75/month savings
Total potential: $3,616.25/month = $43,395/year

Multi-Account Execution¶

# Step 1: Verify all profiles have access
aws sts get-caller-identity --profile ${MANAGEMENT_PROFILE}
aws sts get-caller-identity --profile ${BILLING_PROFILE}
aws sts get-caller-identity --profile ${CENTRALISED_OPS_PROFILE}
# Expected: Success for all 3 profiles

# Step 2: Execute org-wide pipeline
task -t Taskfile.inventory.yaml workflow-multi-account
# Expected: 5-layer pipeline with Organizations enrichment
# Duration: 15-25 minutes

# Step 3: Filter org-wide MUST tier with account ownership
awk -F',' 'NR==1 || $30=="MUST"' data/outputs/ec2-scored.csv > /tmp/must-tier-org.csv
# Expected: Header + N MUST tier instances across all accounts

# Step 4: Calculate savings by account
awk -F',' 'NR>1 && $30=="MUST" {
  accounts[$7]+=$15; count[$7]++
} END {
  for (account in accounts) {
    printf "%s: %d instances = $%.2f/month\n", account, count[account], accounts[account]
  }
}' data/outputs/ec2-scored.csv | sort -t'$' -k2 -rn
# Expected: Account-level savings breakdown sorted by cost

# Step 5: Generate executive summary
tail -n +2 data/outputs/ec2-scored.csv | \
  awk -F',' '{tiers[$30]++; costs[$30]+=$15} END {
    printf "Tier Distribution:\n"
    for (tier in tiers) printf "  %s: %d instances ($%.2f/month)\n", tier, tiers[tier], costs[tier]
  }'
# Expected: Tier distribution with instance counts and costs

Troubleshooting: - No cost data: Verify Cost Explorer enabled → aws ce describe-cost-category-definition --profile ${BILLING_PROFILE} - Zero MUST tier: Resources are active → Review SHOULD tier for candidates - High costs but low scores: Active workloads → Focus on right-sizing instead

Scenario 3: Organization Validation for Compliance¶

Business Value: Complete account inventory for governance and audit readiness

Single-Account Execution¶

# Note: Organizations features limited in single-account mode
# Use multi-account workflow for full organization validation

# Step 1: Verify account details
aws sts get-caller-identity --profile ${AWS_PROFILE}
# Expected: Single account details

# Step 2: Discover resources with basic metadata
task -t Taskfile.inventory.yaml discover-ec2
# Expected: Resource discovery for single account
# Duration: 2-3 minutes

# Step 3: List discovered resources
task -t Taskfile.inventory.yaml list-outputs
# Expected: ec2-discovered.csv with N rows

Note: For full organization validation, use multi-account workflow below.

Multi-Account Execution¶

# Step 1: Verify Organizations access
aws organizations describe-organization --profile ${MANAGEMENT_PROFILE}
# Expected: JSON with organization details (Id, MasterAccountId, FeatureSet)

# Step 2: List all organization accounts
task -t Taskfile.inventory.yaml list-accounts
# Expected: Table with Account ID, Name, Email, Status
# Duration: 30-60 seconds

# Step 3: Visualize organization hierarchy
task -t Taskfile.inventory.yaml draw-org
# Expected: Rich tree visualization of OU structure
# Duration: 30-60 seconds

# Step 4: Validate Landing Zone configuration
task -t Taskfile.inventory.yaml check-landing-zone
# Expected: Landing Zone status and version
# Duration: 30-60 seconds

# Step 5: Check Control Tower status
task -t Taskfile.inventory.yaml check-control-tower
# Expected: Control Tower deployment status
# Duration: 30-60 seconds

# Step 6: Verify account metadata completeness
task -t Taskfile.inventory.yaml workflow-multi-account
grep -E "account_name|account_owner|organizational_unit" data/outputs/ec2-org.csv | head -5
# Expected: Populated metadata fields for accountability

Expected Output Pattern:

📋 Organization Accounts: N accounts
├── Root (ou-xxxx-xxxxxxxx)
│   ├── Production OU (ou-xxxx-xxxxxxxx)
│   │   ├── Account: prod-workload-1 (123456789012)
│   │   └── Account: prod-workload-2 (234567890123)
│   └── Development OU (ou-xxxx-xxxxxxxx)
│       └── Account: dev-sandbox (345678901234)
✅ Control Tower: ACTIVE (version X.X)
✅ Landing Zone: DEPLOYED

Troubleshooting: - Access denied on list-accounts: Add organizations:ListAccounts permission to ${MANAGEMENT_PROFILE} - Empty organization tree: Verify Organizations enabled → aws organizations describe-organization - Landing Zone not found: Control Tower not deployed → Manual deployment required

Scenario 4: VPC Network Discovery and Analysis¶

Business Value: Network topology analysis, VPC architecture validation

Single-Account Execution¶

# Step 1: Verify EC2 VPC permissions
aws ec2 describe-vpcs --profile ${AWS_PROFILE}
# Expected: JSON array of VPCs (not AccessDenied)

# Step 2: Discover VPC resources (using resource-explorer)
runbooks inventory resource-explorer \
  --resource-type vpc \
  --profile ${AWS_PROFILE} \
  --output /tmp/vpcs-discovered.csv
# Expected: CSV with VPC details
# Duration: 1-2 minutes

# Step 3: Count VPCs and subnets
wc -l /tmp/vpcs-discovered.csv
# Expected: N+1 lines (N VPCs + header)

# Step 4: Analyze VPC CIDR blocks
tail -n +2 /tmp/vpcs-discovered.csv | cut -d',' -f5,6 | sort -u
# Expected: Unique VPC CIDR ranges

Expected Output Pattern:

VPC Discovery Results:
- N VPCs discovered
- X public subnets
- Y private subnets
- Z availability zones

Multi-Account Execution¶

# Step 1: Verify multi-account VPC access
aws ec2 describe-vpcs --profile ${CENTRALISED_OPS_PROFILE}
# Expected: VPCs from aggregator index

# Step 2: Discover org-wide VPC resources
runbooks inventory resource-explorer \
  --resource-type vpc \
  --all-profiles \
  --profile ${CENTRALISED_OPS_PROFILE} \
  --output /tmp/vpcs-org-wide.csv
# Expected: CSV with VPCs across all accounts
# Duration: 3-5 minutes

# Step 3: Analyze VPC distribution by account
tail -n +2 /tmp/vpcs-org-wide.csv | cut -d',' -f2 | sort | uniq -c
# Expected: VPC count per account
#   5 123456789012
#   3 234567890123
#   2 345678901234

# Step 4: Check for CIDR overlaps (compliance risk)
tail -n +2 /tmp/vpcs-org-wide.csv | cut -d',' -f5 | sort | uniq -d
# Expected: Empty output (no overlaps) or list of duplicate CIDRs

# Step 5: Visualize network topology with organization context
task -t Taskfile.inventory.yaml draw-org
# Expected: Organization tree showing account relationships

Troubleshooting: - No VPCs found: Check regions enabled → Add --all-regions flag - CIDR overlaps detected: Review VPC peering/transit gateway compatibility - Permission denied: Add ec2:DescribeVpcs permission to profile

Scenario 5: Developer Testing and Validation¶

Business Value: Test infrastructure changes before production deployment

Single-Account Execution (Preferred for Development)¶

# Step 1: Verify development account access
aws sts get-caller-identity --profile ${AWS_PROFILE}
# Expected: Development/sandbox account details

# Step 2: Quick resource discovery (EC2, RDS, Lambda)
task -t Taskfile.inventory.yaml discover-ec2 &
task -t Taskfile.inventory.yaml discover-rds &
task -t Taskfile.inventory.yaml discover-lambda &
wait
# Expected: 3 CSV files in data/outputs/
# Duration: 2-4 minutes (parallel execution)

# Step 3: Verify discovery results
task -t Taskfile.inventory.yaml list-outputs
# Expected: List showing ec2-discovered.csv, rds-discovered.csv, lambda-discovered.csv

# Step 4: Count resources by type
for file in data/outputs/*-discovered.csv; do
  echo "$(basename $file): $(tail -n +2 $file | wc -l) resources"
done
# Expected:
#   ec2-discovered.csv: N resources
#   rds-discovered.csv: N resources
#   lambda-discovered.csv: N resources

# Step 5: Validate resource types supported
task -t Taskfile.inventory.yaml list-resource-types
# Expected: 88 supported AWS resource types (no AWS credentials required)

Expected Output Pattern:

Development Environment Inventory:
✅ EC2: N instances discovered
✅ RDS: N databases discovered
✅ Lambda: N functions discovered
Total: X resources across 3 service types

Note: Multi-account discovery not typical for developer testing. Use single-account workflows for dev environments.

Troubleshooting: - Resource count mismatch: Verify region matches deployment → Add --regions ${REGION} flag - CSV empty (header only): Resources not deployed yet → Expected for clean environments - Permission denied: Add read permissions to dev profile → See IAM policy templates in Appendix A

Single Account Quickstart (5 minutes)¶

Use Case: Development, testing, or standalone AWS account

Step 1: Configure Profile (30 seconds)¶

# Set all profiles to your account
export CENTRALISED_OPS_PROFILE=${AWS_PROFILE}
export MANAGEMENT_PROFILE=${AWS_PROFILE}
export BILLING_PROFILE=${AWS_PROFILE}

# Verify profile access
aws sts get-caller-identity --profile ${CENTRALISED_OPS_PROFILE}
# Expected: JSON with Account (12-digit), UserId, Arn

Step 2: Discover Resources (2 minutes)¶

# Discover EC2 instances
task -t Taskfile.inventory.yaml discover-ec2

# Expected Output:
# 🔍 Discovering EC2 instances...
# ✅ EC2 discovery complete data/outputs/ec2-discovered.csv
#       N data/outputs/ec2-discovered.csv

What happened: - Resource Explorer searched your AWS account - Found N EC2 instances (varies by environment) - Saved to CSV file for further enrichment

Step 3: Enrich with Costs (2 minutes)¶

# Add organization metadata
task -t Taskfile.inventory.yaml enrich-accounts

# Add 12-month cost data
task -t Taskfile.inventory.yaml enrich-costs

# Expected Output:
# 💰 Enriching with cost data (12-month history)...
# ✅ Cost enrichment complete data/outputs/ec2-cost.csv

What happened: - Added AWS Organizations account metadata - Enriched with 12-month cost trends from Cost Explorer - Calculated monthly cost averages and annual totals

Step 4: View Results (1 minute)¶

# Display pipeline summary
task -t Taskfile.inventory.yaml pipeline-summary

# Expected Output:
# Layer                          | Rows | Cols | Status
# ------------------------------------------------------------
# Layer 1 Discovery             |  N   |   10 | ✅
# Layer 2 Organizations         |  N   |   20 | ✅
# Layer 3 Costs                 |  N   |   23 | ✅
# ✅ Pipeline execution complete!

Business Value Delivered: - ✅ Complete EC2 inventory with account context - ✅ 12-month cost trends for financial planning - ✅ Export-ready CSV files for stakeholder reporting - ✅ Foundation for activity analysis and decommissioning

Quick Wins¶

View cost totals:

# Calculate total monthly costs
tail -n +2 data/outputs/ec2-cost.csv | cut -d',' -f15 | \
  awk '{sum+=$1} END {printf "Total Monthly Cost: $%.2f\n", sum}'

# Expected: Total Monthly Cost varies by environment

Export for Excel:

# CSV files ready for Excel/Google Sheets
open data/outputs/ec2-cost.csv

# Or copy to shared drive
cp data/outputs/ec2-cost.csv /path/to/shared/drive/

Multi-Account Quickstart (15 minutes)¶

Use Case: AWS Organizations with centralized operations

Step 1: Verify Multi-Account Setup (1 minute)¶

# Check Organizations access
aws organizations describe-organization --profile ${MANAGEMENT_PROFILE}
# Expected: JSON with Organization Id, MasterAccountId, FeatureSet

# Check Resource Explorer aggregator
aws resource-explorer-2 list-indexes \
  --profile ${CENTRALISED_OPS_PROFILE} \
  --region ap-southeast-2
# Expected: At least one index with Type: AGGREGATOR

Step 2: List Organization Accounts (1 minute)¶

# Discover all AWS accounts in organization
task -t Taskfile.inventory.yaml list-accounts

# Expected Output:
# 📋 Listing AWS accounts...
# Account ID: ${ACCOUNT_ID}, Name: Production, Email: [email protected]
# Account ID: 987654321098, Name: Development, Email: [email protected]
# [... N more accounts ...]
# ✅ Account list complete

Business Value: - ✅ Complete account inventory for governance - ✅ Email contacts for accountability tracking - ✅ Foundation for multi-account resource discovery

Step 3: Run Complete 5-Layer Pipeline (5 minutes)¶

# Execute complete enrichment pipeline for EC2
task -t Taskfile.inventory.yaml pipeline-5-layer

# Pipeline Progress:
# 🔍 Layer 1: Resource Discovery... (2 min)
# 🏢 Layer 2: Organizations Enrichment... (30 sec)
# 💰 Layer 3: Cost Enrichment... (1 min)
# 📊 Layer 4: Activity Analysis... (1.5 min)
# 🎯 Layer 5: Decommission Scoring... (10 sec)

What Each Layer Delivers:

Layer	Time	Purpose	Output Columns	Business Value
1. Discovery	2 min	Find resources across all accounts	10	Complete resource inventory
2. Organizations	30 sec	Add account metadata (owner, WBS, cost center)	+10	Accountability and chargeback
3. Costs	1 min	12-month cost trends and forecasts	+3	Financial planning and budgeting
4. Activity	1.5 min	CloudTrail, CloudWatch, SSM, Compute Optimizer	+13	Idle resource detection
5. Scoring	10 sec	MUST/SHOULD/COULD/KEEP decommission tiers	+3	Prioritized cost reduction roadmap

Step 4: Analyze Results (2 minutes)¶

# View final pipeline summary
task -t Taskfile.inventory.yaml pipeline-summary

# Expected Output:
# Layer                          | Rows | Cols | Status
# ------------------------------------------------------------
# Layer 1 Discovery             |  N   |   10 | ✅
# Layer 2 Organizations         |  N   |   20 | ✅
# Layer 3 Costs                 |  N   |   23 | ✅
# Layer 4 Activity              |  N   |   36 | ✅
# Layer 5 Scored                |  N   |   39 | ✅
# ✅ Pipeline execution complete!

Decommission Tier Distribution:

# Analyze decommission recommendations
tail -n +2 data/outputs/ec2-scored.csv | cut -d',' -f30 | sort | uniq -c

# Expected Output:
#   X MUST      (high-confidence decommissioning)
#   Y SHOULD    (strong candidates, requires review)
#   Z COULD     (possible optimization, low priority)
#   W KEEP      (active resources, do not decommission)

Financial Impact:

# Calculate monthly savings potential
awk -F',' 'NR>1 && $30=="MUST" {sum+=$15; count++} END {
  printf "MUST tier: %d instances = $%.2f/month savings\n", count, sum
}' data/outputs/ec2-scored.csv

awk -F',' 'NR>1 && $30=="SHOULD" {sum+=$15; count++} END {
  printf "SHOULD tier: %d instances = $%.2f/month savings\n", count, sum
}' data/outputs/ec2-scored.csv

# Expected Output:
# MUST tier: X instances = $XXX.XX/month savings
# SHOULD tier: Y instances = $YYY.YY/month savings
# Total potential: $ZZZ.ZZ/month = $AAA,AAA/year

Troubleshooting Quick Reference¶

Issue: No Resources Found¶

Symptoms:

✅ EC2 discovery complete data/outputs/ec2-discovered.csv
      1 data/outputs/ec2-discovered.csv  (header only, no data)

Solutions: 1. Verify profile has access to resources:

aws ec2 describe-instances --profile ${CENTRALISED_OPS_PROFILE}
# Expected: JSON with Reservations array containing instances (not empty)

Check Resource Explorer configuration:

aws resource-explorer-2 list-indexes --profile ${CENTRALISED_OPS_PROFILE}
# Expected: At least one index with Type: AGGREGATOR or LOCAL

Verify region contains resources:

# Try different region
aws ec2 describe-instances --profile ${CENTRALISED_OPS_PROFILE} --region us-east-1
# Expected: Instances in us-east-1 region

Issue: Cost Data Missing¶

Symptoms:

💰 Enriching with cost data (12-month history)...
WARNING: No cost data available for account ${ACCOUNT_ID}

Solutions: 1. Wait for Cost Explorer data availability (24 hours for new accounts) 2. Verify billing profile permissions:

aws ce get-cost-and-usage --profile ${BILLING_PROFILE} \
  --time-period Start=2025-10-01,End=2025-11-01 \
  --granularity MONTHLY \
  --metrics AmortizedCost
# Expected: JSON with ResultsByTime array (not AccessDenied)

Use shorter time period for testing:

task -t Taskfile.inventory.yaml enrich-costs MONTHS=1

Issue: SSO Token Expired¶

Symptoms:

An error occurred (ExpiredToken) when calling the DescribeInstances operation

Solution:

# Re-authenticate with SSO
aws sso login --profile ${CENTRALISED_OPS_PROFILE}

# Verify token
aws sts get-caller-identity --profile ${CENTRALISED_OPS_PROFILE}
# Expected: Account details JSON (not ExpiredToken error)

Issue: Permission Denied¶

Symptoms:

An error occurred (AccessDenied) when calling the Search operation

Solution:

# Check required permissions
# Layer 1: resource-explorer-2:Search
# Layer 2: organizations:ListAccounts
# Layer 3: ce:GetCostAndUsage
# Layer 4: cloudtrail:LookupEvents, cloudwatch:GetMetricStatistics

# Contact AWS administrator to add missing permissions

Next Steps¶

Expand to Other Resources¶

# Discover RDS databases
task -t Taskfile.inventory.yaml discover-rds
task -t Taskfile.inventory.yaml pipeline-5-layer RESOURCE_TYPE=rds

# Discover WorkSpaces
task -t Taskfile.inventory.yaml pipeline-5-layer-workspaces

# Discover S3 buckets
task -t Taskfile.inventory.yaml discover-s3

Automate with CI/CD¶

# .github/workflows/inventory-discovery.yml
name: Weekly Inventory Discovery

on:
  schedule:
    - cron: '0 0 * * 1'  # Every Monday at midnight

jobs:
  discover:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install runbooks
        run: pip install runbooks
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
      - name: Run inventory discovery
        run: task -t Taskfile.inventory.yaml pipeline-5-layer
      - name: Upload results
        uses: actions/upload-artifact@v3
        with:
          name: inventory-results
          path: data/outputs/ec2-scored.csv

Advanced Analysis¶

Jupyter Notebook Integration:

import pandas as pd

# Load scored results
df = pd.read_csv('data/outputs/ec2-scored.csv')

# Analyze by decommission tier
tier_distribution = df['decommission_tier'].value_counts()
print(tier_distribution)

# Calculate savings by tier
tier_savings = df.groupby('decommission_tier')['monthly_cost'].sum()
print(f"MUST tier savings: ${tier_savings['MUST']:.2f}/month")

Dashboard Visualization (PowerBI/Tableau):

# Export to Power BI compatible format
cp data/outputs/ec2-scored.csv ~/PowerBI/data/

# Or convert to Excel
pip install openpyxl
python << 'EOF'
import pandas as pd
df = pd.read_csv('data/outputs/ec2-scored.csv')
df.to_excel('ec2-scored.xlsx', index=False)
EOF

Help & Support¶

Documentation¶

Configuration Guide: /docs-runbooks/inventory/configuration-guide.md
Resource Explorer Guide: /docs-runbooks/inventory/resource-explorer.md
Inventory README: /src/runbooks/inventory/README.md

Commands Reference¶

# Show all available tasks
task -t Taskfile.inventory.yaml --list

# Display configured profiles
task -t Taskfile.inventory.yaml show-profiles

# View generated outputs
task -t Taskfile.inventory.yaml list-outputs

Common Tasks¶

Task	Command	Time
Single resource discovery	`task discover-ec2`	2 min
Complete 5-layer pipeline	`task pipeline-5-layer`	5 min
List organization accounts	`task list-accounts`	1 min
Generate org diagram	`task draw-org`	1 min
Clean output directory	`task clean-outputs`	5 sec

Quick Start Status: Production Ready ✅ Validated With: Multi-account AWS Organizations (varies by deployment) Performance: <5 minutes complete 5-layer pipeline Accuracy: ≥99.5% (MCP validated) Last Updated: 2025-11-09