Skip to content

README.md

Latest commit

 

History

History
280 lines (227 loc) · 20 KB

README.md

File metadata and controls

280 lines (227 loc) · 20 KB

Contributors Forks Stargazers Issues Unlicense License


Logo

AWS RDS & Aurora Module

PSA-compliant RDS and Aurora module with mandatory encryption, RDS Proxy support, and Serverless v2 integration.
Explore the docs »

View Demo · Report Bug · Request Feature

Documentation

Full auto-generated documentation of inputs, outputs, and resources: TERRAFORM-DOCS.md

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Advanced Features
  5. Security Features
  6. PSA Compliance Features
  7. Outputs
  8. Troubleshooting
  9. License

About The Project

This module provides a production-ready, security-first foundation for relational databases on AWS. It supports standard RDS instances, Aurora Clusters (including Serverless v2), and RDS Proxy for advanced connection management.

Features

  • Standard RDS & Aurora: Toggle between standalone instances and high-availability clusters.
  • Aurora Serverless v2: Native support for autoscaling compute capacity.
  • RDS Proxy: Integrated connection pooling and security filtering.
  • KMS Encryption: Mandatory encryption at rest with optional CMK creation.
  • IAM Authentication: Enabled by default for modern access control.
  • Performance Insights: Integrated monitoring for database performance tuning.

(back to top)

Usage

Basic Usage (Standard RDS)

module "db" {
  source = "./terraform-aws-rds"

  project_name = "myapp"
  environment  = "prod"
  
  engine         = "postgres"
  engine_version = "15.4"
  instance_class = "db.t3.medium"
  
  master_password = var.db_password # Use Secrets Manager in production
  
  vpc_id             = module.vpc.vpc_id
  subnet_ids         = module.vpc.database_subnets
  security_group_ids = [module.sg.db_tier_sg_id]
}

Advanced Usage (Aurora Serverless v2 + Proxy)

module "aurora" {
  source = "./terraform-aws-rds"

  create_aurora_cluster = true
  engine                = "aurora-postgresql"
  
  aurora_serverless_v2_scaling_configuration = {
    min_capacity = 0.5
    max_capacity = 16
  }
  
  create_db_proxy = true
  db_proxy_auth = [
    {
      auth_scheme = "SECRETS"
      secret_arn  = aws_secretsmanager_secret.db_creds.arn
      iam_auth    = "REQUIRED"
    }
  ]
  # ... other variables
}

(back to top)

Security Features

  • Encryption at Rest: Mandatory SSE-KMS for all storage and snapshots.
  • SSL/TLS Enforcement: Parameter groups are pre-configured to force encrypted connections (e.g., rds.force_ssl=1).
  • No Public Access: publicly_accessible is hardcoded to false to prevent exposure.
  • Deletion Protection: Enabled by default to prevent accidental data loss.
  • IAM Auth: Enabled by default to allow token-based authentication.

(back to top)

PSA Compliance Features

This module implements the following PSA compliance features (referencing 05-Strukturierte_PSA_Anforderungen_DB_Hadoop_LLM.pdf):

Security Controls

  • Req 2 (TLS Enforcement): Enforced via parameter groups (rds.force_ssl or require_secure_transport).
  • Req 5 (Least Privilege): Integration with IAM Database Authentication.
  • Req 7 (Custom Master User): Defaulted to dbadmin to avoid common admin/root names.
  • Req 14 (Complex Passwords): Recommended integration with AWS Secrets Manager.
  • Req 3.50-01 (Encryption): KMS mandatory for all storage.

(back to top)

Troubleshooting

Connection Timeouts

  • Verify the Security Group allows traffic on the configured port (default 5432 for Postgres).
  • Ensure the calling resource is in a VPC subnet that can route to the database subnets.

IAM Auth Failures

  • Ensure the database user has been created within the DB engine with rds_iam role.
  • Verify the client IAM policy allows rds-db:connect.

(back to top)

Requirements

Name Version
terraform >=1.3

Providers

Name Version
aws n/a

Modules

No modules.

Resources

Name Type
aws_db_instance.this resource
aws_db_parameter_group.this resource
aws_db_proxy.this resource
aws_db_proxy_default_target_group.this resource
aws_db_proxy_target.this resource
aws_db_subnet_group.this resource
aws_kms_alias.rds resource
aws_kms_key.rds resource
aws_rds_cluster.this resource
aws_rds_cluster_instance.this resource
aws_rds_cluster_parameter_group.this resource
aws_caller_identity.current data source

Inputs

Name Description Type Default Required
allocated_storage The allocated storage in gigabytes number 20 no
aurora_instance_count Number of Aurora instances in the cluster number 2 no
aurora_serverless_v2_scaling_configuration Aurora Serverless v2 scaling configuration 
object({
    max_capacity = number
    min_capacity = number
  })
 null no
