Aurora Module

This module creates an Amazon Relational Database Service (RDS) cluster that can run Amazon Aurora, Amazon’s cloud-native relational database. The cluster is managed by AWS and automatically handles standby failover, read replicas, backups, patching, and encryption.

RDS architecture

Features

Deploy a fully-managed, cloud-native relational database
MySQL and PostgreSQL compatibility
Automatic failover to a standby in another availability zone
Read replicas
Automatic nightly snapshots
Automatic scaling of storage

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

What is Amazon RDS?
Common gotchas with RDS
RDS documentation: Amazon’s docs for RDS that cover core concepts such as the types of databases supported, security, backup & restore, and monitoring.
Designing Data Intensive Applications: the best book we’ve found for understanding data systems, including relational databases, NoSQL, replication, sharding, consistency, and so on.

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:

rds module in the Acme example Reference Architecture: Production-ready sample code from the Acme Reference Architecture examples.

Manage

Day-to-day operations

Major changes

Reference

Inputs
Outputs

Required

instance_countnumberrequired

How many instances to launch. RDS will automatically pick a leader and configure the others as replicas.

instance_typestringrequired

The instance type from an Amazon Aurora supported instance class based on a selected engine_mode. Amazon Aurora supports 2 types of instance classes: Memory Optimized (db.r) and Burstable Performance (db.t). Aurora Global Clusters require instance class of either db.r5 (latest) or db.r4 (current). See AWS documentation on Amazon Aurora supported instance class types: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Concepts.DBInstanceClass.html#Concepts.DBInstanceClass.Types

namestringrequired

The name used to namespace all resources created by these templates, including the cluster and cluster instances (e.g. drupaldb). Must be unique in this region. Must be a lowercase string.

subnet_idslist(string)required

A list of subnet ids where the database instances 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

allow_connections_from_cidr_blockslist(string)optional

A list of CIDR-formatted IP address ranges that can connect to this DB. In the standard Gruntwork VPC setup, these should be the CIDR blocks of the private app subnets, plus the private subnets in the mgmt VPC.

Default:[]

allow_connections_from_security_groupslist(string)optional

Specifies a list of Security Groups to allow connections from.

Default:[]

allow_major_version_upgradebooloptional

Enable to allow major engine version upgrades when changing engine versions.

Default:false

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

Configure the auto minor version upgrade behavior. This is applied to the cluster instances and indicates if the automatic minor version upgrade of the engine is allowed. Default value is true.

Default:true

aws_db_security_group_descriptionstringoptional

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

Default:null

aws_db_security_group_namestringoptional

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

Default:null

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

backtrack_windownumberoptional

Window to allow Aurora Backtrack a special, in-place, destructive rollback for the entire cluster. Must be specified in seconds. 0=disabled, to maximum of 259200

Default:null

backup_retention_periodnumberoptional

How many days to keep backup snapshots around before cleaning them up

Default:21

ca_cert_identifierstringoptional

The Certificate Authority (CA) certificate bundle to use on the Aurora DB instances.

Default:null

cluster_iam_roleslist(string)optional

List of IAM role ARNs to attach to the cluster. Be sure these roles exists. They will not be created here. Serverless aurora does not support attaching IAM roles.

Default:[]

cluster_instances_maintenance_duration_minutesnumberoptional

Amount of time, in minutes, to allow for DB maintenance windows for the cluster instances

Default:120

cluster_instances_maintenance_window_start_timestampstringoptional

The cluster instances maintenance window start in RFC 3339 timestamp (date and time) format. The default starts at 'wed:00:00-wed:02:00'. Can have any date from any year, only the day of the week will be used. Performance may be degraded or there may even be a downtime during maintenance windows.

Default:"2017-11-22T00:00:00Z"

cluster_instances_minutes_between_maintenance_windowsnumberoptional

Amount of time, in minutes, between maintenance windows of the cluster instances

Default:180

