Skip to main content
Data Storage Modules 0.32Last updated in version 0.31.4

RDS Read Replicas Module

View SourceRelease Notes

This module creates a read replica (read-only copy) of a DB instance.

About RDS Read Replicas

A read replica is a read-only copy of a DB instance. You can reduce the load on your primary DB instance by routing queries from your applications to the read replica. Refer to Working with DB instance read replicas for more information.

Promoting Read Replica as Primary

For disaster recovery, you may need to promote a read replica as a primary instance. Promoting an RDS replica to be a primary instance is not a supported operation in Terraform and requires direct interaction with AWS APIs. Subsequent steps are then required to ensure your Terraform state is up-to-date. Please see the following walk-through for steps to promote a replica to primary.

  1. Promote the replica: Run AWS CLI command to promote read replica as primary with the following command:
aws rds promote-read-replica \
--db-instance-identifier <replica-identifier> \
--region <region>

Note: This command triggers the promotion process and takes an additional 30-60 mins to complete the modification.

  1. Update the Terraform configuration: Modify your Terraform configuration file (e.g., main.tf) to reflect the new state. There's no way to automatically reflect the new state in terraform.
  2. Import the new primary instance into Terraform state: Run the terraform import command. This command associates the resource in your Terraform configuration with the existing resource in AWS.
terraform import aws_db_instance.<identifier> <primary_instance_arn>
  1. Refresh the Terraform state: Run terraform refresh to fetch the current state of the primary instance from AWS and update the Terraform state file accordingly. This ensures that Terraform is aware of the new primary instance's attributes.
  2. Verify the Terraform plan: Run terraform plan to review the changes that Terraform will apply based on the updated configuration and current state. Make sure the plan reflects the desired changes, including the new primary instance attributes.
  3. Apply the Terraform changes: If the plan looks correct, apply the changes by running terraform apply. Terraform will update the resources to match the desired configuration, reflecting the newly promoted primary instance.

Sample Usage

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S RDS-REPLICAS MODULE
# ------------------------------------------------------------------------------------------------------