auto_minor_version_upgrade Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window bool true no
backup_retention_period The days to retain backups for number 7 no
backup_window The daily time range (in UTC) during which automated backups are created if they are enabled string "03:00-06:00" no
ca_cert_identifier The identifier of the CA certificate for the DB instance string "rds-ca-rsa2048-g1" no
create_aurora_cluster Whether to create an Aurora cluster instead of a standard RDS instance bool false no
create_db_proxy Whether to create an RDS Proxy bool false no
create_kms_key Whether to create a KMS key for RDS encryption bool true no
create_parameter_group Whether to create a custom parameter group bool true no
create_read_replica Whether to create a read replica bool false no
custom_parameters Custom parameters to add to the parameter group 
list(object({
    name  = string
    value = string
  }))
 [] no
database_name The name of the database to create when the DB instance is created string null no
database_port The port on which the DB accepts connections number 5432 no
db_proxy_auth Configuration block for DB Proxy authentication 
list(object({
    auth_scheme = string
    description = optional(string)
    iam_auth    = optional(string)
    secret_arn  = string
  }))
 [] no
db_proxy_role_arn ARN of the IAM role for RDS Proxy to access Secrets Manager string "" no
delete_automated_backups Specifies whether to remove automated backups immediately after the DB instance is deleted bool false no
deletion_protection The database can't be deleted when this value is set to true bool true no
enable_enhanced_monitoring Specifies whether Enhanced Monitoring is enabled bool false no
enable_performance_insights Specifies whether Performance Insights are enabled bool true no
enabled_cloudwatch_logs_exports List of log types to enable for exporting to CloudWatch logs list(string) 
[
  "postgresql",
  "upgrade"
]
 no
engine The database engine to use (postgres, mysql, mariadb, oracle-ee, sqlserver-ex, etc.) string "postgres" no
engine_version The engine version to use string "15.4" no
environment Environment (e.g., prod, dev, test) string n/a yes
iam_database_authentication_enabled Specifies whether mapping of AWS Identity and Access Management (IAM) accounts to database accounts is enabled bool true no
instance_class The instance type of the RDS instance string "db.t3.medium" no
kms_key_id The ARN of an existing KMS key to use for encryption string "" no
log_retention_days Specifies the number of days you want to retain log events in the specified log group number 30 no
maintenance_window The window to perform maintenance in string "Mon:00:00-Mon:03:00" no
master_password Password for the master DB user. Note that this may show up in logs, and it is recommended to use Secrets Manager. string n/a yes
master_username Username for the master DB user string "dbadmin" no
max_allocated_storage The upper limit to which Amazon RDS can automatically scale the storage of the DB instance number 100 no
monitoring_role_arn The ARN for the IAM role that permits RDS to send enhanced monitoring metrics to CloudWatch Logs string "" no
multi_az Specifies if the RDS instance is multi-AZ bool true no
mysql_security_parameters Security-focused parameters for MySQL/MariaDB 
list(object({
    name  = string
    value = string
  }))
 
[
  {
    "name": "require_secure_transport",
    "value": "ON"
  },
  {
    "name": "log_warnings",
    "value": "2"
  }
]
 no
name_prefix Prefix for resource names (if not provided, will use project-environment pattern) string "" no
parameter_group_family The family of the DB parameter group string "postgres15" no
parameter_group_name Name of the existing DB parameter group to use (if create_parameter_group is false) string null no
postgres_security_parameters Security-focused parameters for PostgreSQL 
list(object({
    name  = string
    value = string
  }))
 
[
  {
    "name": "rds.force_ssl",
    "value": "1"
  },
  {
    "name": "log_connections",
    "value": "1"
  },
  {
    "name": "log_disconnections",
    "value": "1"
  },
  {
    "name": "log_checkpoints",
    "value": "1"
  },
  {
    "name": "log_lock_waits",
    "value": "1"
  }
]
 no
project_name Name of the project string n/a yes
replica_instance_class The instance type of the RDS read replica string "db.t3.medium" no
security_group_ids List of VPC security groups to associate list(string) n/a yes
skip_final_snapshot Determines whether a final DB snapshot is created before the DB instance is deleted bool false no
snapshot_identifier Specifies whether or not to create this database from a snapshot string null no
storage_type One of 'standard' (magnetic), 'gp2' (general purpose SSD), 'gp3' (general purpose SSD), or 'io1' (provisioned IOPS SSD) string "gp3" no
subnet_ids A list of VPC subnet IDs list(string) n/a yes
tags Additional tags for all resources map(string) {} no

Outputs

Name Description
cluster_endpoint The cluster endpoint
cluster_id The ID of the Aurora cluster
cluster_reader_endpoint The cluster reader endpoint
db_instance_arn The ARN of the RDS instance
db_instance_endpoint The connection endpoint
db_instance_id The RDS instance ID
db_proxy_endpoint The endpoint of the RDS Proxy
db_proxy_id The ID of the RDS Proxy
db_subnet_group_name The name of the DB subnet group
instance_identifier The primary database instance identifier
kms_key_arn The ARN of the KMS key used for encryption
monitoring_role_arn The IAM role ARN used for enhanced monitoring
parameter_group_name The name of the active parameter group