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 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, and one secret per stage holds the copy the application reads | The same ephemeral value goes to the cluster and to the secret acme/usw2/<stage>/documentdb/master_password, both through write-only arguments, so it never lands in plan or state |
modules/external-secrets | The operator's IAM policy allows GetSecretValue and DescribeSecret on secrets named acme/usw2/<stage>/* | The aws-secretsmanager ClusterSecretStore reads the DocumentDB password with it |
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 secret together; plans stay clean in between. The secret, not a SecureString parameter, holds the copy because its write-only version refreshes by listing version ids without reading the value, while a parameter is read with decryption on every refresh. It costs $0.40 a month per stage, and a deleted secret stays recoverable for seven days. A Security-Best-Practices-for-Secrets-Manager conformance pack ships with the AWS Baseline and is switched off with the other optional packs.
Human-managed secrets stay in Parameter Store. Moving one of them to Secrets Manager needs no new permission, since the operator's store already reads secrets under the stage prefix, but it is a change to make deliberately. No pipeline role can read a secret value: the read-only plan role is denied GetSecretValue, and so are the ReadOnlyAccess and DevOpsAdminAccess sessions in the prod account.
Terms you will see
| Term | Meaning |
|---|---|
| Secret | A named, versioned value in Secrets Manager. |
GetSecretValue | The call that reads a secret; denied to auditors, plan roles and prod sessions. |
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 human-managed secrets. |
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.