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

Usage

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

  name           = "test-aurora-db-postgres96"
  engine         = "aurora-postgresql"
  engine_version = "11.12"
  instance_class = "db.r6g.large"
  instances = {
    one = {}
    2 = {
      instance_class = "db.r6g.2xlarge"
    }
  }

  vpc_id  = "vpc-12345678"
  subnets = ["subnet-12345678", "subnet-87654321"]

  allowed_security_groups = ["sg-12345678"]
  allowed_cidr_blocks     = ["10.20.0.0/20"]

  storage_encrypted   = true
  apply_immediately   = true
  monitoring_interval = 10

  db_parameter_group_name         = "default"
  db_cluster_parameter_group_name = "default"

  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:

ℹ️ Only the pertinent attributes are shown for brevity

Create homogenous cluster of any number of instances

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

  instance_class = "db.r6g.large"
  instances = {
    one   = {}
    two   = {}
    three = {}
  }

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)

ℹ️ Autoscaling uses the instance class specified by instance_class.

  instance_class = "db.r6g.large"
  instances = {
    one   = {}
    two   = {}
    three = {}
  }

  autoscaling_enabled      = true
  autoscaling_min_capacity = 2
  autoscaling_max_capacity = 5

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

  instance_class = "db.r6g.large"
  instances = {
    one = {}
  }

  autoscaling_enabled      = true
  autoscaling_min_capacity = 1
  autoscaling_max_capacity = 5

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

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

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)

