This Terraform module manages secrets in AWS Secrets Manager for all Oshun services across domains.
Features#
- Centralized Secrets Management: All application secrets stored in AWS Secrets Manager
- KMS Encryption: Dedicated KMS key for secrets encryption with key rotation
- Automatic Password Generation: Generate strong passwords for databases and services
- Secret Rotation: Lambda-based automatic rotation for database credentials and tokens
- Multi-Region Replication: Replicate secrets across regions for disaster recovery
- ECS Integration: Pre-formatted outputs for ECS task definition secrets blocks
- Domain Isolation: Organized secrets by domain (database, redis, jwt, encryption, oauth, ai, external)
Usage#
module "secrets" {
source = "../secrets"
environment = "production"
region = "us-east-1"
name_prefix = "oshun"
# KMS Configuration
create_kms_key = true
kms_key_deletion_window = 30
# Multi-region replication
replica_regions = ["us-west-2"]
# Database secrets
database_secrets = {
main = {
description = "Main database credentials"
database = "oshun"
username = "oshun_app"
host = module.rds.endpoint
port = 5432
generate_password = true
rotation_days = 30
}
}
# JWT secrets
jwt_secrets = {
access = {
description = "JWT access token secret"
generate_secret = true
length = 64
rotation_days = 90
}
}
# AI provider secrets
ai_provider_secrets = {
openai = {
description = "OpenAI API credentials"
api_key = var.openai_api_key
org_id = var.openai_org_id
}
}
# Rotation configuration
enable_database_rotation = true
rotation_vpc_id = module.vpc.vpc_id
rotation_subnet_ids = module.vpc.private_subnet_ids
psycopg2_layer_path = "lambda-layers/psycopg2.zip"
tags = {
Environment = "production"
}
}
Secret Types#
Database Secrets#
Stores credentials for PostgreSQL databases with connection string generation.
database_secrets = {
main = {
description = "Main database credentials"
database = "oshun"
username = "oshun_app"
host = "db.example.com"
port = 5432
engine = "postgres"
generate_password = true
rotation_days = 30 # 0 to disable rotation
}
}
Secret structure:
{
"username": "oshun_app",
"password": "generated-password",
"host": "db.example.com",
"port": 5432,
"database": "oshun",
"engine": "postgres",
"connection_string": "postgresql://oshun_app:password@db.example.com:5432/oshun"
}
Redis Secrets#
Stores Redis/ElastiCache authentication tokens.
redis_secrets = {
main = {
description = "Main Redis credentials"
generate_password = true
}
}
JWT Secrets#
Stores JWT signing secrets for token generation.
jwt_secrets = {
access = {
description = "JWT access token secret"
generate_secret = true
length = 64
rotation_days = 90
}
}
Encryption Keys#
Stores application-level encryption keys.
encryption_keys = {
data = {
description = "Data encryption key"
generate_key = true
length = 32
rotation_days = 365
}
}
OAuth Secrets#
Stores OAuth provider credentials.
oauth_secrets = {
google = {
description = "Google OAuth credentials"
client_id = "your-client-id"
client_secret = "your-client-secret"
}
}
AI Provider Secrets#
Stores AI service API keys.
ai_provider_secrets = {
openai = {
description = "OpenAI API credentials"
api_key = "sk-..."
org_id = "org-..."
}
}
External Service Secrets#
Stores credentials for external services.
external_service_secrets = {
stripe = {
description = "Stripe credentials"
api_key = "pk_..."
secret_key = "sk_..."
webhook_secret = "whsec_..."
}
}
Storage Secrets#
Stores S3-compatible storage credentials.
storage_secrets = {
s3 = {
description = "S3 storage credentials"
access_key = ""
secret_key = ""
generate_keys = true
}
}
Custom Secrets#
Stores arbitrary secrets with flexible structure.
custom_secrets = {
internal-keys = {
description = "Internal service keys"
secret_string = "" # Raw string, or use secret_data for JSON
secret_data = {
key1 = "value1"
key2 = "value2"
}
}
}
Outputs#
Secret ARNs#
# Individual secret ARNs
module.secrets.database_secret_arns["main"]
module.secrets.jwt_secret_arns["access"]
module.secrets.ai_provider_secret_arns["openai"]
# Convenience outputs for domain databases
module.secrets.main_database_secret_arn
module.secrets.yemaya_database_secret_arn
module.secrets.lilith_database_secret_arn
ECS Integration#
Pre-formatted outputs for ECS task definitions:
# Database connection strings
module.secrets.ecs_database_secrets["main"]
# => { name = "MAIN_DATABASE_URL", valueFrom = "arn:...:connection_string::" }
# JWT secrets
module.secrets.ecs_jwt_secrets["access"]
# => { name = "JWT_ACCESS_SECRET", valueFrom = "arn:...:secret::" }
IAM Policy#
Ready-to-use IAM policy for secret access:
resource "aws_iam_role_policy" "secrets_access" {
role = aws_iam_role.task.id
policy = module.secrets.secrets_read_policy_json
}
Secret Rotation#
Database Rotation#
When rotation_days > 0, a Lambda function is created to automatically rotate
database passwords:
- createSecret: Generates new password and stores as AWSPENDING version
- setSecret: Connects to database and updates the user's password
- testSecret: Verifies the new password works
- finishSecret: Promotes AWSPENDING to AWSCURRENT
Requirements:
rotation_vpc_id: VPC where Lambda will runrotation_subnet_ids: Private subnets with database connectivitypsycopg2_layer_path: Path to Lambda layer with psycopg2
JWT/Encryption Key Rotation#
Self-contained rotation that generates new keys without external dependencies:
- Generates new random secret of the same length
- Stores as AWSPENDING version
- Promotes to AWSCURRENT after verification
Note: Applications should support both current and pending versions during rotation window.
Accessing Secrets in Applications#
ECS Task Definition#
resource "aws_ecs_task_definition" "app" {
container_definitions = jsonencode([{
name = "app"
secrets = [
{
name = "DATABASE_URL"
valueFrom = "${module.secrets.database_secret_arns["main"]}:connection_string::"
},
{
name = "JWT_SECRET"
valueFrom = "${module.secrets.jwt_secret_arns["access"]}:secret::"
},
{
name = "OPENAI_API_KEY"
valueFrom = "${module.secrets.ai_provider_secret_arns["openai"]}:api_key::"
}
]
}])
}
Application Code (Node.js)#
import {
SecretsManagerClient,
GetSecretValueCommand,
} from '@aws-sdk/client-secrets-manager';
const client = new SecretsManagerClient({});
async function getSecret(secretArn: string): Promise<Record<string, unknown>> {
const response = await client.send(
new GetSecretValueCommand({ SecretId: secretArn })
);
return JSON.parse(response.SecretString!);
}
// Get database credentials
const dbSecret = await getSecret(process.env.DATABASE_SECRET_ARN!);
const connectionString = dbSecret.connection_string;
Security Best Practices#
- Least Privilege: Use the generated IAM policy and scope to only needed secrets
- KMS Key Policies: Restrict KMS key access to authorized services
- VPC Endpoints: Use Secrets Manager VPC endpoints to avoid public internet
- Rotation: Enable rotation for all credentials, especially databases
- Audit Logging: Enable CloudTrail logging for secret access
- Recovery Window: Use appropriate recovery windows (30 days for production)
Inputs#
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| environment | Deployment environment | string | - | yes |
| region | AWS region | string | "us-east-1" | no |
| name_prefix | Prefix for secret names | string | "oshun" | no |
| create_kms_key | Create dedicated KMS key | bool | true | no |
| kms_key_arn | Existing KMS key ARN | string | "" | no |
| replica_regions | Regions for secret replication | list(string) | [] | no |
| database_secrets | Database credentials map | map(object) | {} | no |
| redis_secrets | Redis credentials map | map(object) | {} | no |
| jwt_secrets | JWT secrets map | map(object) | {} | no |
| encryption_keys | Encryption keys map | map(object) | {} | no |
| oauth_secrets | OAuth provider secrets map | map(object) | {} | no |
| ai_provider_secrets | AI provider API keys map | map(object) | {} | no |
| external_service_secrets | External service secrets map | map(object) | {} | no |
| storage_secrets | Storage credentials map | map(object) | {} | no |
| custom_secrets | Custom secrets map | map(object) | {} | no |
| recovery_window_in_days | Days before permanent deletion | number | 7 | no |
| enable_database_rotation | Enable database rotation | bool | false | no |
| rotation_vpc_id | VPC for rotation Lambda | string | "" | no |
| rotation_subnet_ids | Subnets for rotation Lambda | list(string) | [] | no |
| psycopg2_layer_path | Path to psycopg2 Lambda layer | string | "" | no |
Outputs#
| Name | Description |
|---|---|
| kms_key_arn | ARN of the KMS key |
| database_secret_arns | Map of database secret ARNs |
| redis_secret_arns | Map of Redis secret ARNs |
| jwt_secret_arns | Map of JWT secret ARNs |
| encryption_key_arns | Map of encryption key ARNs |
| oauth_secret_arns | Map of OAuth secret ARNs |
| ai_provider_secret_arns | Map of AI provider secret ARNs |
| external_service_secret_arns | Map of external service secret ARNs |
| storage_secret_arns | Map of storage secret ARNs |
| custom_secret_arns | Map of custom secret ARNs |
| all_secret_arns | Combined map of all secret ARNs |
| secrets_read_policy_json | IAM policy JSON for secret access |
| ecs_database_secrets | ECS-formatted database secrets |
| ecs_jwt_secrets | ECS-formatted JWT secrets |
| secrets_summary | Summary of all created secrets |