runbooks inventory workspaces¶

Auto-generated from runbooks inventory workspaces --help on 2026-05-21. Source of truth: runbooks PyPI package v1.3.22

Usage: runbooks inventory workspaces [OPTIONS]

  6-phase WorkSpaces investigation: discovery, metadata, security, network,
  compliance, summary.

  Phase 1: workspaces:DescribeWorkspaces -- user, state, compute type, running
  mode Phase 2: Bundle type, directory, OS type Phase 3: Volume encryption, IP
  access control, last connection Phase 4: Directory VPC/subnet, security
  groups Phase 5: Auto-stop timeout, protocol (WSP vs PCoIP), running mode
  Phase 6: Cost optimisation analysis and risk summary

  READONLY -- no mutations.

  Examples:     runbooks inventory workspaces --all-profile $AWS_OPERATIONS_PROFILE
  --workspace-id ws-abc123     runbooks inventory workspaces --workspace-id
  ws-abc123 --region $AWS_DEFAULT_REGION --output json

Options:
  --all-profile TEXT           AWS profile for centralised-ops account (env:
                               AWS_OPERATIONS_PROFILE). Resolves in order:
                               CLI arg > $AWS_OPERATIONS_PROFILE > $AWS_PROFILE.
                               See aws-profile-semantics.md Rule 1.
  -p, --profile TEXT           AWS profile name (fallback; default: from
                               AWS_PROFILE env var)
  --workspace-id WORKSPACE_ID  WorkSpace ID to investigate (e.g. ws-abc123def)
                               [required]
  --region TEXT                AWS region (default: $AWS_DEFAULT_REGION)
  --output [table|json]        Output format (default: table)
  --help                       Show this message and exit.

A2 Auto-Sync · runbooks workspaces collect --help¶

$ runbooks workspaces collect --help
Usage: runbooks workspaces collect [OPTIONS]

  Discover all WorkSpaces across managed accounts. Per-account collection
  with cost allocation and decommission scoring.

  READONLY -- no mutations.

  Examples:
    runbooks workspaces collect --all-profile $AWS_MANAGEMENT_PROFILE
    runbooks workspaces collect --account-ids ${AWS_ACCOUNT_ID},${AWS_ACCOUNT_ID_2} --output tmp/ws/
    runbooks workspaces collect --quiet

Options:
  --profile TEXT           AWS profile for single-account mode (env:
                           AWS_PROFILE). Takes precedence over
                           --all-profile. Region-bound queries.
  --all-profile TEXT       AWS profile for multi-account fan-out (env:
                           AWS_MANAGEMENT_PROFILE). Uses Organizations
                           list_accounts; per-workload profiles from
                           ~/.aws/config. See aws-profile-semantics.md
                           Rule 2.
  --account-ids TEXT       Comma-separated account ID subset. Overrides
                           Organizations list_accounts. Used for
                           incident triage (known scope).
  --output PATH            CSV output directory (default:
                           tmp/cloudops/workspaces/). Filename pattern:
                           collect-YYYY-MM-DD.csv
  --quiet                  Suppress Rich terminal output. Useful for
                           cron/CI pipelines.
  --help                   Show this message and exit.

Governance Posture Snapshot¶

WorkSpaces is your virtual desktop CI fleet. 122 WorkSpaces across 7 workload accounts (b2b-energy baseline). Discovery + decommission scoring + monthly cost rollup feed the CMDB service map and FinOps savings dashboard.

(verdict thresholds: 🟢 = on target · 🟡 = warning, review · 🔴 = breach, action required)

Overview¶

This command performs a 6-phase investigation of AWS WorkSpaces across discovery, metadata, security, network, compliance, and cost optimization.

Data Coverage: Supports 122+ WorkSpaces across 7 accounts (sourced from enterprise CI data). All examples use environment variables or generic account descriptions—no hardcoded AWS account IDs.

Two Approaches to WorkSpaces Discovery¶

Approach A1: Single Investigate¶

Profile Semantics: Uses $AWS_OPERATIONS_PROFILE — the centralised-ops account where cross-account WorkSpaces investigation APIs are pre-authorized.

Basic Usage¶

# Set the centralised-ops profile
export AWS_OPERATIONS_PROFILE=<your-operations-profile>

# Investigate a single WorkSpace
runbooks inventory workspaces \
  --all-profile $AWS_OPERATIONS_PROFILE \
  --workspace-id ws-abc123def456

Output (6-Phase Analysis)¶

The command returns:

Examples¶

Primary approach: using centralised-ops account¶

# Set operations profile environment variable
export AWS_OPERATIONS_PROFILE=<your-operations-profile>

# Investigate a WorkSpace with 6-phase analysis
runbooks inventory workspaces --all-profile $AWS_OPERATIONS_PROFILE --workspace-id ws-12345abcde

Fallback: using default profile¶

