README.md

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)

Usage

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

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

  vpc_id               = "vpc-12345678"
  db_subnet_group_name = "db-subnet-group"
  security_group_rules = {
    ex1_ingress = {
      cidr_blocks = ["10.20.0.0/20"]
    }
    ex1_ingress = {
      source_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:

ℹ️ 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 = 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
• Global Cluster: A PostgreSQL global cluster with clusters provisioned in two different region
• 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

Name	Version
terraform	>= 1.0
aws	>= 5.26

Providers

Name	Version
aws	>= 5.26

Modules

No modules.

Resources

Name	Type
aws_appautoscaling_policy.this	resource
aws_appautoscaling_target.this	resource
aws_cloudwatch_log_group.this	resource
aws_db_parameter_group.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_activity_stream.this	resource
aws_rds_cluster_endpoint.this	resource
aws_rds_cluster_instance.this	resource
aws_rds_cluster_parameter_group.this	resource
aws_rds_cluster_role_association.this	resource
aws_security_group.this	resource
aws_security_group_rule.this	resource
aws_iam_policy_document.monitoring_rds_assume_role	data source
aws_partition.current	data source

Inputs

Name	Description	Type	Default	Required
allocated_storage	The amount of storage in gibibytes (GiB) to allocate to each DB instance in the Multi-AZ DB cluster. (This setting is required to create a Multi-AZ DB cluster)	number	null	no
allow_major_version_upgrade	Enable to allow major engine version upgrades when changing engine versions. Defaults to false	bool	false	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_policy_name	Autoscaling policy name	string	"target-metric"	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
availability_zones	List of EC2 Availability Zones for the DB cluster storage where DB cluster instances can be created. RDS automatically assigns 3 AZs if less than 3 AZs are configured, which will show as a difference requiring resource recreation next Terraform apply	list(string)	null	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	number	null	no
ca_cert_identifier	The identifier of the CA certificate for the DB instance	string	null	no
cloudwatch_log_group_kms_key_id	The ARN of the KMS Key to use when encrypting log data	string	null	no
cloudwatch_log_group_retention_in_days	The number of days to retain CloudWatch logs for the DB instance	number	7	no
cluster_members	List of RDS Instances that are a part of this cluster	list(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
cluster_use_name_prefix	Whether to use name as a prefix for the cluster	bool	false	no
copy_tags_to_snapshot	Copy all Cluster tags to snapshots	bool	null	no
create	Whether cluster should be created (affects nearly all resources)	bool	true	no
create_cloudwatch_log_group	Determines whether a CloudWatch log group is created for each enabled_cloudwatch_logs_exports	bool	false	no
create_db_cluster_activity_stream	Determines whether a cluster activity stream is created.	bool	false	no
create_db_cluster_parameter_group	Determines whether a cluster parameter should be created or use existing	bool	false	no
create_db_parameter_group	Determines whether a DB parameter should be created or use existing	bool	false	no
create_db_subnet_group	Determines whether to create the database subnet group or use existing	bool	false	no
create_monitoring_role	Determines whether to create the IAM role for RDS enhanced monitoring	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_activity_stream_kms_key_id	The AWS KMS key identifier for encrypting messages in the database activity stream	string	null	no
db_cluster_activity_stream_mode	Specifies the mode of the database activity stream. Database events such as a change or access generate an activity stream event. One of: sync, async	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_instance_class	The compute and memory capacity of each DB instance in the Multi-AZ DB cluster, for example db.m6g.xlarge. Not all DB instance classes are available in all AWS Regions, or for all database engines	string	null	no
db_cluster_parameter_group_description	The description of the DB cluster parameter group. Defaults to "Managed by Terraform"	string	null	no
db_cluster_parameter_group_family	The family of the DB cluster parameter group	string	""	no
db_cluster_parameter_group_name	The name of the DB cluster parameter group	string	null	no
db_cluster_parameter_group_parameters	A list of DB cluster parameters to apply. Note that parameters may differ from a family to an other	list(map(string))	[]	no
db_cluster_parameter_group_use_name_prefix	Determines whether the DB cluster parameter group name is used as a prefix	bool	true	no
db_parameter_group_description	The description of the DB parameter group. Defaults to "Managed by Terraform"	string	null	no
db_parameter_group_family	The family of the DB parameter group	string	""	no
db_parameter_group_name	The name of the DB parameter group	string	null	no
db_parameter_group_parameters	A list of DB parameters to apply. Note that parameters may differ from a family to an other	list(map(string))	[]	no
db_parameter_group_use_name_prefix	Determines whether the DB parameter group name is used as a prefix	bool	true	no
db_subnet_group_name	The name of the subnet group name (existing or created)	string	""	no
delete_automated_backups	Specifies whether to remove automated backups immediately after the DB cluster is deleted	bool	null	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	"provisioned"	no
engine_native_audit_fields_included	Specifies whether the database activity stream includes engine-native audit fields. This option only applies to an Oracle DB instance. By default, no engine-native audit fields are included	bool	false	no
engine_version	The database engine version. Updating this argument results in an outage	string	null	no
final_snapshot_identifier	The name of your final DB snapshot when this DB cluster is deleted. If omitted, no final snapshot will be made	string	null	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
iops	The amount of Provisioned IOPS (input/output operations per second) to be initially allocated for each DB instance in the Multi-AZ DB cluster	number	null	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
manage_master_user_password	Set to true to allow RDS to manage the master user password in Secrets Manager. Cannot be set if master_password is provided	bool	true	no
master_password	Password for the master DB user. Note that this may show up in logs, and it will be stored in the state file. Required unless manage_master_user_password is set to true or unless snapshot_identifier or replication_source_identifier is provided or unless a global_cluster_identifier is provided when the cluster is the secondary cluster of a global database	string	null	no
master_user_secret_kms_key_id	The Amazon Web Services KMS key identifier is the key ARN, key ID, alias ARN, or alias name for the KMS key	string	null	no
master_username	Username for the master DB user. Required unless snapshot_identifier or replication_source_identifier is provided or unless a global_cluster_identifier is provided when the cluster is the secondary cluster of a global database	string	null	no
monitoring_interval	The interval, in seconds, between points when Enhanced Monitoring metrics are collected for instances. Set to 0 to disable. 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
network_type	The type of network stack to use (IPV4 or DUAL)	string	null	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
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)	{}	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_name	The security group name. Default value is (var.name)	string	""	no
security_group_rules	Map of security group rules to add to the cluster security group created	any	{}	no
security_group_tags	Additional tags for the security group	map(string)	{}	no
security_group_use_name_prefix	Determines whether the security group name (var.name) is used as a prefix	bool	true	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	false	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
storage_type	Determines the storage type for the DB cluster. Optional for Single-AZ, required for Multi-AZ DB clusters. Valid values for Single-AZ: aurora, "" (default, both refer to Aurora Standard), aurora-iopt1 (Aurora I/O Optimized). Valid values for Multi-AZ: io1 (default).	string	null	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 security group created	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_user_secret	The generated database master user secret when manage_master_user_password is set to true
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_cluster_activity_stream_kinesis_stream_name	The name of the Amazon Kinesis data stream to be used for the database activity stream
db_cluster_cloudwatch_log_groups	Map of CloudWatch log groups created and their attributes
db_cluster_parameter_group_arn	The ARN of the DB cluster parameter group created
db_cluster_parameter_group_id	The ID of the DB cluster parameter group created
db_parameter_group_arn	The ARN of the DB parameter group created
db_parameter_group_id	The ID of the DB parameter group created
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!