DocumentDB
Amazon DocumentDB is a managed document database that speaks the MongoDB wire protocol. The Web App Blueprint stores its items in it, one cluster per stage, and never puts the master password in Git, in a plan or in state.
What it does
A DocumentDB cluster has one writer instance and up to fifteen replicas that share the same storage volume. AWS handles backups, patching and failover. Clients connect over TLS with a username and password, using any MongoDB driver.
How BuiltForProd uses it
The documentdb unit in acme-aws-blueprint-webapp-infra creates cluster acme-usw2-dev-docdb (engine 5.0.0, db.t3.medium instances) in the private subnets published by the AWS Baseline. The sg-docdb unit provides its security group, which allows port 27017 from the organization's private address space only.
Per-stage choices live in environments/<stage>/us-west-2/terragrunt.stack.hcl:
| Stage | Instances | Deletion protection |
|---|---|---|
| dev | 1 | off |
| staging | 2 | on |
| prod | 3 (writer plus two replicas in other AZs) | on |
Storage is encrypted (AWS-managed key by default, a customer key if you pass one), automated backups are kept for seven days, and prod takes a final snapshot on deletion. Audit logs reach CloudWatch because both halves are set together: a cluster parameter group turns the engine's audit_logs parameter on and the cluster declares the audit export, and the single enable_audit_logs setting moves the two as one. Cluster and instances both apply changes immediately, so resizing an instance class does not wait for the next maintenance window.
The master password is the interesting part. The module asks Secrets Manager for a random 32-character password as an ephemeral value and writes it with write-only arguments to two places at once: the cluster's master_password_wo and the SecureString parameter /acme/usw2/dev/documentdb/master_password. Neither the plan nor the state file ever contains it. Rotation is a version bump: raising master_password_version writes a new password to both places on the next apply. The cluster endpoint is published as /acme/usw2/dev/documentdb/endpoint.
The application never reads Parameter Store directly. The Helm chart's ExternalSecret pulls both parameters into the Kubernetes Secret blueprint-app-secrets, and the deployment reads DOCDB_HOST and DOCDB_PASSWORD from it. The container image carries the RDS certificate bundle, so connections use TLS. The readiness probe GET /ready checks the database before the pod receives traffic.
Terms you will see
| Term | Meaning |
|---|---|
| Cluster endpoint | The DNS name that always points at the current writer. |
| Replica | A read instance in another availability zone that can be promoted on failure. |
| Write-only argument | An OpenTofu input whose value is sent to AWS but never stored in state. |
| Ephemeral resource | A value generated during a run and discarded afterwards. |
| Deletion protection | A cluster setting that blocks deletion until it is switched off. |
| Cluster parameter group | The engine settings shared by every instance, such as audit_logs. |
Where to read more
- Web App Blueprint overview
- ElastiCache for the cache next to it
- External Secrets Operator for the secret delivery
- Systems Manager Parameter Store for the parameter paths