# Investigate a WorkSpace using default AWS profile
runbooks inventory workspaces --workspace-id ws-12345abcde

JSON output format¶

# Generate JSON output for processing or integration
runbooks inventory workspaces \
  --all-profile $AWS_OPERATIONS_PROFILE \
  --workspace-id ws-12345abcde \
  --output json

Multi-region investigation¶

# Investigate WorkSpace in a specific region
runbooks inventory workspaces \
  --all-profile $AWS_OPERATIONS_PROFILE \
  --workspace-id ws-12345abcde \
  --region $AWS_DEFAULT_REGION

Approach A2 · Org-Wide Collect (Canonical)¶

# Single command. No bash loop. No --next-token bugs. No raw aws CLI.
runbooks workspaces collect \
  --all-profile ${AWS_MANAGEMENT_PROFILE} \
  --output tmp/cloudops/workspaces/

# → tmp/cloudops/workspaces/collect-2026-05-21.csv  (22 columns, 122 rows expected)

5 Options (from workspaces.py:259-294)¶

Output Path & Filename Pattern¶

tmp/cloudops/workspaces/collect-<YYYY-MM-DD>.csv

Filename pattern (UTC) set by workspaces.py:484 (f"collect-{_datestamp()}.csv"). Path is gitignored at tmp/ — outputs do not pollute the repo.

22-Column CSV Schema (from workspaces.py:402-425)¶

Worked Example · Reproduce 122 WorkSpaces from Excel Baseline¶

# 1. Run canonical collect (READONLY — pre-authorized by $AWS_MANAGEMENT_PROFILE)
runbooks workspaces collect --all-profile ${AWS_MANAGEMENT_PROFILE} \
  --output tmp/cloudops/workspaces/

# 2. Verify total row count
CSV=tmp/cloudops/workspaces/collect-$(date +%Y-%m-%d).csv
ROWS=$(($(wc -l < "$CSV") - 1))
[ "$ROWS" -eq 122 ] && echo "PASS: 122" || echo "FAIL: $ROWS"

# 3. Verify 7 distinct accounts
ACCTS=$(python3 -c "import csv,sys; print(len(set(r[14] for r in csv.reader(sys.stdin) if len(r)>14)))" < "$CSV")
[ "$ACCTS" -eq 7 ] && echo "PASS: 7" || echo "FAIL: $ACCTS"

# 4. Per-account distribution (column 15 = account_name)
python3 -c "import csv,sys; from collections import Counter; print("\n".join(f"{c} {a}" for a, c in sorted(Counter(r[14] for r in csv.reader(sys.stdin) if len(r)>14).items())))" < "$CSV"

Expected Per-Account Distribution (Excel baseline)¶

Reproducibility target: rows match (122) + accounts match (7) + per-account distribution within ±1 row → ≥99.5% (Excel/API <1% transient drift acceptable due to API rate-limit timing).

Approach A1-Discovery (Fast ARN Lookup)¶

Use Case: Org-wide WorkSpaces discovery via AWS Resource Explorer AGGREGATOR index. Fast (~<30s), eventual-consistent, suitable for CMDB delta detection and inventory sync — NOT for APRA CPS 234 audit evidence (use A2 for that).

Profile: $AWS_OPERATIONS_PROFILE (centralised-ops account hosting the aggregator index).

Worked Example¶

# Single command. Resource Explorer AGGREGATOR does the cross-account query.
runbooks workspaces collect \
  --all-profile $AWS_OPERATIONS_PROFILE \
  --mode discovery \
  --output tmp/cloudops/workspaces/

# → tmp/cloudops/workspaces/collect-discovery-2026-05-22.csv (4 columns, 122 rows expected)

Output: 4-Column CSV¶

Wall Time: <30s (single aggregator query, <24h eventual-consistency lag documented in CC-ADR-016 v2).

3-Approach Comparison Matrix¶

Operational Paths · 5 Ways to Generate WorkSpaces Evidence¶

1. runbooks CLI (canonical, this doc) — runbooks workspaces collect --all-profile $AWS_MANAGEMENT_PROFILE
2. Claude /aws:workspaces-investigate — agentic per-workspace deep-dive (uses A1)
3. Raw aws CLI verify — aws workspaces describe-workspaces --profile $WORKLOAD_PROFILE (per-account, manual fallback)
4. Jupyter notebook — notebooks/cloudops/workspaces-fleet-analysis.ipynb (reads collect-*.csv, plots distributions)
5. CxO dashboard — Vizro/Tableau view of collect-*.csv + monthly trends (governance posture)

Each path consumes/produces the same 22-column CSV — the schema is the contract.

Resource Explorer Cross-Validation¶

After discovery via A1 or A2, validate using AWS Resource Explorer for independent confirmation.

ARN Patterns & Resource Types¶

Cross-Validation Query¶