module "rds_replicas" {

source = "git::git@github.com:gruntwork-io/terraform-aws-data-storage.git//modules/rds-replicas?ref=v0.32"

# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------

# The instance type to use for the db (e.g. db.t2.micro)
instance_type = <string>

# The name used to namespace all resources created by these templates,
# including the DB instance (e.g. drupaldb). Must be unique for this region.
# May contain only lowercase alphanumeric characters, hyphens, underscores,
# periods, and spaces.
name = <string>

# The port the DB will listen on (e.g. 3306)
port = <number>

# An ID of the primary DB instance to create read replicas from
primary_instance_id = <string>

# The id of the VPC in which this DB should be deployed.
vpc_id = <string>

# ----------------------------------------------------------------------------------------------------
# OPTIONAL VARIABLES
# ----------------------------------------------------------------------------------------------------

# List of IDs of AWS Security Groups to attach to the read replica RDS
# instance.
additional_security_group_ids = []

# A list of CIDR-formatted IP address ranges that can connect to read replica
# instances. If not set read replica instances will use the same security
# group as master instance.
allow_connections_from_cidr_blocks = []

# A list of Security Groups that can connect to read replica instances. If not
# set read replica instances will use the same security group as master
# instance.
allow_connections_from_security_groups = []

# Indicates whether major version upgrades (e.g. 9.4.x to 9.5.x) will ever be
# permitted. Note that these updates must always be manually performed and
# will never automatically applied.
allow_major_version_upgrade = true

# The availability zones within which it should be possible to spin up
# replicas
allowed_replica_zones = []

# Specifies whether any cluster modifications are applied immediately, or
# during the next maintenance window. Note that cluster modifications may
# cause degraded performance or downtime.
apply_immediately = false

# Indicates that minor engine upgrades will be applied automatically to the DB
# instance during the maintenance window. If set to true, you should set
# var.engine_version to MAJOR.MINOR and omit the .PATCH at the end (e.g., use
# 5.7 and not 5.7.11); otherwise, you'll get Terraform state drift. See
# https://www.terraform.io/docs/providers/aws/r/db_instance.html#engine_version
# for more details.
auto_minor_version_upgrade = true

# The description of the aws_db_subnet_group that is created. Defaults to
# 'Subnet group for the var.name DB' if not specified.
aws_db_subnet_group_description = null

# The name of the aws_db_subnet_group that is created, or an existing one to
# use if create_subnet_group is false. Defaults to var.name if not specified.
aws_db_subnet_group_name = null

# How many days to keep backup snapshots around before cleaning them up. Must
# be 1 or greater to support read replicas. 0 means disable automated backups.
backup_retention_period = 21

# The daily time range during which automated backups are created (e.g.
# 04:00-09:00). Time zone is UTC. Performance may be degraded while a backup
# runs.
backup_window = null

# The Certificate Authority (CA) certificates bundle to use on the RDS
# instance.
ca_cert_identifier = null

# Copy all the RDS instance tags to snapshots. Default is false.
copy_tags_to_snapshot = false

# When working with read replicas, only configure db subnet group if the
# source database specifies an instance in another AWS Region. If true, it
# will create a new subnet group.
create_subnet_group = false

# Timeout for DB creating
creating_timeout = "40m"

# A map of custom tags to apply to the RDS Instance and the Security Group
# created for it. The key is the tag name and the value is the tag value.
custom_tags = {}

# Specifies whether to remove automated backups immediately after the DB
# instance is deleted
delete_automated_backups = null

# Timeout for DB deleting
deleting_timeout = "60m"

# The database can't be deleted when this value is set to true. The default is
# false.
deletion_protection = false

# List of log types to enable for exporting to CloudWatch logs. If omitted, no
# logs will be exported. Valid values (depending on engine): alert, audit,
# error, general, listener, slowquery, trace, postgresql (PostgreSQL) and
# upgrade (PostgreSQL).
enabled_cloudwatch_logs_exports = []

# Specifies whether IAM database authentication is enabled. This option is
# only available for MySQL and PostgreSQL engines.
iam_database_authentication_enabled = null

# The amount of provisioned IOPS for the primary instance. Setting this
# implies a storage_type of 'io1','io2, or 'gp3'. Set to 0 to disable.
iops = 0

# The ARN of a KMS key that should be used to encrypt data on disk. Only used
# if var.storage_encrypted is true. If you leave this blank, the default RDS
# KMS key for the account will be used.
kms_key_arn = null

# The weekly day and time range during which system maintenance can occur
# (e.g. wed:04:00-wed:04:30). Time zone is UTC. Performance may be degraded or
# there may even be a downtime during maintenance windows.
maintenance_window = null

# When configured, the upper limit to which Amazon RDS can automatically scale
# the storage of the DB instance. Configuring this will automatically ignore
# differences to allocated_storage. Must be greater than or equal to
# allocated_storage or 0 to disable Storage Autoscaling.
max_allocated_storage = 0

# The interval, in seconds, between points when Enhanced Monitoring metrics
# are collected for the DB instance. To disable collecting Enhanced Monitoring
# metrics, specify 0. Valid Values: 0, 1, 5, 10, 15, 30, 60. Enhanced
# Monitoring metrics are useful when you want to see how different processes
# or threads on a DB instance use the CPU.
monitoring_interval = 0

# The ARN for the IAM role that permits RDS to send enhanced monitoring
# metrics to CloudWatch Logs. If monitoring_interval is greater than 0, but
# monitoring_role_arn is let as an empty string, a default IAM role that
# allows enhanced monitoring will be created.
monitoring_role_arn = null

# Specifies if a standby instance should be deployed in another availability
# zone. If the primary fails, this instance will automatically take over.
multi_az = false

# (Optional) The network type of the DB instance. Valid values: IPV4, DUAL. By
# default, it's set to IPV4.
network_type = null

# The number of read replicas to create. RDS will asynchronously replicate all
# data from the master to these replicas, which you can use to horizontally
# scale reads traffic.
num_read_replicas = 0

# Name of a DB parameter group to associate.
parameter_group_name = null

# Specifies whether Performance Insights are enabled. Performance Insights can
# be enabled for specific versions of database engines. See
# https://aws.amazon.com/rds/performance-insights/ for more details.
performance_insights_enabled = false

# The ARN for the KMS key to encrypt Performance Insights data. When
# specifying performance_insights_kms_key_id, performance_insights_enabled
# needs to be set to true. Once KMS key is set, it can never be changed. When
# set to `null` default aws/rds KMS for given region is used.
performance_insights_kms_key_id = null

# The amount of time in days to retain Performance Insights data. Either 7 (7
# days) or 731 (2 years). When specifying
# performance_insights_retention_period, performance_insights_enabled needs to
# be set to true. Defaults to `7`.
performance_insights_retention_period = null

# WARNING: - In nearly all cases a database should NOT be publicly accessible.
# Only set this to true if you want the database open to the internet.
publicly_accessible = false

# Identifiers of the replica you want to create. Use this variable if you want
# to set custom identifier for your read replicas.
replica_identifiers = null

# Determines whether a final DB snapshot is created before the DB instance is
# deleted. Be very careful setting this to true; if you do, and you delete
# this DB instance, you will not have any backups of the data!
skip_final_snapshot = false

# Specifies whether the DB instance is encrypted.
storage_encrypted = true

# The type of storage to use for the primary instance. Must be one of
# 'standard' (magnetic), 'gp2' (general purpose SSD), 'gp3' (general purpose
# SSD), io1' (provisioned IOPS SSD), or 'io2' (2nd gen provisioned IOPS SSD).
storage_type = "gp2"

# A list of subnet ids where the database should be deployed. In the standard
# Gruntwork VPC setup, these should be the private persistence subnet ids.
# This is ignored if create_subnet_group=false.
subnet_ids = null

# Timeout for DB updating
updating_timeout = "80m"

}


