Skip to main content
View SourceRelease Notes

RDS Module

This module creates an Amazon Relational Database Service (RDS) cluster that can run MySQL, Postgres, MariaDB, Oracle, or SQL Server. The cluster is managed by AWS and automatically handles standby failover, read replicas, backups, patching, and encryption.

RDS architectureRDS architecture

Features​

  • Deploy a fully-managed relational database

  • Supports MySQL, PostgreSQL, MariaDB, Oracle, and SQL Server

  • Automatic failover to a standby in another availability zone

  • Read replicas

  • Automatic nightly snapshots

Learn​

Note

This repo is a part of the Gruntwork Infrastructure as Code Library, a collection of reusable, battle-tested, production ready infrastructure code. If you’ve never used the Infrastructure as Code Library before, make sure to read How to use the Gruntwork Infrastructure as Code Library!

Core concepts​

Deploy​

Non-production deployment (quick start for learning)​

If you just want to try this repo out for experimenting and learning, check out the following resources:

  • examples folder: The examples folder contains sample code optimized for learning, experimenting, and testing (but not production usage).

Production deployment​

If you want to deploy this repo in production, check out the following resources:

Manage​

Day-to-day operations​

Major changes​

Reference​

Required​

enginestringrequired

The DB engine to use (e.g. mysql). Required unless replicate_source_db is set.

engine_versionstringrequired

The version of engine to use (e.g. 5.7.11 for mysql). If auto_minor_version_upgrade is set to true, set the version number to MAJOR.MINOR and omit the PATCH (e.g., set it to 5.7 and not 5.7.11) to avoid state drift. See https://www.terraform.io/docs/providers/aws/r/db_instance.html#engine_version for more details.

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)

subnet_idslist(string)required

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.

vpc_idstringrequired

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

Optional​

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

[]

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

[]
allocated_storagenumberoptional

The amount of storage space the DB should use, in GB. If max_allocated_storage is configured, this argument represents the initial storage allocation and differences from the configuration will be ignored automatically when Storage Autoscaling occurs. Required unless replicate_source_db is set.

null

A list of CIDR-formatted IP address ranges that can connect to this DB. Should typically be the CIDR blocks of the private app subnet in this VPC plus the private subnet in the mgmt VPC.

[]

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 this DB.

[]

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_security_group that is created. Defaults to 'Security group for the name DB' if not specified.

null

The name of the aws_db_security_group that is created. Defaults to name if not specified.

null

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.

"06:00-07:00"
ca_cert_identifierstringoptional

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

null
character_set_namestringoptional

The character set name to use for DB encoding in Oracle and Microsoft SQL instances (collation). This must be null for all other engine types. Note that this is only relevant at create time - it can not be changed after creation.

null

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

false

If false, the DB will bind to aws_db_subnet_group_name and the CIDR will be ignored (allow_connections_from_cidr_blocks)

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

{}
db_namestringoptional

The name for your database of up to 8 alpha-numeric characters. If you do not provide a name, Amazon RDS will not create a database in the DB cluster you are creating.

null
default_license_modelsmap(string)optional

A map of the default license to use for each supported RDS engine.

{
  mariadb = "general-public-license",
  mysql = "general-public-license",
  oracle-ee = "bring-your-own-license",
  oracle-se = "bring-your-own-license",
  oracle-se1 = "bring-your-own-license",
  oracle-se2 = "bring-your-own-license",
  postgres = "postgresql-license",
  sqlserver-ee = "license-included",
  sqlserver-ex = "license-included",
  sqlserver-se = "license-included",
  sqlserver-web = "license-included"
}

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

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

[]
final_snapshot_namestringoptional

The name of the final_snapshot_identifier. Defaults to name-final-snapshot if not specified.

null

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

null

Creates an instance that disables terraform from updating the master_password. Useful when managing secrets outside of terraform (ex. using AWS Secrets Manager Rotations). Note changing this value will switch the db instance resource. To avoid deleting your old database and creating a new one, you will need to run terraform state mv when changing this variable

false
iopsnumberoptional

The amount of provisioned IOPS for the primary instance. Setting this implies a storage_type of 'io1' or 'io2'. 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
license_modelstringoptional

The license model to use for this DB. Check the docs for your RDS DB for available license models. Valid values: general-public-license, postgresql-license, license-included, bring-your-own-license.

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.

"sun:07:00-sun:08:00"
master_passwordstringoptional

The password for the master user. If snapshot_identifier is non-empty, this value is ignored. Required unless replicate_source_db is set.

null
master_usernamestringoptional

The username for the master user. Required unless replicate_source_db is set.

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

Optionally add a path to the IAM monitoring role. If left blank, it will default to just /.

"/"
monitoring_role_namestringoptional

The name of the enhanced_monitoring_role that is created. Defaults to name-monitoring-role if not specified.

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.

true

The national character set is used in the NCHAR, NVARCHAR2, and NCLOB data types for Oracle instances. This must be null for all other engine types. Note that this is only relevant at create time - it can not be changed after creation.

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
option_group_namestringoptional

Name of a DB option group to associate.

null
parameter_group_namestringoptional

Name of a DB parameter group to associate.

null

Name of a DB parameter group to associate with read replica instances. Defaults to parameter_group_name if not set.

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

The ARN of the policy that is used to set the permissions boundary for the role of enhanced monitoring role. This policy should be created outside of this module.

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
read_replica_iopsnumberoptional

The amount of provisioned IOPS for read replicas. If null, the replica will use the same value as the primary, which is set in iops.

null

The type of storage to use for read replicas. If null, the replica will use the same value as the primary, which is set in storage_type.

null

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

0
replicate_source_dbstringoptional

Specifies that this resource is a Replicate database, and to use this value as the source database. This correlates to the identifier of another Amazon RDS Database to replicate (if replicating within a single region) or ARN of the Amazon RDS Database to replicate (if replicating cross-region). Note that if you are creating a cross-region replica of an encrypted database you will also need to specify a kms_key_arn.

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
snapshot_identifierstringoptional

If non-null, the RDS Instance will be restored from the given Snapshot ID. This is the Snapshot ID you'd find in the RDS console, e.g: rds:production-2015-06-26-06-05.

null
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), 'io1' (provisioned IOPS SSD), or 'io2' (2nd gen provisioned IOPS SSD).

"gp2"
updating_timeoutstringoptional

Timeout for DB updating

"80m"