Secrets Manager and Parameter Store

What it is

Secrets are values that grant access, such as database passwords, API keys and tokens. They must not live in code, images or plain environment variables, and they should be rotated.

AWS offers two main stores. AWS Secrets Manager is built for secrets with rotation, and Systems Manager Parameter Store is a general configuration store that can also hold encrypted values.

How it works

Secrets Manager

• Storage. Secrets are encrypted with a KMS key, either the AWS managed key for Secrets Manager or a customer managed key.
• Rotation. Secrets Manager can rotate a secret on a schedule using a Lambda function. For many databases, such as Amazon RDS, managed rotation or ready made rotation functions exist.
• Versions. Each value has a version with staging labels. AWSCURRENT is the live value, AWSPENDING is a new value during rotation, and AWSPREVIOUS is the last one.
• Access control. IAM policies on the caller, a resource policy on the secret, and the key policy of the KMS key all apply. For cross account use, add a resource policy and use a customer managed key.
• Replication. A secret can be replicated to other Regions for disaster recovery.
• Audit. CloudTrail records GetSecretValue and other calls.

# AWS CLI: read the current value of a secret
aws secretsmanager get-secret-value --secret-id prod/app/db \
  --query SecretString --output text

How rotation works

Rotation follows four steps: create a new secret version, set the new credential in the database, test it, and finish by moving the AWSCURRENT label. The rotation function needs network access to both the database and the Secrets Manager endpoint, so a function in a VPC needs a route or an interface endpoint.

With Amazon RDS you can also let the service manage the master user password in Secrets Manager, which rotates it automatically and removes the need to handle it.

Parameter Store

Parameter Store keeps parameters in a hierarchy, such as /prod/app/db-url. It has three types.

There are standard and advanced tiers, which differ in the number of parameters, size and features such as parameter policies for expiry notifications. Parameter Store has no built in secret rotation, and standard parameters have no additional charge for storage.

Comparing the two

Choose Secrets Manager for credentials that need rotation, cross account sharing or replication. Choose Parameter Store for application configuration and for secrets that are static and low in value or cost sensitive.

Getting secrets into applications

• ECS. Reference the secret in the task definition secrets field, and the agent injects it at start using the task execution role.
• EKS. Use the Secrets Store CSI driver to mount secrets, with a pod identity for access.
• Lambda. Fetch at runtime with a role, and cache the value. Avoid long lived plain environment variables.
• CloudFormation. Use a dynamic reference, such as {{resolve:secretsmanager:prod/app/db:SecretString:password}}, so the value is never in the template.
• EC2. Read with the instance role at startup, not from user data.

Good practice

• Use one secret per purpose, and name them with a path.
• Give each workload read access to its own secrets only, with resource ARNs in the IAM policy.
• Use a customer managed key when you need separate access control or cross account use.
• Alarm on unusual GetSecretValue activity, and on rotation failures.
• Scan code and repositories for hard coded secrets, and revoke any that are found.
• Prefer roles and temporary credentials over secrets where possible, since no secret is better than a rotated one.