Skip to main content
Service Catalog Version 0.96.9Last updated in version 0.96.6

Amazon Relational Database Service

View SourceRelease Notes

Overview​

This service contains code to deploy an Amazon Relational Database Service (RDS) cluster that can run MySQL, PostgreSQL, SQL Server, Oracle, or MariaDB. The cluster is managed by AWS and automatically handles standby failover, read replicas, backups, patching, and encryption. For Aurora, use the Aurora service.

RDS architectureRDS architecture

Features​

  • Deploy a fully-managed native relational database
  • Supports, MySQL, PostgreSQL, SQL Server, Oracle, and MariaDB
  • Automatic failover to a standby in another availability zone
  • Read replicas
  • Automatic nightly snapshots
  • Automatic cross account snapshots
  • Automatic scaling of storage
  • CloudWatch Alarms for alerting when CPU, memory, and disk metrics exceed certain thresholds
  • CloudWatch dashboard widgets for RDS statistics
  • Integrate with Kubernetes Service Discovery

Learn​

note

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

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/for-learning-and-testing folder: The examples/for-learning-and-testing folder contains standalone sample code optimized for learning, experimenting, and testing (but not direct production usage).

Production deployment​

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

Reference​

Required​

allocated_storagenumberrequired

The amount of storage space the DB should use, in GB.

engine_versionstringrequired

The version of engine to use (e.g. 8.0.17 for mysql).

namestringrequired

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

subnet_idslist(string)required

The list of IDs of the subnets in which to deploy RDS. The list must only contain subnets in vpc_id.

vpc_idstringrequired

The ID of the VPC in which to deploy RDS.

Optional​

alarms_sns_topic_arnslist(string)optional

The ARNs of SNS topics where CloudWatch alarms (e.g., for CPU, memory, and disk space usage) should send notifications. Also used for the alarms if the share snapshot backup job fails.

[]

The list of network CIDR blocks to allow network access to RDS from. One of allow_connections_from_cidr_blocks or allow_connections_from_security_groups must be specified for the database to be reachable.

[]

The list of IDs or Security Groups to allow network access to RDS from. All security groups must either be in the VPC specified by vpc_id, or a peered VPC with the VPC specified by vpc_id. One of allow_connections_from_cidr_blocks or allow_connections_from_security_groups must be specified for the database to be reachable.

[]

If true, both the CMK's Key Policy and IAM Policies (permissions) can be used to grant permissions on the CMK. If false, only the CMK's Key Policy can be used to grant permissions on the CMK. False is more secure (and generally preferred), but true is more flexible and convenient.

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.

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://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/db_instance.html#engine_version for more details.

true

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

null

How often, in seconds, the backup job is expected to run. This is the same as schedule_expression, but unfortunately, Terraform offers no way to convert rate expressions to seconds. We add a CloudWatch alarm that triggers if the metric in create_snapshot_cloudwatch_metric_namespace isn't updated within this time period, as that indicates the backup failed to run.

3600

Sets how the backup job alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"

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

30
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"
cmk_administrator_iam_arnslist(string)optional

A list of IAM ARNs for users who should be given administrator access to this CMK (e.g. arn:aws:iam::<aws-account-id>:user/<iam-user-arn>). If this list is empty, and kms_key_arn is null, the ARN of the current user will be used.

[]
cmk_external_user_iam_arnslist(string)optional

A list of IAM ARNs for users from external AWS accounts who should be given permissions to use this CMK (e.g. arn:aws:iam::<aws-account-id>:root).

[]
cmk_user_iam_arnslist(object(…))optional

A list of IAM ARNs for users who should be given permissions to use this CMK (e.g. arn:aws:iam::<aws-account-id>:user/<iam-user-arn>). If this list is empty, and kms_key_arn is null, the ARN of the current user will be used.

list(object({
    name = list(string)
    conditions = list(object({
      test     = string
      variable = string
      values   = list(string)
    }))
  }))
[]

