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:

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)

  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)

  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.

Requirements

Providers

Modules

No modules.

Resources

Inputs

object({
    include_audit_fields = optional(bool, false)
    kms_key_id           = string
    mode                 = string
  })

object({
    name            = optional(string)
    use_name_prefix = optional(bool, true)
    description     = optional(string)
    family          = string
    parameters = optional(list(object({
      name         = string
      value        = string
      apply_method = optional(string, "immediate")
    })))
  })

object({
    create = optional(string)
    update = optional(string)
    delete = optional(string)
  })

object({
    name            = optional(string)
    use_name_prefix = optional(bool, true)
    description     = optional(string)
    family          = string
    parameters = optional(list(object({
      name         = string
      value        = string
      apply_method = optional(string, "immediate")
    })))
  })

map(object({
    identifier       = string
    type             = string
    excluded_members = optional(list(string))
    static_members   = optional(list(string))
    tags             = optional(map(string), {})
  }))

object({
    create = optional(string)
    update = optional(string)
    delete = optional(string)
  })

map(object({
    apply_immediately                     = optional(bool)
    auto_minor_version_upgrade            = optional(bool)
    availability_zone                     = optional(string)
    ca_cert_identifier                    = optional(string)
    copy_tags_to_snapshot                 = optional(bool, true)
    custom_iam_instance_profile           = optional(string)
    db_parameter_group_name               = optional(string)
    db_subnet_group_name                  = optional(string)
    identifier                            = optional(string)
    identifier_prefix                     = optional(string)
    instance_class                        = optional(string)
    monitoring_interval                   = optional(number)
    monitoring_role_arn                   = optional(string)
    performance_insights_enabled          = optional(bool)
    performance_insights_kms_key_id       = optional(string)
    performance_insights_retention_period = optional(number)
    preferred_maintenance_window          = optional(string)
    promotion_tier                        = optional(number)
    publicly_accessible                   = optional(bool)
    tags                                  = optional(map(string), {})
  }))

object({
    restore_to_time            = optional(string)
    restore_type               = optional(string)
    source_cluster_identifier  = optional(string)
    source_cluster_resource_id = optional(string)
    use_latest_restorable_time = optional(bool)
  })

map(object({
    feature_name = optional(string)
    role_arn     = string
  }))

object({
    bucket_name           = string
    bucket_prefix         = optional(string)
    ingestion_role        = string
    source_engine_version = string
  })

object({
    auto_pause               = optional(bool)
    max_capacity             = optional(number)
    min_capacity             = optional(number)
    seconds_before_timeout   = optional(number)
    seconds_until_auto_pause = optional(number)
    timeout_action           = optional(string)
  })

map(object({
    name = optional(string)

    cidr_ipv4                    = optional(string)
    cidr_ipv6                    = optional(string)
    description                  = optional(string)
    from_port                    = optional(number)
    ip_protocol                  = optional(string, "tcp")
    prefix_list_id               = optional(string)
    referenced_security_group_id = optional(string)
    region                       = optional(string)
    tags                         = optional(map(string), {})
    to_port                      = optional(number)
  }))

map(object({
    name = optional(string)

    cidr_ipv4                    = optional(string)
    cidr_ipv6                    = optional(string)
    description                  = optional(string)
    from_port                    = optional(number)
    ip_protocol                  = optional(string, "tcp")
    prefix_list_id               = optional(string)
    referenced_security_group_id = optional(string)
    region                       = optional(string)
    tags                         = optional(map(string), {})
    to_port                      = optional(number)
  }))

object({
    max_capacity             = number
    min_capacity             = optional(number)
    seconds_until_auto_pause = optional(number)
  })

object({
    compute_redundancy  = optional(number)
    identifier          = string
    max_acu             = number
    min_acu             = optional(number)
    publicly_accessible = optional(bool)
    tags                = optional(map(string), {})
    timeouts = optional(object({
      create = optional(string)
      update = optional(string)
      delete = optional(string)
    }))
  })

Outputs

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!