ADR 005: Secrets Management
Status: Accepted | Date: 2025-02-25
Context
Per the Open Web Application Security Project (OWASP) Secrets Management Cheat Sheet:
Organisations face a growing need to centralise the storage, provisioning, auditing, rotation and management of secrets to control access to secrets and prevent them from leaking and compromising the organisation. Often, services share the same secrets, which makes identifying the source of compromise or leak challenging.
To address these challenges, we need a standardised, auditable approach to managing and rotating secrets within our environments. Secrets should be accessed at runtime by workloads and should never be hard-coded or stored in plain text.
- Amazon Web Services (AWS) Secrets Manager Compliance validation
- Using Elastic Kubernetes Service (EKS) encryption provider support for defense-in-depth
Decision
Use AWS Secrets Manager to store and manage secrets.
- Secrets should be fetched and securely injected into AWS resources at runtime.
- The secret rotation period must be captured in the system design.
Recommended rotation periods:
- Database credentials: 30-90 days (automate via Secrets Manager)
- API keys: 90 days or on suspected compromise
- Certificates: Before expiry (automate via ACM where possible)
- Rotate secrets automatically where possible, or ensure that a manual rotation process is documented and followed.
- Use Identity and Access Management (IAM) policy statements to enforce least-privilege access to secrets.
Kubernetes Integration:
- ADR 002: AWS EKS for Cloud Workloads kubernetes workloads should use EKS Key Management Service (KMS) secrets encryption with namespace-local secrets by default.
- If secrets need to be accessed by multiple clusters, use External Secrets Operator to synchronise them from AWS Secrets Manager.
Consequences
Benefits:
- Automated secret rotation reduces human error
- Meets compliance and auditing requirements
- Enhanced security through centralised management
Risks if not implemented:
- Security exposure from manual secret handling
- Operational overhead and error-prone processes
- Non-compliance with security requirements
Trade-offs:
- AWS vendor dependency may complicate future migrations