Data Storage Modules 0.29.0

RDS Read Replicas Module

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.

Sample Usage

Terraform
Terragrunt

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.29.0"

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

  # 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

  # 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"

}

terragrunt.hcl

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

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

inputs = {

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

  # 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

  # 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

Inputs
Outputs

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.

Default:[]

allow_connections_from_cidr_blockslist(string)optional

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.

Default:[]

allow_connections_from_security_groupslist(string)optional

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.

Default:[]

allow_major_version_upgradebooloptional

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.

Default:true

allowed_replica_zoneslist(string)optional

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

Default:[]

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.

Default:false

auto_minor_version_upgradebooloptional

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.

Default:true

aws_db_subnet_group_descriptionstringoptional

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

Default:null

aws_db_subnet_group_namestringoptional

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.

Default:null

backup_retention_periodnumberoptional

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.

Default: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.

Default:null

ca_cert_identifierstringoptional

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

Default:null

copy_tags_to_snapshotbooloptional

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

Default:false

create_subnet_groupbooloptional

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.

Default:false

creating_timeoutstringoptional

Timeout for DB creating

Default:"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.

Default:{}

delete_automated_backupsbooloptional

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

Default:null

deleting_timeoutstringoptional

Timeout for DB deleting

Default:"60m"

deletion_protectionbooloptional

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

Default:false

enabled_cloudwatch_logs_exportslist(string)optional

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).

Default:[]

iam_database_authentication_enabledbooloptional

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

Default: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.

Default: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.

Default: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.

Default: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.

Default: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.

Default: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.

Default: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.

Default:false

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.

Default:0

parameter_group_namestringoptional

Name of a DB parameter group to associate.

Default:null

performance_insights_enabledbooloptional

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.

Default:false

performance_insights_kms_key_idstringoptional

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.

Default:null

performance_insights_retention_periodnumberoptional

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.

Default:null

publicly_accessiblebooloptional

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.

Default:false

skip_final_snapshotbooloptional

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!

Default:false

storage_encryptedbooloptional

Specifies whether the DB instance is encrypted.

Default: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).

Default:"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.

Default:null

updating_timeoutstringoptional

Timeout for DB updating

Default:"80m"

read_replica_addresses

read_replica_arns

read_replica_endpoints

read_replica_ids

read_replica_names

read_replica_port