terraform-aws-rds-aurora

Architecture Document — Production-Grade AWS Aurora Cluster Module

Terraform ≥ 1.5.0AWS Provider ≥ 5.20.0MIT License

Executive Summary

This Terraform module deploys production-grade Amazon Aurora clusters supporting both MySQL and PostgreSQL engines. It provides a comprehensive feature set including global databases for cross-region failover, RDS Proxy for connection pooling, Activity Streams for audit compliance, auto-scaling read replicas, serverless configurations, enhanced monitoring, Performance Insights, and security best practices with KMS encryption, IAM authentication, and Secrets Manager integration.

Overview

Engine Support

Aurora MySQL and Aurora PostgreSQL with configurable versions

10+

Resources Managed

Cluster, instances, proxy, global DB, SG, parameter groups, monitoring, auto-scaling

Input Variables

Cluster, auth, network, encryption, backup, monitoring, scaling, global DB config

Outputs

Endpoints, ARNs, proxy, global cluster, SG, monitoring, parameter groups

Architecture Diagram

Global Database Architecture

Global Cluster
(Cross-Region)

→

Primary Region
Aurora Cluster

→

Secondary Region
Aurora Cluster

Cluster Connectivity

Application

→

RDS Proxy
(TLS / IAM)

→

Security
Group

→

Writer
Instance

→

Reader
Instance(s)

Supporting Infrastructure

DB Subnet
Group

Cluster Param
Group

Instance Param
Group

Enhanced
Monitoring

Performance
Insights

Activity
Streams

Component Breakdown

Resource	Purpose
`aws_rds_global_cluster.this`	Global database for cross-region replication and automated failover
`aws_db_subnet_group.this`	Multi-AZ subnet group for cluster placement (minimum 2 subnets)
`aws_rds_cluster_parameter_group.this`	Cluster-level parameter group with dynamic parameters and lifecycle management
`aws_db_parameter_group.this`	Instance-level parameter group for per-instance tuning
`aws_rds_cluster.this`	Aurora cluster with encryption, backups, IAM auth, Secrets Manager, CloudWatch logs
`aws_rds_cluster_instance.this`	Provisioned instances (1-15) with monitoring, Performance Insights, promotion tiers
`aws_rds_cluster_activity_stream.this`	Real-time database activity monitoring via Kinesis Data Streams
`aws_appautoscaling_target/policy`	Auto-scaling read replicas based on CPU utilisation target tracking
`aws_security_group.this`	Least-privilege security group limited to database port from specified sources
`aws_iam_role.monitoring`	IAM role for Enhanced Monitoring metrics collection

Data Flow

Application connects via RDS Proxy (if enabled) or directly to the cluster endpoint
RDS Proxy handles connection pooling, TLS termination, and IAM authentication
Security Group validates source against allowed SG IDs and CIDR blocks on database port only
Writer Instance handles all write operations; changes are replicated to reader instances
Reader Instances serve read-only queries via the reader endpoint with auto-scaling
Auto-scaling adjusts reader count (min/max) based on CPU utilisation target (default: 70%)
Global Cluster replicates data across regions with sub-second replication lag
Activity Streams publish database activity events to Kinesis for audit/compliance
Enhanced Monitoring collects OS-level metrics at configurable intervals (1-60 seconds)
Performance Insights captures query-level performance data with configurable retention

Security Controls

Encryption at Rest

Storage encryption enabled by default. Supports customer-managed KMS keys for key rotation control.

Encryption in Transit

RDS Proxy enforces TLS by default. SSL/TLS natively supported on Aurora connections.

IAM Authentication

Enabled by default. Authenticate with IAM roles instead of database passwords.

Secrets Manager

Master password managed by Secrets Manager with automatic rotation (default: enabled).

Security Groups

Least-privilege ingress: database port only from specified SG IDs and CIDR blocks.

Activity Streams

Real-time audit trail via Kinesis. KMS-encrypted. Supports sync and async modes.

Deletion Protection

Enabled by default. Final snapshot taken on deletion unless explicitly skipped.

Private Access

Instances set to publicly_accessible = false. Only accessible within VPC.

Backup

