Systems Manager Parameter Store
AWS Systems Manager Parameter Store is a hierarchical key-value store for configuration and secrets, addressed by paths such as /acme/usw2/dev/vpc/id. In the platform it is the contract between repositories: the landing zone publishes what workloads need, the blueprints publish what deployments need, and the secrets repository publishes what applications need.
What it does
A parameter has a path-like name, a type and a value. String and StringList hold plain values. SecureString holds a value encrypted with a KMS key, which only principals with both parameter and key permissions can decrypt. Names are hierarchical, so IAM policies can grant access to a whole prefix, and a caller can fetch every parameter under a path in one call. Standard parameters are free.
How BuiltForProd uses it
Every path follows one convention: /<namespace>/<environment>/<stage>/<service>/<key>, for example /acme/usw2/prd/sample/AUTH0_CLIENT_SECRET.
| Writer | Parameters | Readers |
|---|---|---|
Landing zone, ssm-publish unit in every plat-* account (and the runner VPC) | /acme/usw2/<stage>/vpc/id, vpc/cidr, vpc/private_subnet_ids, vpc/public_subnet_ids, tgw/attachment_id, account/id | Blueprint modules, through data sources at plan time, to place EKS, DocumentDB, Redis and Lambda in the right VPC |
| Web application blueprint | acm/certificate_arn and its CloudFront variant, frontend/bucket_name, frontend/cloudfront_distribution_id, the DocumentDB and Redis endpoints | Deployment workflows and the External Secrets Operator |
Data blueprint, modules/lambda | etl-trigger/image_tag, seeded as bootstrap and updated by the CD workflow with every deployed tag | The Lambda module at plan time, so a plan never rolls the function back |
Secrets repository, on merge to main | One SecureString per key in each SOPS-encrypted file, under /acme/usw2/<stage>/<app>/ | The External Secrets Operator |
Because the blueprints read parameters instead of landing-zone state, the repositories are decoupled: a workload team never needs access to the landing zone's Terraform state, and the two sides can be planned and applied independently.
Inside Kubernetes, the External Secrets Operator runs a ClusterSecretStore named aws-ssm with an EKS Pod Identity role whose policy allows GetParameter, GetParameters and GetParametersByPath only under /acme/usw2/<stage>/*; ExternalSecrets refresh hourly. The application service account gets read access to its own path the same way. A second store, aws-secretsmanager, serves the DocumentDB master password, which the module writes to Secrets Manager rather than to Parameter Store: a SecureString parameter resource is read with decryption on every refresh, which would put the password into every plan.
One cross-account path exists: /acme/syncer/plat-accounts/<stage> in core-security maps stages to account ids for the secrets syncers; each stage's syncer reads only its own stage's entry. Workloads read only their own account's parameters; the GitHub App credentials ArgoCD uses are written by a lead into each stage account, under /acme/usw2/<stage>/argocd/.
Non-secret outputs are String parameters (no KMS cost); SecureStrings use the AWS-managed SSM key. The auditor permission sets may describe parameters but are denied reading values. The read-only role of pull request plans and drift checks is denied SecureString decryption in every account, and so are the ReadOnlyAccess and DevOpsAdminAccess sessions in the prod account, so no plan and no standing session reads a secret value there. Data sources read only String and StringList parameters.
Terms you will see
| Term | Meaning |
|---|---|
| Parameter | One named value; the unit of storage. |
SecureString | A parameter encrypted with KMS; used for every secret that people manage. |
| Path prefix | The leading part of a name, such as /acme/usw2/dev/, that IAM policies scope to. |
GetParametersByPath | The call that fetches every parameter under a prefix. |
ClusterSecretStore | The External Secrets Operator resource that points at Parameter Store (aws-ssm) or Secrets Manager. |
| Write-only argument | An OpenTofu argument whose value is sent to AWS but never stored in state. |
| Syncer | The per-stage acme-secrets-syncer-<stage> roles and the workflow that write decrypted secrets to parameters. |
Where to read more
- Secrets Blueprint overview for the repository that feeds SecureStrings.
- External Secrets Operator for how parameters become Kubernetes Secrets.
- Secrets Manager for why the platform stores secrets here instead.