AWS RDS Aurora Terraform module

Terraform module which creates AWS RDS Aurora resources.

Available Features

• Autoscaling of read-replicas
• Global cluster
• Enhanced monitoring
• Serverless cluster (v1 and v2)
• Import from S3
• Fine grained control of individual cluster instances
• Custom endpoints
• RDS multi-AZ support (not Aurora)
• Aurora Limitless
• Aurora DSQL cluster

Usage

module "cluster" {
  source  = "terraform-aws-modules/rds-aurora/aws"

  name           = "test-aurora-db-postgres96"
  engine         = "aurora-postgresql"
  engine_version = "17.5"

  cluster_instance_class = "db.r8g.large"
  instances = {
    one = {}
    two = {
      instance_class = "db.r8g.2xlarge"
    }
  }

  vpc_id               = "vpc-12345678"
  db_subnet_group_name = "db-subnet-group"
  security_group_ingress_rules = {
    ex1_ingress = {
      cidr_ipv4 = "10.20.0.0/20"
    }
    ex1_ingress = {
      referenced_security_group_id = "sg-12345678"
    }
  }

  storage_encrypted   = true
  apply_immediately   = true
  monitoring_interval = 10

  enabled_cloudwatch_logs_exports = ["postgresql"]

  tags = {
    Environment = "dev"
    Terraform   = "true"
  }
}

Cluster Instance Configuration

There are a couple different configuration methods that can be used to create instances within the cluster:

[!NOTE] Only the pertinent attributes are shown for brevity

1. Create homogenous cluster of any number of instances

• Resources created:
  • Writer: 1
  • Reader(s): 2

  cluster_instance_class = "db.r8g.large"
  instances = {
    one   = {}
    two   = {}
    three = {}
  }

2. Create homogenous cluster of instances w/ autoscaling enabled. This is redundant and we'll show why in the next example.

• Resources created:
  • Writer: 1
  • Reader(s):
    • At least 4 readers (2 created directly, 2 created by appautoscaling)
    • At most 7 reader instances (2 created directly, 5 created by appautoscaling)

[!NOTE] Autoscaling uses the instance class specified by cluster_instance_class.

  cluster_instance_class = "db.r8g.large"
  instances = {
    one   = {}
    two   = {}
    three = {}
  }

  autoscaling_enabled      = true
  autoscaling_min_capacity = 2
  autoscaling_max_capacity = 5

3. Create homogeneous cluster scaled via autoscaling. At least one instance (writer) is required

• Resources created:
  • Writer: 1
  • Reader(s):
    • At least 1 reader
    • At most 5 readers

  cluster_instance_class = "db.r8g.large"
  instances = {
    one = {}
  }

  autoscaling_enabled      = true
  autoscaling_min_capacity = 1
  autoscaling_max_capacity = 5

4. Create heterogenous cluster to support mixed-use workloads

   It is common in this configuration to independently control the instance promotion_tier paired with endpoints to create custom endpoints directed at select instances or instance groups.

• Resources created:
  • Writer: 1
  • Readers: 2

  cluster_instance_class = "db.r8g.large"
  instances = {
    one = {
      instance_class      = "db.r8g.2xlarge"
      publicly_accessible = true
    }
    two = {
      identifier     = "static-member-1"
      instance_class = "db.r8g.2xlarge"
    }
    three = {
      identifier     = "excluded-member-1"
      instance_class = "db.r8g.large"
      promotion_tier = 15
    }
  }

5. Create heterogenous cluster to support mixed-use workloads w/ autoscaling enabled

• Resources created:
  • Writer: 1
  • Reader(s):
    • At least 3 readers (2 created directly, 1 created through appautoscaling)
    • At most 7 readers (2 created directly, 5 created through appautoscaling)

[!NOTE] Autoscaling uses the instance class specified by cluster_instance_class.

  cluster_instance_class = "db.r8g.large"
  instances = {
    one = {
      instance_class      = "db.r8g.2xlarge"
      publicly_accessible = true
    }
    two = {
      identifier     = "static-member-1"
      instance_class = "db.r8g.2xlarge"
    }
    three = {
      identifier     = "excluded-member-1"
      instance_class = "db.r8g.large"
      promotion_tier = 15
    }
  }

  autoscaling_enabled      = true
  autoscaling_min_capacity = 1
  autoscaling_max_capacity = 5

Conditional Creation

The following values are provided to toggle on/off creation of the associated resources as desired:

# This RDS cluster will not be created
module "cluster" {
  source  = "terraform-aws-modules/rds-aurora/aws"

  # Disable creation of cluster and all resources
  create = false

  # Disable creation of subnet group - provide a subnet group
  create_db_subnet_group = false

  # Disable creation of security group - provide a security group
  create_security_group = false

  # Disable creation of monitoring IAM role - provide a role ARN
  create_monitoring_role = false

  # ... omitted
}

Examples

• Autoscaling: A PostgreSQL cluster with enhanced monitoring and autoscaling enabled
• DSQL: Multi region and single region DSQL clusters
• Global Cluster: A PostgreSQL global cluster with clusters provisioned in two different region
• Limitless: A PostgreSQL Limitless cluster
• Multi-AZ: A multi-AZ RDS cluster (not using Aurora engine)
• MySQL: A simple MySQL cluster
• PostgreSQL: A simple PostgreSQL cluster
• S3 Import: A MySQL cluster created from a Percona Xtrabackup stored in S3
• Serverless: Serverless V1 and V2 (PostgreSQL and MySQL)

Documentation

Terraform documentation is generated automatically using pre-commit hooks. Follow installation instructions here.

Authors

Module is maintained by Anton Babenko with help from these awesome contributors.

License

Apache 2 Licensed. See LICENSE for full details.

Additional information for users from Russia and Belarus

• Russia has illegally annexed Crimea in 2014 and brought the war in Donbas followed by full-scale invasion of Ukraine in 2022.
• Russia has brought sorrow and devastations to millions of Ukrainians, killed hundreds of innocent people, damaged thousands of buildings, and forced several million people to flee.
• Putin khuylo!