copy_tags_to_snapshotbooloptional

Copy all the Aurora cluster tags to snapshots. Default is false.

Default:false

create_subnet_groupbooloptional

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

Default:true

creating_timeoutstringoptional

Timeout for DB creating

Default:"120m"

custom_tagsmap(string)optional

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

Default:{}

db_cluster_parameter_group_namestringoptional

A cluster parameter group to associate with the cluster. Parameters in a DB cluster parameter group apply to every DB instance in a DB cluster.

Default:null

db_instance_parameter_group_namestringoptional

An instance parameter group to associate with the cluster instances. Parameters in a DB parameter group apply to a single DB instance in an Aurora DB cluster.

Default:null

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.

Default:null

deleting_timeoutstringoptional

Timeout for DB deleting

Default:"120m"

deletion_protectionbooloptional

If the DB instance should have deletion protection enabled. The database can't be deleted when this value is set to true.

Default:false

dependencieslist(string)optional

Create a dependency between the resources in this module to the interpolated values in this list (and thus the source resources). In other words, the resources in this module will now depend on the resources backing the values in this list such that those resources need to be created before the resources in this module, and the resources in this module need to be destroyed before the resources in the list.

Default:[]

enable_http_endpointbooloptional

If true, enables the HTTP endpoint used for Data API. Only valid when engine_mode is set to serverless.

Default:null

enabled_cloudwatch_logs_exportslist(string)optional

If non-empty, the Aurora cluster will export the specified logs to Cloudwatch. Must be zero or more of: audit, error, general and slowquery

Default:[]

enginestringoptional

The name of the database engine to be used for this DB cluster. Valid Values: aurora (for MySQL 5.6-compatible Aurora), aurora-mysql (for MySQL 5.7-compatible Aurora), and aurora-postgresql

Default:"aurora-mysql"

engine_modestringoptional

The DB engine mode of the DB cluster: either provisioned, serverless, parallelquery, multimaster or global which only applies for global database clusters created with Aurora MySQL version 5.6.10a. For higher Aurora MySQL versions, the clusters in a global database use provisioned engine mode.. Limitations and requirements apply to some DB engine modes. See AWS documentation: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/CHAP_AuroraSettingUp.html

Default:"provisioned"

engine_versionstringoptional

The Amazon Aurora DB engine version for the selected engine and engine_mode. Note: Starting with Aurora MySQL 2.03.2, Aurora engine versions have the following syntax <mysql-major-version>.mysql_aurora.<aurora-mysql-version>. e.g. 5.7.mysql_aurora.2.08.1.

Default:null

final_snapshot_namestringoptional

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

Default:null

global_cluster_identifierstringoptional

Global cluster identifier when creating the global secondary cluster.

Default:null

iam_database_authentication_enabledbooloptional

Specifies whether mappings of AWS Identity and Access Management (IAM) accounts to database accounts is enabled. Disabled by default.

Default:false

ignore_password_changesbooloptional

Implements a cluster 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 cluster resource. To avoid deleting your old database and creating a new one, you will need to run terraform state mv when changing this variable

Default:false

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 null, the default RDS KMS key for the account will be used.

Default:null

master_passwordstringoptional

The password for the master user. Required unless this is a secondary database in a global Aurora cluster. If snapshot_identifier is non-empty, this value is ignored.

Default:null

master_usernamestringoptional

The username for the master user. Required unless this is a secondary database in a global Aurora cluster.

Default:null

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. Allowed values: 0, 1, 5, 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. Be sure this role exists. It will not be created here. You must specify a MonitoringInterval value other than 0 when you specify a MonitoringRoleARN value that is not empty string.

Default:null

performance_insights_enabledbooloptional

Specifies whether Performance Insights is enabled or not. On Aurora MySQL, Performance Insights is not supported on db.t2 or db.t3 DB instance classes.

Default:false

performance_insights_kms_key_idstringoptional

