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
• 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

1. Create homogenous cluster of any number of instances

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

  instance_class = "db.r6g.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)

ℹ️ 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

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

  instance_class = "db.r6g.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

  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
    }
  }

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)

ℹ️ 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 PostgreSQL and MySQL clusters

Documentation

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

Requirements

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

Providers

Name	Version
aws	>= 3.63
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
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 databae 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
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_tags	Additional tags for the security group	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.