If set to true, create a KMS CMK and use it to encrypt data on disk in the database. The permissions for this CMK will be assigned by the following variables: cmk_administrator_iam_arns, cmk_user_iam_arns, cmk_external_user_iam_arns, allow_manage_key_permissions.

false

Set to true if you want a DNS record automatically created and pointed at the RDS endpoints.

false

The namespace to use for the CloudWatch metric we report every time a new RDS snapshot is created. We add a CloudWatch alarm on this metric to notify us if the backup job fails to run for any reason. Defaults to the cluster name.

null
custom_parameter_groupobject(…)optional

Configure a custom parameter group for the RDS DB. This will create a new parameter group with the given parameters. When null, the database will be launched with the default parameter group.

object({
    # Name of the parameter group to create
    name = string

    # The family of the DB parameter group.
    family = string

    # The parameters to configure on the created parameter group.
    parameters = list(object({
      # Parameter name to configure.
      name = string

      # Vaue to set the parameter.
      value = string

      # When to apply the parameter. "immediate" or "pending-reboot".
      apply_method = string
    }))
  })
null
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.

{}

Parameters for the cpu usage widget to output for use in a CloudWatch dashboard.

object({
    # The period in seconds for metrics to sample across.
    period = number

    # The width and height of the widget in grid units in a 24 column grid. E.g., a value of 12 will take up half the
    # space.
    width  = number
    height = number
  })
{
  height = 6,
  period = 60,
  width = 8
}

Parameters for the database connections widget to output for use in a CloudWatch dashboard.

object({
    # The period in seconds for metrics to sample across.
    period = number

    # The width and height of the widget in grid units in a 24 column grid. E.g., a value of 12 will take up half the
    # space.
    width  = number
    height = number
  })
{
  height = 6,
  period = 60,
  width = 8
}

Parameters for the available disk space widget to output for use in a CloudWatch dashboard.

object({
    # The period in seconds for metrics to sample across.
    period = number

    # The width and height of the widget in grid units in a 24 column grid. E.g., a value of 12 will take up half the
    # space.
    width  = number
    height = number
  })
{
  height = 6,
  period = 60,
  width = 8
}

Parameters for the available memory widget to output for use in a CloudWatch dashboard.

object({
    # The period in seconds for metrics to sample across.
    period = number

    # The width and height of the widget in grid units in a 24 column grid. E.g., a value of 12 will take up half the
    # space.
    width  = number
    height = number
  })
{
  height = 6,
  period = 60,
  width = 8
}

Parameters for the read latency widget to output for use in a CloudWatch dashboard.

object({
    # The period in seconds for metrics to sample across.
    period = number

    # The width and height of the widget in grid units in a 24 column grid. E.g., a value of 12 will take up half the
    # space.
    width  = number
    height = number
  })
{
  height = 6,
  period = 60,
  width = 8
}

Parameters for the read latency widget to output for use in a CloudWatch dashboard.

object({
    # The period in seconds for metrics to sample across.
    period = number

    # The width and height of the widget in grid units in a 24 column grid. E.g., a value of 12 will take up half the
    # space.
    width  = number
    height = number
  })
{
  height = 6,
  period = 60,
  width = 8
}

The friendly name or ARN of an AWS Secrets Manager secret that contains database configuration information in the format outlined by this document: https://docs.aws.amazon.com/secretsmanager/latest/userguide/best-practices.html. The engine, username, password, dbname, and port fields must be included in the JSON. Note that even with this precaution, this information will be stored in plaintext in the Terraform state file! See the following blog post for more details: https://blog.gruntwork.io/a-comprehensive-guide-to-managing-secrets-in-your-terraform-code-1d586955ace1. If you do not wish to use Secrets Manager, leave this as null, and use the master_username, master_password, db_name, engine, and port variables.

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 an empty database on the RDS instance. This can also be provided via AWS Secrets Manager. See the description of db_config_secrets_manager_id.

null

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

true

