Examples

These examples demonstrate practical, real-world usage patterns for the kms-key module. Each example is self-contained and ready to run—simply copy the configuration, customize the values for your environment, and apply.

Getting Started

To run any example, follow these steps:

  1. Authenticate with the registry: terraform login registry.patterneddesigns.ca
  2. Initialize the working directory: terraform init
  3. Review the execution plan: terraform plan
  4. Apply the configuration: terraform apply

Usage Examples

Basic Usage

Simple KMS key for application encryption

module "encryption_key" {
  source  = "registry.patterneddesigns.ca/patterneddesigns/kms-key/aws"
  version = "1.0.0"

  alias       = "alias/app-encryption"
  description = "Encryption key for application data"
}

S3 Bucket Encryption

KMS key for encrypting S3 bucket objects

module "s3_encryption_key" {
  source  = "registry.patterneddesigns.ca/patterneddesigns/kms-key/aws"
  version = "1.0.0"

  alias       = "alias/s3-bucket-encryption"
  description = "Encryption key for S3 bucket data at rest"
}

resource "aws_s3_bucket" "encrypted" {
  bucket = "my-encrypted-bucket"
}

resource "aws_s3_bucket_server_side_encryption_configuration" "encrypted" {
  bucket = aws_s3_bucket.encrypted.id

  rule {
    apply_server_side_encryption_by_default {
      kms_master_key_id = module.s3_encryption_key.key_arn
      sse_algorithm     = "aws:kms"
    }
    bucket_key_enabled = true  # Reduces KMS costs
  }
}

output "bucket_name" {
  value = aws_s3_bucket.encrypted.id
}

output "encryption_key_arn" {
  value = module.s3_encryption_key.key_arn
}

RDS Encryption

KMS key for encrypting RDS database instances

module "rds_encryption_key" {
  source  = "registry.patterneddesigns.ca/patterneddesigns/kms-key/aws"
  version = "1.0.0"

  alias       = "alias/rds-encryption"
  description = "Encryption key for RDS database instances"
}

resource "aws_db_instance" "encrypted" {
  identifier     = "encrypted-database"
  engine         = "postgres"
  engine_version = "15.4"
  instance_class = "db.t3.micro"

  allocated_storage = 20
  storage_type      = "gp3"
  storage_encrypted = true
  kms_key_id        = module.rds_encryption_key.key_arn

  db_name  = "appdb"
  username = "admin"
  password = var.db_password

  skip_final_snapshot = true
}

output "db_endpoint" {
  value = aws_db_instance.encrypted.endpoint
}

output "encryption_key_arn" {
  value = module.rds_encryption_key.key_arn
}

EBS Volume Encryption

KMS key for encrypting EBS volumes

module "ebs_encryption_key" {
  source  = "registry.patterneddesigns.ca/patterneddesigns/kms-key/aws"
  version = "1.0.0"

  alias       = "alias/ebs-encryption"
  description = "Encryption key for EBS volumes"
}

resource "aws_ebs_volume" "encrypted" {
  availability_zone = "us-east-1a"
  size              = 100
  type              = "gp3"

  encrypted  = true
  kms_key_id = module.ebs_encryption_key.key_arn

  tags = {
    Name = "encrypted-volume"
  }
}

resource "aws_volume_attachment" "encrypted" {
  device_name = "/dev/sdf"
  volume_id   = aws_ebs_volume.encrypted.id
  instance_id = var.instance_id
}

# Enable EBS encryption by default for the account
resource "aws_ebs_encryption_by_default" "enabled" {
  enabled = true
}

resource "aws_ebs_default_kms_key" "default" {
  key_arn = module.ebs_encryption_key.key_arn
}

output "volume_id" {
  value = aws_ebs_volume.encrypted.id
}

output "encryption_key_arn" {
  value = module.ebs_encryption_key.key_arn
}

Secrets Manager

KMS key for encrypting Secrets Manager secrets

module "secrets_encryption_key" {
  source  = "registry.patterneddesigns.ca/patterneddesigns/kms-key/aws"
  version = "1.0.0"

  alias       = "alias/secrets-manager"
  description = "Encryption key for Secrets Manager secrets"
}

resource "aws_secretsmanager_secret" "database_credentials" {
  name       = "prod/database/credentials"
  kms_key_id = module.secrets_encryption_key.key_arn

  description = "Database credentials for production environment"

  tags = {
    Environment = "production"
  }
}

resource "aws_secretsmanager_secret_version" "database_credentials" {
  secret_id = aws_secretsmanager_secret.database_credentials.id
  secret_string = jsonencode({
    username = "admin"
    password = var.db_password
    host     = var.db_host
    port     = 5432
  })
}

# IAM policy for applications to access the secret
data "aws_iam_policy_document" "secrets_access" {
  statement {
    effect = "Allow"
    actions = [
      "secretsmanager:GetSecretValue",
      "secretsmanager:DescribeSecret"
    ]
    resources = [aws_secretsmanager_secret.database_credentials.arn]
  }

  statement {
    effect = "Allow"
    actions = [
      "kms:Decrypt"
    ]
    resources = [module.secrets_encryption_key.key_arn]
  }
}

output "secret_arn" {
  value = aws_secretsmanager_secret.database_credentials.arn
}

output "encryption_key_arn" {
  value = module.secrets_encryption_key.key_arn
}

Multi-Region Key

Multi-region KMS key for cross-region encryption

# Primary key in the main region
module "primary_key" {
  source  = "registry.patterneddesigns.ca/patterneddesigns/kms-key/aws"
  version = "1.0.0"

  alias       = "alias/multi-region-primary"
  description = "Primary multi-region encryption key"

  # Note: multi_region must be enabled in the module
  # This example shows the conceptual pattern
}

# Create replica key in secondary region
provider "aws" {
  alias  = "replica"
  region = "eu-west-1"
}

resource "aws_kms_replica_key" "replica" {
  provider = aws.replica

  primary_key_arn         = module.primary_key.key_arn
  description             = "Replica encryption key in EU"
  deletion_window_in_days = 30
}

resource "aws_kms_alias" "replica" {
  provider = aws.replica

  name          = "alias/multi-region-replica"
  target_key_id = aws_kms_replica_key.replica.key_id
}

# S3 bucket with cross-region replication using multi-region key
resource "aws_s3_bucket" "primary" {
  bucket = "primary-encrypted-bucket"
}

resource "aws_s3_bucket_server_side_encryption_configuration" "primary" {
  bucket = aws_s3_bucket.primary.id

  rule {
    apply_server_side_encryption_by_default {
      kms_master_key_id = module.primary_key.key_arn
      sse_algorithm     = "aws:kms"
    }
  }
}

output "primary_key_arn" {
  value = module.primary_key.key_arn
}

output "replica_key_arn" {
  value = aws_kms_replica_key.replica.arn
}