Reference

Required

instance_typestringrequired

The instance type to use for the db (e.g. db.t2.micro)

namestringrequired

The name used to namespace all resources created by these templates, including the DB instance (e.g. drupaldb). Must be unique for this region. May contain only lowercase alphanumeric characters, hyphens, underscores, periods, and spaces.

portnumberrequired

The port the DB will listen on (e.g. 3306)

primary_instance_idstringrequired

An ID of the primary DB instance to create read replicas from

vpc_idstringrequired

The id of the VPC in which this DB should be deployed.

Optional

additional_security_group_idslist(string)optional

List of IDs of AWS Security Groups to attach to the read replica RDS instance.

[]

A list of CIDR-formatted IP address ranges that can connect to read replica instances. If not set read replica instances will use the same security group as master instance.

[]

A list of Security Groups that can connect to read replica instances. If not set read replica instances will use the same security group as master instance.

[]

Indicates whether major version upgrades (e.g. 9.4.x to 9.5.x) will ever be permitted. Note that these updates must always be manually performed and will never automatically applied.

true
allowed_replica_zoneslist(string)optional

The availability zones within which it should be possible to spin up replicas

[]
apply_immediatelybooloptional

Specifies whether any cluster modifications are applied immediately, or during the next maintenance window. Note that cluster modifications may cause degraded performance or downtime.

false

Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window. If set to true, you should set engine_version to MAJOR.MINOR and omit the .PATCH at the end (e.g., use 5.7 and not 5.7.11); otherwise, you'll get Terraform state drift. See https://www.terraform.io/docs/providers/aws/r/db_instance.html#engine_version for more details.

true

The description of the aws_db_subnet_group that is created. Defaults to 'Subnet group for the name DB' if not specified.

null

The name of the aws_db_subnet_group that is created, or an existing one to use if create_subnet_group is false. Defaults to name if not specified.

null

How many days to keep backup snapshots around before cleaning them up. Must be 1 or greater to support read replicas. 0 means disable automated backups.

21
backup_windowstringoptional

The daily time range during which automated backups are created (e.g. 04:00-09:00). Time zone is UTC. Performance may be degraded while a backup runs.

null
ca_cert_identifierstringoptional

The Certificate Authority (CA) certificates bundle to use on the RDS instance.

null

Copy all the RDS instance tags to snapshots. Default is false.

false

When working with read replicas, only configure db subnet group if the source database specifies an instance in another AWS Region. If true, it will create a new subnet group.

false
creating_timeoutstringoptional

Timeout for DB creating

"40m"
custom_tagsmap(string)optional

A map of custom tags to apply to the RDS Instance and the Security Group created for it. The key is the tag name and the value is the tag value.

{}