Automated backups with 7-day retention (configurable up to 35 days). Tags copied to snapshots.

Industry Adaptation

Industry	Use Case	Configuration Focus
Financial Services	Transaction processing with audit trail	Activity Streams (sync), Global DB, 35-day backups, KMS CMK, deletion protection
Healthcare	HIPAA-compliant patient data store	IAM auth, KMS encryption, Enhanced Monitoring, no public access, SG lockdown
E-Commerce	High-read product catalogue	RDS Proxy, auto-scaling readers (2-8), Performance Insights, Aurora MySQL
SaaS	Multi-tenant application database	RDS Proxy connection pooling, Aurora PostgreSQL, auto-scaling, serverless option
Gaming	Low-latency session and leaderboard data	Global DB for latency-based routing, provisioned instances, high IOPS

Production Readiness Checklist

Enable storage encryption with customer-managed KMS key
Use manage_master_user_password = true (Secrets Manager)
Deploy minimum 2 instances across different AZs
Enable deletion protection and disable skip_final_snapshot
Set backup_retention_period to at least 7 days (35 for compliance)
Enable Enhanced Monitoring and Performance Insights
Configure CloudWatch log exports for your engine type
Enable RDS Proxy with TLS for connection pooling
Enable auto-scaling for read replicas with appropriate min/max
Configure allowed_security_group_ids (avoid open CIDR blocks)
Enable Activity Streams for regulated workloads
Consider Global Database for disaster recovery requirements
Tune cluster and instance parameter groups for workload
Set up CloudWatch alarms for CPU, connections, and replication lag
Tag all resources for cost allocation

Configuration Reference

Key Variables

Variable	Type	Default	Description
`cluster_identifier`	string	—	Aurora cluster identifier (required)
`engine`	string	—	aurora-mysql or aurora-postgresql (required)
`engine_version`	string	—	Engine version (required)
`engine_mode`	string	provisioned	provisioned or serverless
`master_username`	string	—	Master database username
`manage_master_user_password`	bool	true	Use Secrets Manager for password
`instance_count`	number	2	Number of cluster instances (1-15)
`instance_class`	string	db.r6g.large	Instance class
`storage_encrypted`	bool	true	Enable encryption at rest
`backup_retention_period`	number	7	Backup retention (1-35 days)
`enable_deletion_protection`	bool	true	Prevent accidental deletion
`enable_rds_proxy`	bool	false	Create RDS Proxy
`enable_global_cluster`	bool	false	Create global database
`autoscaling_enabled`	bool	false	Enable read replica auto-scaling
`autoscaling_target_cpu`	number	70	Target CPU % for auto-scaling
`enable_activity_stream`	bool	false	Enable Activity Streams

Key Outputs

Output	Description
`cluster_endpoint`	Cluster writer endpoint
`reader_endpoint`	Cluster reader endpoint for read-only connections
`proxy_endpoint`	RDS Proxy endpoint (if enabled)
`security_group_id`	Security group ID for the cluster
`global_cluster_id`	Global cluster identifier (if enabled)
`activity_stream_kinesis_stream_name`	Kinesis stream for activity (if enabled)

Cost Estimation

Component	Approximate Monthly Cost
db.r6g.large (2 instances)	~$400
db.r6g.xlarge (3 instances)	~$1,200
db.r6g.2xlarge (3 instances)	~$2,400
RDS Proxy	~$150
Activity Streams	~$50
Performance Insights (7 days)	Free
Global database replication	~$200

Deployment

module "aurora" {
  source = "kogunlowo123/rds-aurora/aws"

  cluster_identifier = "my-aurora-cluster"
  engine             = "aurora-postgresql"
  engine_version     = "15.4"

  master_username             = "dbadmin"
  manage_master_user_password = true
  database_name               = "myapp"

  vpc_id     = "vpc-0123456789abcdef0"
  subnet_ids = ["subnet-aaa", "subnet-bbb", "subnet-ccc"]

  instance_count = 2
  instance_class = "db.r6g.large"

  enable_rds_proxy       = true
  autoscaling_enabled    = true
  autoscaling_max_capacity = 5

  tags = {
    Environment = "production"
  }
}

terraform init
terraform plan
terraform apply