Secrets Manager
AWS Secrets Manager stores secrets such as database passwords and API keys, encrypts them with KMS, and can rotate them on a schedule. The platform does not use it as its secret store; secrets live in Parameter Store, and Secrets Manager appears only at the edges.
What it does
A secret in Secrets Manager is a named, versioned, KMS-encrypted value, usually a JSON document. Applications fetch it with GetSecretValue. Rotation can run a Lambda function on a schedule to change the credential in both the secret and the target system. The service also offers GetRandomPassword, which returns a strong random string without creating a secret. Secrets Manager charges per secret per month and per API call; Parameter Store SecureString parameters are free at the standard tier, and both encrypt with KMS.
How BuiltForProd uses it
The design decision is to keep human-managed secrets SOPS-encrypted in the secrets repository, sync them on merge to SecureString parameters in Parameter Store, and deliver them to Kubernetes with the External Secrets Operator. Git gives review, history and ownership; per-stage KMS keys give the access matrix; Parameter Store keeps the values out of Terraform state and Helm values. Rotation is manual: edit, review, merge.
Secrets Manager still shows up in three places:
| Where | What | Why |
|---|---|---|
modules/documentdb in the web application blueprint | An ephemeral aws_secretsmanager_random_password call generates the 32-character alphanumeric master password | GetRandomPassword only; no secret is created. The value feeds a write-only argument on the cluster and a SecureString parameter, so it never lands in state |
modules/external-secrets | The operator's IAM policy allows GetSecretValue and DescribeSecret on secrets named acme/usw2/<stage>/* | The ClusterSecretStore in use points at Parameter Store; the permission exists but no secrets are created under that name |
The SecurityAuditorAccess and LeadSecurityAuditorAccess permission sets | May ListSecrets and DescribeSecret; explicitly denied GetSecretValue | Auditors can verify rotation settings and metadata without reading values |
The password is regenerated only when master_password_version changes, which rewrites the cluster and the parameter together; plans stay clean in between. A Security-Best-Practices-for-Secrets-Manager conformance pack ships with the AWS Baseline and is switched off with the other optional packs.
If an organization prefers Secrets Manager for a workload, the External Secrets Operator already has the permission shape for it, but that is a change to make deliberately; the platform as delivered stores nothing there.
Terms you will see
| Term | Meaning |
|---|---|
| Secret | A named, versioned value in Secrets Manager. |
GetSecretValue | The call that reads a secret; denied to auditors. |
GetRandomPassword | The call that returns a random string without storing anything. |
| Rotation | Scheduled credential change through a Lambda function; not used. |
| Ephemeral resource | An OpenTofu resource whose value exists only during a run and is never stored. |
| Write-only argument | An argument sent to AWS but excluded from plan and state. |
SecureString | The Parameter Store type the platform uses for secrets instead. |
Where to read more
- Secrets Blueprint overview for the repository and sync workflow.
- Parameter Store for the store the platform actually uses.
- DocumentDB for the cluster whose password is generated this way.