ℹ️ Autoscaling uses the instance class specified by instance_class.

  instance_class = "db.r5.large"
  instances = {
    one = {
      instance_class      = "db.r5.2xlarge"
      publicly_accessible = true
    }
    two = {
      identifier     = "static-member-1"
      instance_class = "db.r5.2xlarge"
    }
    three = {
      identifier     = "excluded-member-1"
      instance_class = "db.r5.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_cluster = 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

  # Disable creation of random password - AWS API provides the password
  create_random_password = false

  # ... omitted
}

Examples

Autoscaling: A PostgreSQL cluster with enhanced monitoring and autoscaling enabled
Global Cluster: A PostgreSQL global cluster with clusters provisioned in two different region
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

Name	Version
terraform	>= 0.13
aws	>= 4.12
random	>= 2.2

Providers

Name	Version
aws	>= 4.12
random	>= 2.2

Modules

No modules.

Resources

Name	Type
aws_appautoscaling_policy.this	resource
aws_appautoscaling_target.this	resource
aws_db_subnet_group.this	resource
aws_iam_role.rds_enhanced_monitoring	resource
aws_iam_role_policy_attachment.rds_enhanced_monitoring	resource
aws_rds_cluster.this	resource
aws_rds_cluster_endpoint.this	resource
aws_rds_cluster_instance.this	resource
aws_rds_cluster_role_association.this	resource
aws_security_group.this	resource
aws_security_group_rule.cidr_ingress	resource
aws_security_group_rule.default_ingress	resource
aws_security_group_rule.egress	resource
random_id.snapshot_identifier	resource
random_password.master_password	resource
aws_iam_policy_document.monitoring_rds_assume_role	data source
aws_partition.current	data source

Inputs

Name	Description	Type	Default	Required
allow_major_version_upgrade	Enable to allow major engine version upgrades when changing engine versions. Defaults to `false`	`bool`	`false`	no
allowed_cidr_blocks	A list of CIDR blocks which are allowed to access the database	`list(string)`	`[]`	no
allowed_security_groups	A list of Security Group ID's to allow access to	`list(string)`	`[]`	no
apply_immediately	Specifies whether any cluster modifications are applied immediately, or during the next maintenance window. Default is `false`	`bool`	`null`	no
auto_minor_version_upgrade	Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window. Default `true`	`bool`	`null`	no
autoscaling_enabled	Determines whether autoscaling of the cluster read replicas is enabled	`bool`	`false`	no
autoscaling_max_capacity	Maximum number of read replicas permitted when autoscaling is enabled	`number`	`2`	no
autoscaling_min_capacity	Minimum number of read replicas permitted when autoscaling is enabled	`number`	`0`	no
autoscaling_scale_in_cooldown	Cooldown in seconds before allowing further scaling operations after a scale in	`number`	`300`	no
autoscaling_scale_out_cooldown	Cooldown in seconds before allowing further scaling operations after a scale out	`number`	`300`	no
autoscaling_target_connections	Average number of connections threshold which will initiate autoscaling. Default value is 70% of db.r4/r5/r6g.large's default max_connections	`number`	`700`	no
autoscaling_target_cpu	CPU threshold which will initiate autoscaling	`number`	`70`	no
backtrack_window	The target backtrack window, in seconds. Only available for `aurora` engine currently. To disable backtracking, set this value to 0. Must be between 0 and 259200 (72 hours)	`number`	`null`	no
backup_retention_period	The days to retain backups for. Default `7`	`number`	`7`	no
ca_cert_identifier	The identifier of the CA certificate for the DB instance	`string`	`null`	no
cluster_tags	A map of tags to add to only the cluster. Used for AWS Instance Scheduler tagging	`map(string)`	`{}`	no
cluster_timeouts	Create, update, and delete timeout configurations for the cluster	`map(string)`	`{}`	no
copy_tags_to_snapshot	Copy all Cluster `tags` to snapshots	`bool`	`null`	no
create_cluster	Whether cluster should be created (affects nearly all resources)	`bool`	`true`	no
create_db_subnet_group	Determines whether to create the database subnet group or use existing	`bool`	`true`	no
create_monitoring_role	Determines whether to create the IAM role for RDS enhanced monitoring	`bool`	`true`	no
create_random_password	Determines whether to create random password for RDS primary cluster	`bool`	`true`	no
create_security_group	Determines whether to create security group for RDS cluster	`bool`	`true`	no
database_name	Name for an automatically created database on cluster creation	`string`	`null`	no
db_cluster_db_instance_parameter_group_name	Instance parameter group to associate with all instances of the DB cluster. The `db_cluster_db_instance_parameter_group_name` is only valid in combination with `allow_major_version_upgrade`	`string`	`null`	no
db_cluster_parameter_group_name	A cluster parameter group to associate with the cluster	`string`	`null`	no
db_parameter_group_name	The name of the DB parameter group to associate with instances	`string`	`null`	no
db_subnet_group_name	The name of the subnet group name (existing or created)	`string`	`""`	no
deletion_protection	If the DB instance should have deletion protection enabled. The database can't be deleted when this value is set to `true`. The default is `false`	`bool`	`null`	no
enable_global_write_forwarding	Whether cluster should forward writes to an associated global cluster. Applied to secondary clusters to enable them to forward writes to an `aws_rds_global_cluster`'s primary cluster	`bool`	`null`	no
enable_http_endpoint	Enable HTTP endpoint (data API). Only valid when engine_mode is set to `serverless`	`bool`	`null`	no
enabled_cloudwatch_logs_exports	Set of log types to export to cloudwatch. If omitted, no logs will be exported. The following log types are supported: `audit`, `error`, `general`, `slowquery`, `postgresql`	`list(string)`	`[]`	no
endpoints	Map of additional cluster endpoints and their attributes to be created	`any`	`{}`	no
engine	The name of the database engine to be used for this DB cluster. Defaults to `aurora`. Valid Values: `aurora`, `aurora-mysql`, `aurora-postgresql`	`string`	`null`	no
engine_mode	The database engine mode. Valid values: `global`, `multimaster`, `parallelquery`, `provisioned`, `serverless`. Defaults to: `provisioned`	`string`	`null`	no
engine_version	The database engine version. Updating this argument results in an outage	`string`	`null`	no
final_snapshot_identifier_prefix	The prefix name to use when creating a final snapshot on cluster destroy; a 8 random digits are appended to name to ensure it's unique	`string`	`"final"`	no
global_cluster_identifier	The global cluster identifier specified on `aws_rds_global_cluster`	`string`	`null`	no
iam_database_authentication_enabled	Specifies whether or mappings of AWS Identity and Access Management (IAM) accounts to database accounts is enabled	`bool`	`null`	no
iam_role_description	Description of the monitoring role	`string`	`null`	no
iam_role_force_detach_policies	Whether to force detaching any policies the monitoring role has before destroying it	`bool`	`null`	no
iam_role_managed_policy_arns	Set of exclusive IAM managed policy ARNs to attach to the monitoring role	`list(string)`	`null`	no
iam_role_max_session_duration	Maximum session duration (in seconds) that you want to set for the monitoring role	`number`	`null`	no
iam_role_name	Friendly name of the monitoring role	`string`	`null`	no
iam_role_path	Path for the monitoring role	`string`	`null`	no
iam_role_permissions_boundary	The ARN of the policy that is used to set the permissions boundary for the monitoring role	`string`	`null`	no
iam_role_use_name_prefix	Determines whether to use `iam_role_name` as is or create a unique name beginning with the `iam_role_name` as the prefix	`bool`	`false`	no
iam_roles	Map of IAM roles and supported feature names to associate with the cluster	`map(map(string))`	`{}`	no
instance_class	Instance type to use at master instance. Note: if `autoscaling_enabled` is `true`, this will be the same instance class used on instances created by autoscaling	`string`	`""`	no
instance_timeouts	Create, update, and delete timeout configurations for the cluster instance(s)	`map(string)`	`{}`	no
instances	Map of cluster instances and any specific/overriding attributes to be created	`any`	`{}`	no
instances_use_identifier_prefix	Determines whether cluster instance identifiers are used as prefixes	`bool`	`false`	no
is_primary_cluster	Determines whether cluster is primary cluster with writer instance (set to `false` for global cluster and replica clusters)	`bool`	`true`	no
kms_key_id	The ARN for the KMS encryption key. When specifying `kms_key_id`, `storage_encrypted` needs to be set to `true`	`string`	`null`	no
master_password	Password for the master DB user. Note - when specifying a value here, 'create_random_password' should be set to `false`	`string`	`null`	no
master_username	Username for the master DB user	`string`	`"root"`	no
monitoring_interval	The interval, in seconds, between points when Enhanced Monitoring metrics are collected for instances. Set to `0` to disble. Default is `0`	`number`	`0`	no
monitoring_role_arn	IAM role used by RDS to send enhanced monitoring metrics to CloudWatch	`string`	`""`	no
name	Name used across resources created	`string`	`""`	no
performance_insights_enabled	Specifies whether Performance Insights is enabled or not	`bool`	`null`	no
performance_insights_kms_key_id	The ARN for the KMS key to encrypt Performance Insights data	`string`	`null`	no
performance_insights_retention_period	Amount of time in days to retain Performance Insights data. Either 7 (7 days) or 731 (2 years)	`number`	`null`	no
port	The port on which the DB accepts connections	`string`	`null`	no
predefined_metric_type	The metric type to scale on. Valid values are `RDSReaderAverageCPUUtilization` and `RDSReaderAverageDatabaseConnections`	`string`	`"RDSReaderAverageCPUUtilization"`	no
preferred_backup_window	The daily time range during which automated backups are created if automated backups are enabled using the `backup_retention_period` parameter. Time in UTC	`string`	`"02:00-03:00"`	no
preferred_maintenance_window	The weekly time range during which system maintenance can occur, in (UTC)	`string`	`"sun:05:00-sun:06:00"`	no
publicly_accessible	Determines whether instances are publicly accessible. Default false	`bool`	`null`	no
putin_khuylo	Do you agree that Putin doesn't respect Ukrainian sovereignty and territorial integrity? More info: https://en.wikipedia.org/wiki/Putin_khuylo!	`bool`	`true`	no
random_password_length	Length of random password to create. Defaults to `10`	`number`	`10`	no
replication_source_identifier	ARN of a source DB cluster or DB instance if this DB cluster is to be created as a Read Replica	`string`	`null`	no
restore_to_point_in_time	Map of nested attributes for cloning Aurora cluster	`map(string)`	`{}`	no
s3_import	Configuration map used to restore from a Percona Xtrabackup in S3 (only MySQL is supported)	`map(string)`	`null`	no
scaling_configuration	Map of nested attributes with scaling properties. Only valid when `engine_mode` is set to `serverless`	`map(string)`	`{}`	no
security_group_description	The description of the security group. If value is set to empty string it will contain cluster name in the description	`string`	`null`	no
security_group_egress_rules	A map of security group egress rule defintions to add to the security group created	`map(any)`	`{}`	no
security_group_tags	Additional tags for the security group	`map(string)`	`{}`	no
serverlessv2_scaling_configuration	Map of nested attributes with serverless v2 scaling properties. Only valid when `engine_mode` is set to `provisioned`	`map(string)`	`{}`	no
skip_final_snapshot	Determines whether a final snapshot is created before the cluster is deleted. If true is specified, no snapshot is created	`bool`	`null`	no
snapshot_identifier	Specifies whether or not to create this cluster from a snapshot. You can use either the name or ARN when specifying a DB cluster snapshot, or the ARN when specifying a DB snapshot	`string`	`null`	no
source_region	The source region for an encrypted replica DB cluster	`string`	`null`	no
storage_encrypted	Specifies whether the DB cluster is encrypted. The default is `true`	`bool`	`true`	no
subnets	List of subnet IDs used by database subnet group created	`list(string)`	`[]`	no
tags	A map of tags to add to all resources	`map(string)`	`{}`	no
vpc_id	ID of the VPC where to create security group	`string`	`""`	no
vpc_security_group_ids	List of VPC security groups to associate to the cluster in addition to the SG we create in this module	`list(string)`	`[]`	no

Outputs

Name	Description
additional_cluster_endpoints	A map of additional cluster endpoints and their attributes
cluster_arn	Amazon Resource Name (ARN) of cluster
cluster_database_name	Name for an automatically created database on cluster creation
cluster_endpoint	Writer endpoint for the cluster
cluster_engine_version_actual	The running version of the cluster database
cluster_hosted_zone_id	The Route53 Hosted Zone ID of the endpoint
cluster_id	The RDS Cluster Identifier
cluster_instances	A map of cluster instances and their attributes
cluster_master_password	The database master password
cluster_master_username	The database master username
cluster_members	List of RDS Instances that are a part of this cluster
cluster_port	The database port
cluster_reader_endpoint	A read-only endpoint for the cluster, automatically load-balanced across replicas
cluster_resource_id	The RDS Cluster Resource ID
cluster_role_associations	A map of IAM roles associated with the cluster and their attributes
db_subnet_group_name	The db subnet group name
enhanced_monitoring_iam_role_arn	The Amazon Resource Name (ARN) specifying the enhanced monitoring role
enhanced_monitoring_iam_role_name	The name of the enhanced monitoring role
enhanced_monitoring_iam_role_unique_id	Stable and unique string identifying the enhanced monitoring role
security_group_id	The security group ID of the cluster

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!

samirpdl/terraform-aws-rds-aurora