Secrets Management

# Reading an existing secret from Secrets Manager
# The secret was created by a human operator or a separate process — not by Terraform

# Step 1: Look up the secret metadata by name
data "aws_secretsmanager_secret" "db" {
  name = "prod/rds/master-credentials"  # Only the name — never the value — in .tf files
}

# Step 2: Read the current version of the secret value
data "aws_secretsmanager_secret_version" "db" {
  secret_id = data.aws_secretsmanager_secret.db.id  # Reference by ID from step 1
}

# Step 3: Parse the JSON secret string into a usable map
locals {
  # Secrets Manager stores credentials as JSON: {"username":"admin","password":"s3cr3t"}
  db_credentials = jsondecode(data.aws_secretsmanager_secret_version.db.secret_string)
}

# Step 4: Use the credentials — they are read at plan time, never stored in code
resource "aws_db_instance" "main" {
  identifier        = "prod-db"
  engine            = "postgres"
  engine_version    = "15.3"
  instance_class    = "db.t3.medium"
  allocated_storage = 100

  db_name  = "appdb"
  username = local.db_credentials.username  # From Secrets Manager — not hardcoded
  password = local.db_credentials.password  # From Secrets Manager — not hardcoded

  # Even though the password came from Secrets Manager,
  # it will still appear in the state file — ensure state is encrypted
  skip_final_snapshot = false

  tags = {
    Environment = "prod"
    ManagedBy   = "Terraform"
  }
}

# Reading a SecureString from SSM Parameter Store

data "aws_ssm_parameter" "api_key" {
  name            = "/prod/app/third-party-api-key"
  with_decryption = true  # Required to get the plaintext value — omit and you get ciphertext
}

data "aws_ssm_parameter" "db_password" {
  name            = "/prod/rds/master-password"
  with_decryption = true
}

# Use in a resource
resource "aws_lambda_function" "app" {
  filename      = "app.zip"
  function_name = "prod-app"
  role          = aws_iam_role.lambda.arn
  handler       = "index.handler"
  runtime       = "nodejs18.x"

  environment {
    variables = {
      # Inject SSM values as environment variables — Lambda decrypts at runtime
      API_KEY     = data.aws_ssm_parameter.api_key.value    # From SSM SecureString
      DB_PASSWORD = data.aws_ssm_parameter.db_password.value
    }
  }
}

# Secrets Manager vs SSM Parameter Store — which to use?
# Use Secrets Manager when:
#   - You need automatic rotation with rotation lambdas
#   - You store complex JSON credentials (database username + password)
#   - You need cross-account secret sharing
#   - Compliance requires dedicated secrets management (PCI-DSS, HIPAA)
#
# Use SSM Parameter Store when:
#   - Simple key-value secrets without rotation requirements
#   - Configuration values mixed with secrets (same hierarchy)
#   - Cost is a factor — SSM SecureString is free, Secrets Manager charges per secret/month
#   - You want a hierarchical namespace: /prod/app/key, /dev/app/key

# Pattern: Terraform creates the secret container — not the secret value
# The value is populated out of band — by rotation, a bootstrap job, or a human

resource "aws_secretsmanager_secret" "db_credentials" {
  name        = "prod/rds/master-credentials"
  description = "RDS master credentials for the production database"

  # Encrypt the secret with a customer-managed KMS key
  kms_key_id = aws_kms_key.secrets.arn

  # Soft delete protection — prevents accidental deletion of the secret
  recovery_window_in_days = 7  # 7-day window before permanent deletion

  tags = {
    Environment = "prod"
    ManagedBy   = "Terraform"
  }
}

# Rotation configuration — Secrets Manager calls the Lambda on schedule
resource "aws_secretsmanager_secret_rotation" "db_credentials" {
  secret_id           = aws_secretsmanager_secret.db_credentials.id
  rotation_lambda_arn = aws_lambda_function.db_rotation.arn

  rotation_rules {
    automatically_after_days = 30  # Rotate the password every 30 days automatically
  }
}

# The initial value is set outside Terraform — via AWS console, CLI, or bootstrap script
# aws secretsmanager put-secret-value \
#   --secret-id prod/rds/master-credentials \
#   --secret-string '{"username":"admin","password":"initial-value"}'
#
# This keeps the initial secret value out of Terraform state entirely
# Subsequent rotations are handled by the Lambda — Terraform never sees the value

# Architecture that allows secret rotation without any Terraform apply

# Approach: Grant the application's IAM role permission to read from Secrets Manager
# The application calls Secrets Manager directly at runtime — not via Terraform

resource "aws_iam_role_policy" "app_secrets" {
  name = "app-secrets-access"
  role = aws_iam_role.app.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "secretsmanager:GetSecretValue",  # Read the secret value at runtime
        "secretsmanager:DescribeSecret"   # Read secret metadata
      ]
      Resource = aws_secretsmanager_secret.db_credentials.arn  # Only this specific secret
    }]
  })
}

# The application code reads the secret at startup:
# const secret = await secretsManagerClient.getSecretValue({ SecretId: 'prod/rds/master-credentials' })
# const creds = JSON.parse(secret.SecretString)
# const dbPassword = creds.password
#
# When the secret rotates:
# → Secrets Manager calls the rotation Lambda
# → Lambda updates the RDS password and the secret value atomically
# → On next application startup, the app fetches the new value automatically
# → Zero Terraform involvement — zero infrastructure redeployment

# Contrast with the injection approach (Terraform injects at apply time):
# → Secret value goes into Terraform state
# → To use a rotated secret, must run terraform apply again
# → Application downtime window between rotation and redeploy
# → The runtime approach is always preferred for high-availability systems

# Using HashiCorp Vault with Terraform

terraform {
  required_providers {
    vault = {
      source  = "hashicorp/vault"
      version = "~> 3.0"
    }
  }
}

# Configure the Vault provider — address and authentication method
provider "vault" {
  address = "https://vault.acme.internal:8200"
  # Authentication via AWS IAM role — no token hardcoded
  # The Vault server validates the caller's AWS identity against Vault policies
  # Set VAULT_TOKEN or VAULT_ROLE environment variable in CI/CD
}

# Read a secret from Vault's KV secrets engine
data "vault_generic_secret" "db" {
  path = "secret/prod/database"  # Path in Vault where the secret is stored
}

# Use the secret value from Vault
resource "aws_db_instance" "main" {
  identifier     = "prod-db"
  engine         = "postgres"
  instance_class = "db.t3.medium"

  username = data.vault_generic_secret.db.data["username"]  # From Vault
  password = data.vault_generic_secret.db.data["password"]  # From Vault

  # Note: Vault dynamic secrets generate a unique credential for each lease
  # Dynamic credentials expire automatically — far more secure than static passwords
  # Requires the Vault database secrets engine to be configured for the RDS instance
}