Set to true to enable several basic CloudWatch alarms around CPU usage, memory usage, and disk space usage. If set to true, make sure to specify SNS topics to send notifications to using alarms_sns_topic_arn.

true

When true, enable CloudWatch metrics for the manual snapshots created for the purpose of sharing with another account.

true

Enable deletion protection on the RDS instance. If this is enabled, the database cannot be deleted prior to disabling

false
enable_perf_alarmsbooloptional

Set to true to enable alarms related to performance, such as read and write latency alarms. Set to false to disable those alarms if you aren't sure what would be reasonable perf numbers for your RDS set up or if those numbers are too unpredictable.

true

When true, enable CloudWatch alarms for the manual snapshots created for the purpose of sharing with another account. Only used if share_snapshot_with_another_account is true.

true

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

[]
enginestringoptional

The DB engine to use (e.g. mysql). This can also be provided via AWS Secrets Manager. See the description of db_config_secrets_manager_id.

null

The period, in seconds, over which to measure the CPU utilization percentage.

60

Trigger an alarm if the DB instance has a CPU utilization percentage above this threshold.

90

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"

The period, in seconds, over which to measure the read latency.

60

Trigger an alarm if the DB instance read latency (average amount of time taken per disk I/O operation), in seconds, is above this threshold.

5

The period, in seconds, over which to measure the write latency.

60

Trigger an alarm if the DB instance write latency (average amount of time taken per disk I/O operation), in seconds, is above this threshold.

5
hosted_zone_idstringoptional

The ID of the Route 53 hosted zone into which the Route 53 DNS record should be written

null

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

false
instance_typestringoptional

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

"db.t3.micro"
kms_key_arnstringoptional

The Amazon Resource Name (ARN) of an existing KMS customer master key (CMK) that will be used to encrypt/decrypt backup files. If you leave this blank, the default RDS KMS key for the account will be used. If you set create_custom_kms_key to true, this value will be ignored and a custom key will be created and used instead.

null
license_modelstringoptional

The license model to use for this DB. Check the docs for your RDS DB for available license models. Set to an empty string to use the default.

null

The period, in seconds, over which to measure the available free disk space.

60

Trigger an alarm if the amount of disk space, in Bytes, on the DB instance drops below this threshold.

1000000000

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"

The period, in seconds, over which to measure the available free memory.

60

Trigger an alarm if the amount of free memory, in Bytes, on the DB instance drops below this threshold.

100000000

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"
master_passwordstringoptional

The value to use for the master password of the database. This can also be provided via AWS Secrets Manager. See the description of db_config_secrets_manager_id.

null
master_usernamestringoptional

The value to use for the master username of the database. This can also be provided via AWS Secrets Manager. See the description of db_config_secrets_manager_id.

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

false
num_read_replicasnumberoptional

The number of read replicas to deploy

0
option_group_namestringoptional

Name of a DB option 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
portnumberoptional

The port the DB will listen on (e.g. 3306). Alternatively, this can be provided via AWS Secrets Manager. See the description of db_config_secrets_manager_id.

null
primary_domain_namestringoptional

The domain name to create a route 53 record for the primary endpoint of the RDS database.

null

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

false

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
replica_domain_namestringoptional

The domain name to create a route 53 record for the read replicas of the RDS database.

null

The maximum number of snapshots to keep around for the purpose of cross account sharing. Once this number is exceeded, a lambda function will delete the oldest snapshots. Only used if share_snapshot_with_another_account is true.

30

An expression that defines how often to run the lambda function to take snapshots for the purpose of cross account sharing. For example, cron(0 20 * ? ) or rate(5 minutes). Required if share_snapshot_with_another_account is true

null

The ID of the AWS Account that the snapshot should be shared with. Required if share_snapshot_with_another_account is true.

null

If set to true, take periodic snapshots of the RDS DB that should be shared with another account.

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! You almost never want to set this to true, unless you are doing automated or manual testing.

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

Trigger an alarm if the number of connections to the DB instance goes above this threshold.

null

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"