# Using Resource Explorer to validate discovered WorkSpaces
aws resource-explorer-2 search \
  --index-arn "arn:aws:resource-explorer-2:${AWS_DEFAULT_REGION}:${AWS_ACCOUNT_ID}:index/default" \
  --query-string "resourceType:workspaces" \
  --region ${AWS_DEFAULT_REGION} \
  --output json | jq '.Resources[] | {Arn, Region, AccountId, LastReportedAt}'

Expected Output (for 122 WorkSpaces across 7 accounts):

[
  {
    "Arn": "arn:aws:workspaces:${AWS_DEFAULT_REGION}:${AWS_ACCOUNT_ID}:workspace/ws-12345abcde",
    "Region": "${AWS_DEFAULT_REGION}",
    "AccountId": "${AWS_ACCOUNT_ID}",
    "LastReportedAt": "2026-05-21T14:32:00Z"
  },
  ...
]

Profile Semantics & Why A2 Uses MANAGEMENT Not OPERATIONS¶

See aws-profile-semantics.md for full details. Summary:

Key Principle: Organizations data lives in the Management account. Workload resources live in workload accounts. A2 bridges both via the discovery → resolve → loop pattern.

Profile Architecture (CC-ORG-015): All WorkSpaces investigation uses $AWS_OPERATIONS_PROFILE (per-account + cross-account AGGREGATOR). WorkSpaces are account-level resources, not org-level — the Management profile is not required. See profile semantics.

Troubleshooting¶

Cross-Account Silent Zero Issue¶

Problem: describe-workspaces returns [] instead of an error when account access is denied.

Why It Happens: AWS WorkSpaces APIs do NOT always throw AccessDeniedException for cross-account calls. Sometimes they silently return empty results.

Detection & Fix:

# ALWAYS verify caller identity matches expected account
CURRENT_ACCT=$(aws sts get-caller-identity --profile "$PROFILE" --query Account --output text)
TARGET_ACCT="${AWS_ACCOUNT_ID}"

if [[ "$CURRENT_ACCT" != "$TARGET_ACCT" ]]; then
  echo "❌ CROSS_ACCOUNT_SILENT_ZERO: Using ${CURRENT_ACCT}, expected ${TARGET_ACCT}"
  # Switch to correct account profile
  export AWS_PROFILE="correct-account-profile"
  exit 2
fi

# Now safe to query
aws workspaces describe-workspaces --profile "$PROFILE" --output json

Empty Results with Valid Profile¶

Problem: runbooks inventory workspaces --all-profile $AWS_OPERATIONS_PROFILE --workspace-id ws-xxx returns no results.

Checklist: 1. ✅ Verify workspace-id is spelled correctly: aws workspaces describe-workspaces --workspace-ids ws-xxx --profile $AWS_OPERATIONS_PROFILE 2. ✅ Verify region: WorkSpaces are region-specific. Set export AWS_DEFAULT_REGION=<your-aws-region> (or correct region). 3. ✅ Verify profile has WorkSpaces read permissions: aws sts get-caller-identity --profile $AWS_OPERATIONS_PROFILE 4. ✅ Verify centralised-ops account: The profile should authenticate to the account where cross-account WorkSpaces APIs are configured (typically a hub/operations account).

Timeout or Slow Responses (A2)¶

Cause: Paginating through large numbers of workspaces across many accounts.

Optimization: - Reduce --max-results from 25 to 10 for faster per-page queries (more requests, but each request <2s) - Query regions in parallel (requires shell job control or Python subprocess) - Cache discovered workspaces to avoid re-querying on subsequent runs

Pipeline · raw → V1 → V4 → CMDB¶

flowchart LR
  RAW["raw csv<br/>collect-YYYY-MM-DD.csv<br/>(22 cols × 122 rows)"]
  V1["V1 ingest<br/>row-level validation<br/>+ Excel cross-check"]
  V4["V4 transform<br/>Jinja2 template<br/>→ ServiceNow CSDM CI"]
  CMDB["CMDB publish<br/>WorkSpace CIs + relationships<br/>(HITL approves)"]
  RAW --> V1 --> V4 --> CMDB

Acceptance Criteria (workspaces.md quality contract)¶

References¶

• aws-profile-semantics.md: Profile role semantics (BILLING, MANAGEMENT, OPERATIONS, per-workload)
• CC-ADR-016: Workspaces multi-account discovery pattern decision record
• operational-efficiency.md: Rule 9 (Cross-account zero-result validation)
• AWS WorkSpaces API: https://docs.aws.amazon.com/workspaces/latest/api/API_DescribeWorkspaces.html
• AWS Resource Explorer: https://docs.aws.amazon.com/resource-explorer/latest/userguide/manage-indexes.html

Components Used (ADLC 5W1H)¶

Last updated: 2026-05-21 · scope_id: WORKSPACES-PDCA-SCORING-V1-REMEDIATION