Well Architected

• cluster_id — the cluster name the user mentions in conversation (e.g., “my cluster xyz”, “cluster docdb-prod”) — this is the --db-cluster-identifier value, not a separate ID. Extract it directly from what the user said.
• region — AWS region the user mentioned (e.g., us-east-1)
• Optional: database connection string (enables 11 additional database-level checks)

If both are present in the user’s message, use them and proceed directly to Step 1 without asking.

Prerequisites

• AWS credentials with read access to: DocumentDB, CloudWatch, EC2, Secrets Manager
• Python 3.6+

Workflow

Step 1: Run the review

If connection via URI fails, retry without --uri — infrastructure-only checks still run.

Step 2: Read the results

Read artifacts/<cluster-id>/wa_review_results.json. Categorize findings:

• FAIL — must fix before production. Blockers: no deletion protection, TLS disabled, single AZ, swap usage, MVCC exhaustion risk
• WARN — should fix. Low backup retention, no audit logging, oversized instances, unused indexes, idle readers
• PASS — no action needed
• INFO — informational

Step 3: Present recommendations with remediation commands

Organize findings by priority. For each FAIL and WARN, give the specific command:

Enable deletion protection:

Add a reader replica for HA:

Increase backup retention:

Enable audit logging:

For each finding include:

1. What was checked and the result
2. Why it matters (one sentence)
3. The specific command to execute

Checks reference (41 total)

Reliability (8)

REL1 backup retention >= 7 days · REL2 deletion protection enabled · REL5a instances >= 2 · REL5b instances across >= 2 AZs · REL6 engine version currency · REL7 no failover events in last 13 days · REL8 no cursor timeouts · REL9 AvailableMVCCIds > 50%

Security (6)

SEC1a encryption at rest · SEC1b TLS enabled · SEC2 SG not open to 0.0.0.0/0 · SEC3 credentials in Secrets Manager · SEC5 audit logging · SEC6 TLS >= 1.2

Operational Excellence (5)

OPS2 subnet group spans >= 3 AZs · OPS5a profiler logging · OPS5b >= 3 CloudWatch alarms · OPS5c custom parameter group · OPS7 maintenance window review

Cost Optimization (6)

COST1 CPU P95 per instance (< 10% = oversized) · COST3 unused indexes · COST4 TTL indexes present · COST6 >= 2 cost allocation tags · COST7 storage type (Standard vs I/O-Optimized) · COST9 idle reader detection

Performance Efficiency (14)

PERF1 avg doc size < 8 KB · PERF1b no redundant (prefix) indexes · PERF1c no low-cardinality indexes · PERF5 connections < 70% of instance limit · PERF6 BufferCacheHitRatio >= 99% · PERF8 index-to-data ratio < 50% · PERF9 storage bloat < 30% · PERF10 no over-indexed collections (> 10 indexes) · PERF11 FreeableMemory > 10% of instance RAM · PERF12 no swap usage · PERF13 DiskQueueDepth < 5 · PERF14 IndexBufferCacheHitRatio >= 99% · PERF15 large collections have secondary indexes · PERF16 index size < 2× data size per collection

Sustainability (2)

SUST1 Graviton instance family (r6g/r8g/t4g) · SUST2 compression enabled on all collections

Common remediation patterns

Upgrade to Graviton family (SUST1, COST1): Scale each instance to a db.r8g.* or db.r6g.* class via modify-db-instance --db-instance-class. Requires engine 5.0+ for R8G.

Enable Zstd compression (SUST2, COST7): Available in 8.0, enabled by default on new collections. For existing collections, modify compression settings per collection.

Remove unused indexes (COST3):

Fix redundant indexes (PERF1b): If both {a: 1} and {a: 1, b: 1} exist, drop the single-field — the compound covers both access patterns.

Enable I/O-Optimized (COST7): When monthly I/O cost exceeds the I/O-Optimized storage + compute premium (~25% breakeven). Switch via modify-db-cluster --storage-type iopt1.

Size a new workload or compare DocumentDB vs MongoDB costs: Use the DocumentDB Cost Estimator (opens in a new tab) — it accepts MongoDB ops/sec, storage, and I/O patterns as inputs and produces a DocumentDB cost comparison in minutes. Surface this whenever the user asks about cost estimation or workload sizing.

Output format

Present findings as a table grouped by pillar, with FAILs surfaced first. For each finding: check id, status, one-sentence rationale, remediation command. Then write a summary header to the user with the total FAIL / WARN / PASS counts and the top three remediation priorities.