Skip to content

terraform-aws-modules/terraform-aws-rds-aurora

AWS RDS Aurora Terraform module

Terraform module which creates AWS RDS Aurora resources.

SWUbanner

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 = {}
  }
  1. 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
  1. 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
  1. 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
    }
  }
  1. 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.59

Providers

Name Version
aws >= 5.59

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_secretsmanager_secret_rotation.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_class Specified the log class of the log group. Possible values are: STANDARD or INFREQUENT_ACCESS 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
cloudwatch_log_group_skip_destroy Set to true if you do not wish the log group (and any logs it may contain) to be deleted at destroy time, and instead just remove the log group from the Terraform state bool null no
cluster_ca_cert_identifier The CA certificate identifier to use for the DB cluster's server certificate. Currently only supported for multi-az DB clusters string null 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
domain The ID of the Directory Service Active Directory domain to create the instance in string null no
domain_iam_role_name (Required if domain is provided) The name of the IAM role to be used when making API calls to the Directory Service string 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
enable_local_write_forwarding Whether read replicas can forward write operations to the writer DB instance in the DB cluster. By default, write operations aren't allowed on reader DB instances. 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_lifecycle_support The life cycle type for this DB instance. This setting is valid for cluster types Aurora DB clusters and Multi-AZ DB clusters. Valid values are open-source-rds-extended-support, open-source-rds-extended-support-disabled. Default value is open-source-rds-extended-support. 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
manage_master_user_password_rotation Whether to manage the master user password rotation. Setting this value to false after previously having been set to true will disable automatic rotation. bool false 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_password_rotate_immediately Specifies whether to rotate the secret immediately or wait until the next scheduled rotation window. bool null no
master_user_password_rotation_automatically_after_days Specifies the number of days between automatic scheduled rotations of the secret. Either master_user_password_rotation_automatically_after_days or master_user_password_rotation_schedule_expression must be specified number null no
master_user_password_rotation_duration The length of the rotation window in hours. For example, 3h for a three hour window. string null no
master_user_password_rotation_schedule_expression A cron() or rate() expression that defines the schedule for rotating your secret. Either master_user_password_rotation_automatically_after_days or master_user_password_rotation_schedule_expression must be specified 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_ca_certificate_identifier CA identifier of the CA certificate used for the DB instance's server certificate
cluster_ca_certificate_valid_till Expiration date of the DB instance’s server certificate
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_cluster_secretsmanager_secret_rotation_enabled Specifies whether automatic rotation is enabled for the secret
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