Terraform module which creates AWS RDS Aurora resources.
- Autoscaling of read-replicas
- Global cluster
- Enhanced monitoring
- Serverless cluster
- Import from S3
- Fine grained control of individual cluster instances
- Custom endpoints
- Cluster parameter group
- Parameter group
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"
}
}
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 withendpoints
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
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
}
- 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
Terraform documentation is generated automatically using pre-commit hooks. Follow installation instructions here.
Name | Version |
---|---|
terraform | >= 0.13 |
aws | >= 3.63 |
random | >= 2.2 |
Name | Version |
---|---|
aws | >= 3.63 |
random | >= 2.2 |
No modules.
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 |
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_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 |
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 |
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 |
Module is maintained by Anton Babenko with help from these awesome contributors.
Apache 2 Licensed. See LICENSE for full details.