The ARN for the KMS key to encrypt Performance Insights data.

Default:null

portnumberoptional

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

Default:3306

preferred_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:"06:00-07:00"

preferred_maintenance_windowstringoptional

The weekly day and time range during which cluster 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. For cluster instance maintenance, see 'cluster_instances_maintenance_window_start_timestamp'

Default:"sun:07:00-sun:08:00"

publicly_accessiblebooloptional

If you wish to make your database accessible from the public Internet, set this flag to true (WARNING: NOT RECOMMENDED FOR PRODUCTION USAGE!!). The default is false, which means the database is only accessible from within the VPC, which is much more secure.

Default:false

replication_source_identifierstringoptional

ARN of a source DB cluster or DB instance if this DB cluster is to be created as a Read Replica.

Default:null

restore_source_cluster_identifierstringoptional

If non-empty, the Aurora cluster will be restored from the given source cluster using the latest restorable time. Can only be used if snapshot_identifier is null. For more information see https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_PIT.html

Default:null

restore_to_timestringoptional

Only used if 'restore_source_cluster_identifier' is non-empty. Date and time in UTC format to restore the database cluster to (e.g, 2009-09-07T23:45:00Z). When null, the latest restorable time will be used.

Default:null

restore_typestringoptional

Only used if 'restore_source_cluster_identifier' is non-empty. Type of restore to be performed. Valid options are 'full-copy' and 'copy-on-write'.

Default:null

scaling_configuration_auto_pausebooloptional

Whether to enable automatic pause. A DB cluster can be paused only when it's idle (it has no connections). If a DB cluster is paused for more than seven days, the DB cluster might be backed up with a snapshot. In this case, the DB cluster is restored when there is a request to connect to it.

Default:true

scaling_configuration_max_capacitynumberoptional

The maximum capacity. The maximum capacity must be greater than or equal to the minimum capacity. Valid capacity values are 2, 4, 8, 16, 32, 64, 128, and 256.

Default:256

scaling_configuration_max_capacity_V2numberoptional

The maximum capacity for an Aurora DB cluster in provisioned DB engine mode. The maximum capacity must be greater than or equal to the minimum capacity. Valid capacity values are in a range of 0.5 up to 128 in steps of 0.5.

Default:0.5

scaling_configuration_min_capacitynumberoptional

The minimum capacity. The minimum capacity must be lesser than or equal to the maximum capacity. Valid capacity values are 2, 4, 8, 16, 32, 64, 128, and 256.

Default:2

scaling_configuration_min_capacity_V2numberoptional

The minimum capacity for an Aurora DB cluster in provisioned DB engine mode. The minimum capacity must be lesser than or equal to the maximum capacity. Valid capacity values are in a range of 0.5 up to 128 in steps of 0.5.

Default:128

scaling_configuration_seconds_until_auto_pausenumberoptional

The time, in seconds, before an Aurora DB cluster in serverless mode is paused. Valid values are 300 through 86400.

Default:300

scaling_configuration_timeout_actionstringoptional

The action to take when the timeout is reached. Valid values: ForceApplyCapacityChange, RollbackCapacityChange. Defaults to RollbackCapacityChange.

Default:"RollbackCapacityChange"

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

snapshot_identifierstringoptional

If non-empty, the Aurora cluster 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.

Default:null

source_regionstringoptional

Source region for global secondary cluster (if creating a global cluster) or the master cluster (if creating a read replica cluster).

Default:null

storage_encryptedbooloptional

Specifies whether the DB cluster uses encryption for data at rest in the underlying storage for the DB, its automated backups, Read Replicas, and snapshots. Uses the default aws/rds key in KMS.

Default:true

updating_timeoutstringoptional

Timeout for DB updating

Default:"120m"

cluster_arn

cluster_endpoint

cluster_id

cluster_instances_maintenance_window

cluster_resource_id

db_name

instance_endpoints

instance_ids