Specifies whether to remove automated backups immediately after the DB instance is deleted

null
deleting_timeoutstringoptional

Timeout for DB deleting

"60m"

The database can't be deleted when this value is set to true. The default is false.

false

List of log types to enable for exporting to CloudWatch logs. If omitted, no logs will be exported. Valid values (depending on engine): alert, audit, error, general, listener, slowquery, trace, postgresql (PostgreSQL) and upgrade (PostgreSQL).

[]

Specifies whether IAM database authentication is enabled. This option is only available for MySQL and PostgreSQL engines.

null
iopsnumberoptional

The amount of provisioned IOPS for the primary instance. Setting this implies a storage_type of 'io1','io2, or 'gp3'. Set to 0 to disable.

0
kms_key_arnstringoptional

The ARN of a KMS key that should be used to encrypt data on disk. Only used if storage_encrypted is true. If you leave this blank, the default RDS KMS key for the account will be used.

null
maintenance_windowstringoptional

The weekly day and time range during which system maintenance can occur (e.g. wed:04:00-wed:04:30). Time zone is UTC. Performance may be degraded or there may even be a downtime during maintenance windows.

null
max_allocated_storagenumberoptional

When configured, the upper limit to which Amazon RDS can automatically scale the storage of the DB instance. Configuring this will automatically ignore differences to allocated_storage. Must be greater than or equal to allocated_storage or 0 to disable Storage Autoscaling.

0
monitoring_intervalnumberoptional

The interval, in seconds, between points when Enhanced Monitoring metrics are collected for the DB instance. To disable collecting Enhanced Monitoring metrics, specify 0. Valid Values: 0, 1, 5, 10, 15, 30, 60. Enhanced Monitoring metrics are useful when you want to see how different processes or threads on a DB instance use the CPU.

0
monitoring_role_arnstringoptional

The ARN for the IAM role that permits RDS to send enhanced monitoring metrics to CloudWatch Logs. If monitoring_interval is greater than 0, but monitoring_role_arn is let as an empty string, a default IAM role that allows enhanced monitoring will be created.

null
multi_azbooloptional

Specifies if a standby instance should be deployed in another availability zone. If the primary fails, this instance will automatically take over.

false
network_typestringoptional

(Optional) The network type of the DB instance. Valid values: IPV4, DUAL. By default, it's set to IPV4.

null
num_read_replicasnumberoptional

The number of read replicas to create. RDS will asynchronously replicate all data from the master to these replicas, which you can use to horizontally scale reads traffic.

0
parameter_group_namestringoptional

Name of a DB parameter group to associate.

null

Specifies whether Performance Insights are enabled. Performance Insights can be enabled for specific versions of database engines. See https://aws.amazon.com/rds/performance-insights/ for more details.

false

The ARN for the KMS key to encrypt Performance Insights data. When specifying performance_insights_kms_key_id, performance_insights_enabled needs to be set to true. Once KMS key is set, it can never be changed. When set to null default aws/rds KMS for given region is used.

null

The amount of time in days to retain Performance Insights data. Either 7 (7 days) or 731 (2 years). When specifying performance_insights_retention_period, performance_insights_enabled needs to be set to true. Defaults to 7.

null

WARNING: - In nearly all cases a database should NOT be publicly accessible. Only set this to true if you want the database open to the internet.

false
replica_identifierslist(string)optional

Identifiers of the replica you want to create. Use this variable if you want to set custom identifier for your read replicas.

null

Determines whether a final DB snapshot is created before the DB instance is deleted. Be very careful setting this to true; if you do, and you delete this DB instance, you will not have any backups of the data!

false
storage_encryptedbooloptional

Specifies whether the DB instance is encrypted.

true
storage_typestringoptional

The type of storage to use for the primary instance. Must be one of 'standard' (magnetic), 'gp2' (general purpose SSD), 'gp3' (general purpose SSD), io1' (provisioned IOPS SSD), or 'io2' (2nd gen provisioned IOPS SSD).

"gp2"
subnet_idslist(string)optional

A list of subnet ids where the database should be deployed. In the standard Gruntwork VPC setup, these should be the private persistence subnet ids. This is ignored if create_subnet_group=false.

null
updating_timeoutstringoptional

Timeout for DB updating

"80m"