aurora-mysql
This component is responsible for provisioning Aurora MySQL RDS clusters. It seeds relevant database information (hostnames, username, password, etc.) into AWS SSM Parameter Store.
Usage
Stack Level: Regional
Here's an example for how to use this component.
stacks/catalog/aurora-mysql/defaults.yaml
file (base component for all Aurora MySQL clusters with default settings):
components:
terraform:
aurora-mysql/defaults:
metadata:
type: abstract
vars:
enabled: false
name: rds
mysql_deletion_protection: false
mysql_storage_encrypted: true
aurora_mysql_engine: "aurora-mysql"
allowed_cidr_blocks:
# all automation
- 10.128.0.0/22
# all corp
- 10.128.16.0/22
eks_component_names:
- eks/eks
# https://docs.aws.amazon.com/AmazonRDS/latest/AuroraMySQLReleaseNotes/AuroraMySQL.Updates.3020.html
# aws rds describe-db-engine-versions --engine aurora-mysql --query 'DBEngineVersions[].EngineVersion'
aurora_mysql_engine_version: "8.0.mysql_aurora.3.02.0"
# engine and cluster family are notoriously hard to find.
# If you know the engine version (example here is "8.0.mysql_aurora.3.02.0"), use Engine and DBParameterGroupFamily from:
# aws rds describe-db-engine-versions --engine aurora-mysql --query "DBEngineVersions[]" | \
# jq '.[] | select(.EngineVersion == "8.0.mysql_aurora.3.02.0") |
# { Engine: .Engine, EngineVersion: .EngineVersion, DBParameterGroupFamily: .DBParameterGroupFamily }'
#
# Returns:
# {
# "Engine": "aurora-mysql",
# "EngineVersion": "8.0.mysql_aurora.3.02.0",
# "DBParameterGroupFamily": "aurora-mysql8.0"
# }
aurora_mysql_cluster_family: "aurora-mysql8.0"
mysql_name: shared
# 1 writer, 1 reader
mysql_cluster_size: 2
mysql_admin_user: "" # generate random username
mysql_admin_password: "" # generate random password
mysql_db_name: "" # generate random db name
# https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Concepts.DBInstanceClass.html
mysql_instance_type: "db.t3.medium"
mysql_skip_final_snapshot: false
Example configuration for a dev cluster. Import this file into the primary region.
stacks/catalog/aurora-mysql/dev.yaml
file (override the default settings for the cluster in the dev
account):
import:
- catalog/aurora-mysql/defaults
components:
terraform:
aurora-mysql/dev:
metadata:
component: aurora-mysql
inherits:
- aurora-mysql/defaults
vars:
instance_type: db.r5.large
mysql_cluster_size: 1
mysql_name: main
mysql_db_name: main
Example deployment with primary cluster deployed to us-east-1 in a platform-dev
account:
atmos terraform apply aurora-mysql/dev -s platform-use1-dev
Disaster Recovery with Cross-Region Replication
This component is designed to support cross-region replication with continuous replication. If enabled and deployed, a secondary cluster will be deployed in a different region than the primary cluster. This approach is highly aggressive and costly, but in a disaster scenario where the primary cluster fails, the secondary cluster can be promoted to take its place. Follow these steps to handle a Disaster Recovery.
Usage
To deploy a secondary cluster for cross-region replication, add the following catalog entries to an alternative region:
Default settings for a secondary, replica cluster. For this example, this file is saved as
stacks/catalog/aurora-mysql/replica/defaults.yaml
import:
- catalog/aurora-mysql/defaults
components:
terraform:
aurora-mysql/replica/defaults:
metadata:
component: aurora-mysql
inherits:
- aurora-mysql/defaults
vars:
eks_component_names: []
allowed_cidr_blocks:
# all automation in primary region (where Spacelift is deployed)
- 10.128.0.0/22
# all corp in the same region as this cluster
- 10.132.16.0/22
mysql_instance_type: "db.t3.medium"
mysql_name: "replica"
primary_cluster_region: use1
is_read_replica: true
is_promoted_read_replica: false # False by default, added for visibility
Environment specific settings for dev
as an example:
import:
- catalog/aurora-mysql/replica/defaults
components:
terraform:
aurora-mysql/dev:
metadata:
component: aurora-mysql
inherits:
- aurora-mysql/defaults
- aurora-mysql/replica/defaults
vars:
enabled: true
primary_cluster_component: aurora-mysql/dev
Promoting the Read Replica
Promoting an existing RDS Replicate cluster to a fully standalone cluster is not currently supported by Terraform: https://github.com/hashicorp/terraform-provider-aws/issues/6749
Instead, promote the Replicate cluster with the AWS CLI command:
aws rds promote-read-replica-db-cluster --db-cluster-identifier <identifier>
After promoting the replica, update the stack configuration to prevent future Terrafrom runs from re-enabling
replication. In this example, modify stacks/catalog/aurora-mysql/replica/defaults.yaml
is_promoted_read_replica: true
Reploying the component should show no changes. For example,
atmos terraform apply aurora-mysql/dev -s platform-use2-dev
Variables
Required Variables
aurora_mysql_cluster_family
(string
) requiredDBParameterGroupFamily (e.g.
aurora5.6
,aurora-mysql5.7
for Aurora MySQL databases). See https://stackoverflow.com/a/55819394 for help finding the right one to use.aurora_mysql_engine
(string
) requiredEngine for Aurora database:
aurora
for MySQL 5.6,aurora-mysql
for MySQL 5.7region
(string
) requiredAWS Region
Optional Variables
allow_ingress_from_vpc_accounts
optionalList of account contexts to pull VPC ingress CIDR and add to cluster security group.
e.g.
{
environment = "ue2",
stage = "auto",
tenant = "core"
}Defaults to the "vpc" component in the given account
Type:
list(object({
vpc = optional(string, "vpc")
environment = optional(string)
stage = optional(string)
tenant = optional(string)
}))Default value:
[ ]
allowed_cidr_blocks
(list(string)
) optionalList of CIDR blocks to be allowed to connect to the RDS cluster
Default value:
[ ]
aurora_mysql_cluster_parameters
optionalList of DB cluster parameters to apply
Type:
list(object({
apply_method = string
name = string
value = string
}))Default value:
[ ]
aurora_mysql_engine_version
(string
) optionalEngine Version for Aurora database.
Default value:
""
aurora_mysql_instance_parameters
optionalList of DB instance parameters to apply
Type:
list(object({
apply_method = string
name = string
value = string
}))Default value:
[ ]
auto_minor_version_upgrade
(bool
) optionalAutomatically update the cluster when a new minor version is released
Default value:
false
eks_component_names
(set(string)
) optionalThe names of the eks components
Default value:
[
"eks/cluster"
]is_promoted_read_replica
(bool
) optionalIf
true
, do not assign a Replication Source to the Cluster. Set totrue
after manually promoting the cluster from a replica to a standalone cluster.Default value:
false
is_read_replica
(bool
) optionalIf
true
, create this DB cluster as a Read Replica.Default value:
false
mysql_admin_password
(string
) optionalMySQL password for the admin user
Default value:
""
mysql_admin_user
(string
) optionalMySQL admin user name
Default value:
""
mysql_backup_retention_period
(number
) optionalNumber of days for which to retain backups
Default value:
3
mysql_backup_window
(string
) optionalDaily time range during which the backups happen
Default value:
"07:00-09:00"
mysql_cluster_size
(string
) optionalMySQL cluster size
Default value:
2
mysql_db_name
(string
) optionalDatabase name (default is not to create a database
Default value:
""
mysql_deletion_protection
(string
) optionalSet to
true
to protect the database from deletionDefault value:
true
mysql_enabled_cloudwatch_logs_exports
(list(string)
) optionalList of log types to export to cloudwatch. The following log types are supported: audit, error, general, slowquery
Default value:
[
"audit",
"error",
"general",
"slowquery"
]mysql_instance_type
(string
) optionalEC2 instance type for RDS MySQL cluster
Default value:
"db.t3.medium"
mysql_maintenance_window
(string
) optionalWeekly time range during which system maintenance can occur, in UTC
Default value:
"sat:10:00-sat:10:30"
mysql_name
(string
) optionalMySQL solution name (part of cluster identifier)
Default value:
""
mysql_skip_final_snapshot
(string
) optionalDetermines whether a final DB snapshot is created before the DB cluster is deleted
Default value:
false
mysql_storage_encrypted
(string
) optionalSet to
true
to keep the database contents encryptedDefault value:
true
performance_insights_enabled
(bool
) optionalSet
true
to enable Performance InsightsDefault value:
false
primary_cluster_component
(string
) optionalIf this cluster is a read replica and no replication source is explicitly given, the component name for the primary cluster
Default value:
"aurora-mysql"
primary_cluster_region
(string
) optionalIf this cluster is a read replica and no replication source is explicitly given, the region to look for a matching cluster
Default value:
""
publicly_accessible
(bool
) optionalSet to true to create the cluster in a public subnet
Default value:
false
replication_source_identifier
(string
) optionalARN of a source DB cluster or DB instance if this DB cluster is to be created as a Read Replica.
If this value is empty and replication is enabled, remote state will attempt to find
a matching cluster in the Primary DB Cluster's regionDefault value:
""
ssm_password_source
(string
) optionalIf
var.ssm_passwords_enabled
istrue
, DB user passwords will be retrieved from SSM using
var.ssm_password_source
and the database username. If this value is not set,
a default path will be created using the SSM path prefix and ID of the associated Aurora Cluster.Default value:
""
ssm_path_prefix
(string
) optionalSSM path prefix
Default value:
"rds"
vpc_component_name
(string
) optionalThe name of the VPC component
Default value:
"vpc"
Context Variables
The following variables are defined in the context.tf
file of this module and part of the terraform-null-label pattern.
context.tf
file of this module and part of the terraform-null-label pattern.Outputs
aurora_mysql_cluster_arn
The ARN of Aurora cluster
aurora_mysql_cluster_id
The ID of Aurora cluster
aurora_mysql_cluster_name
Aurora MySQL cluster identifier
aurora_mysql_endpoint
Aurora MySQL endpoint
aurora_mysql_master_hostname
Aurora MySQL DB master hostname
aurora_mysql_master_password
Location of admin password in SSM
aurora_mysql_master_password_ssm_key
SSM key for admin password
aurora_mysql_master_username
Aurora MySQL username for the master DB user
aurora_mysql_reader_endpoint
Aurora MySQL reader endpoint
aurora_mysql_replicas_hostname
Aurora MySQL replicas hostname
cluster_domain
Cluster DNS name
kms_key_arn
KMS key ARN for Aurora MySQL
Dependencies
Requirements
terraform
, version:>= 1.0.0
aws
, version:>= 4.0
random
, version:>= 2.2
Providers
aws
, version:>= 4.0
random
, version:>= 2.2
Modules
Name | Version | Source | Description |
---|---|---|---|
aurora_mysql | 1.3.1 | cloudposse/rds-cluster/aws | n/a |
cluster | 0.25.0 | cloudposse/label/null | n/a |
dns-delegated | 1.5.0 | cloudposse/stack-config/yaml//modules/remote-state | n/a |
eks | 1.5.0 | cloudposse/stack-config/yaml//modules/remote-state | n/a |
iam_roles | latest | ../account-map/modules/iam-roles | n/a |
kms_key_rds | 0.12.1 | cloudposse/kms-key/aws | n/a |
parameter_store_write | 0.11.0 | cloudposse/ssm-parameter-store/aws | n/a |
primary_cluster | 1.5.0 | cloudposse/stack-config/yaml//modules/remote-state | n/a |
this | 0.25.0 | cloudposse/label/null | n/a |
vpc | 1.5.0 | cloudposse/stack-config/yaml//modules/remote-state | n/a |
vpc_ingress | 1.5.0 | cloudposse/stack-config/yaml//modules/remote-state | n/a |
Resources
The following resources are used by this module:
random_password.mysql_admin_password
(resource)random_pet.mysql_admin_user
(resource)random_pet.mysql_db_name
(resource)
Data Sources
The following data sources are used by this module:
aws_caller_identity.current
(data source)aws_iam_policy_document.kms_key_rds
(data source)aws_partition.current
(data source)aws_ssm_parameter.password
(data source)
References
- cloudposse/terraform-aws-components - Cloud Posse's upstream component