terraform-aws-arc-db

Overview

The SourceFuse AWS Reference Architecture (ARC) Terraform module offers a comprehensive solution for efficiently managing Aurora and RDS (Relational Database Service) instances within the Amazon Web Services (AWS) environment. This Terraform module is designed to streamline the provisioning, configuration, and management of these database instances, leveraging best practices.

For more information about this repository and its usage, please see Terraform AWS ARC DB Usage Guide.

Module Usage

To see a full example, check out the main.tf file in the example folder.

Requirements

Name	Version
terraform	>= 1.3, < 2.0.0
aws	>= 4.0
null	>= 3.1.1
random	>= 3.4.0

Providers

Name	Version
aws	4.57.0
random	3.4.3

Modules

Name	Source	Version
aurora_cluster	git::https://github.com/cloudposse/terraform-aws-rds-cluster.git	1.9.0
db_management	git::https://github.com/cloudposse/terraform-aws-s3-bucket	4.2.0
rds_instance	git::https://github.com/cloudposse/terraform-aws-rds	1.1.1
this	cloudposse/label/null	0.25.0

Resources

Name	Version
terraform	>= 1.3, < 2.0.0
aws	>= 4.0
null	>= 3.1.1
random	>= 3.4.0

Providers

Name	Version
aws	4.57.0
random	3.4.3

Modules

Name	Source	Version
aurora_cluster	git::https://github.com/cloudposse/terraform-aws-rds-cluster.git	1.9.0
db_management	git::https://github.com/cloudposse/terraform-aws-s3-bucket	4.2.0
rds_instance	git::https://github.com/cloudposse/terraform-aws-rds	1.1.1
this	cloudposse/label/null	0.25.0

Resources

Name	Type
aws_db_instance_role_association.this	resource
aws_db_option_group.this	resource
aws_iam_policy.option_group	resource
aws_iam_role.enhanced_monitoring	resource
aws_iam_role.option_group	resource
aws_iam_role_policy_attachment.enhanced_monitoring	resource
aws_iam_role_policy_attachment.option_group	resource
aws_kms_alias.aurora_cluster_kms_key	resource
aws_kms_alias.rds_db_kms_key	resource
aws_kms_key.aurora_cluster_kms_key	resource
aws_kms_key.rds_db_kms_key	resource
aws_security_group_rule.additional_ingress_rules_aurora	resource
aws_security_group_rule.additional_ingress_rules_rds	resource
aws_ssm_parameter.this	resource
random_password.aurora_db_admin_password	resource
random_password.rds_db_admin_password	resource
aws_iam_policy_document.enhanced_monitoring	data source
aws_partition.this	data source

Inputs

Name	Description	Type	Default	Required
account_id	Account ID where the resources will be deployed to. This is required if enable_custom_option_group is set to true.	string	""	no
additional_ingress_rules_aurora	Additional ingress rules for Aurora	list(object({ name = string description = string type = string from_port = number to_port = number protocol = string cidr_blocks = list(string) }))	[]	no
additional_ingress_rules_rds	Additional ingress rules for RDS	list(object({ name = string description = string type = string from_port = number to_port = number protocol = string cidr_blocks = list(string) }))	[]	no
additional_tag_map	Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id. This is for some rare cases where resources want additional configuration of tags and therefore take a list of maps with tag key, value, and additional configuration.	map(string)	{}	no
attributes	ID element. Additional attributes (e.g. workers or cluster) to add to id, in the order they appear in the list. New attributes are appended to the end of the list. The elements of the list are joined by the delimiter and treated as a single ID element.	list(string)	[]	no
aurora_allow_major_version_upgrade	Enable to allow major engine version upgrades when changing engine versions. Defaults to false.	bool	false	no
aurora_allowed_cidr_blocks	List of CIDR blocks allowed to access the cluster	list(string)	[]	no
aurora_auto_minor_version_upgrade	Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window	bool	true	no
aurora_backup_retention_period	Number of days to retain backups for	number	5	no
aurora_backup_window	Daily time range during which the backups happen	string	"07:00-09:00"	no
aurora_ca_cert_identifier	The identifier of the CA certificate for the Aurora DB instance	string	null	no
aurora_cluster_enabled	Enable creation of an Aurora Cluster	bool	false	no
aurora_cluster_family	The family of the DB cluster parameter group	string	"aurora-postgresql14"	no
aurora_cluster_name	Database name (default is not to create a database)	string	""	no
aurora_cluster_name_override	If true, this will set a the Aurora Cluster name to what is defined in var.aurora_cluster_name. If false, this will prepend ${var.namespace}-${var.environment} to ${var.aurora_cluster_name}"	bool	false	no
aurora_cluster_size	Number of DB instances to create in the cluster	number	0	no
aurora_db_admin_password	Password of the DB admin	string	""	no
aurora_db_admin_username	Name of the default DB admin user role	string	""	no
aurora_db_name	Database name.	string	"auroradb"	no
aurora_db_port	Port for the Aurora DB instance to use.	number	5432	no
aurora_enabled_cloudwatch_logs_exports	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), upgrade (PostgreSQL).	list(string)	[]	no
aurora_engine	The name of the database engine to be used for this DB cluster. Valid values: aurora, aurora-mysql, aurora-postgresql	string	"aurora-postgresql"	no
aurora_engine_mode	The database engine mode. Valid values: parallelquery, provisioned, serverless	string	"provisioned"	no
aurora_engine_version	The version of the database engine tocl use. See aws rds describe-db-engine-versions	string	"14.5"	no
aurora_instance_type	Instance type to use	string	"db.serverless"	no
aurora_iops	The amount of provisioned IOPS. Setting this implies a storage_type of 'io1'. This setting is required to create a Multi-AZ DB cluster. Check TF docs for values based on db engine	number	null	no
aurora_scaling_configuration	List of nested attributes with scaling properties. Only valid when engine_mode is set to serverless	list(object({ auto_pause = bool max_capacity = number min_capacity = number seconds_until_auto_pause = number timeout_action = string }))	[]	no
aurora_security_groups	List of security group IDs to be allowed to connect to the DB instance	list(string)	[]	no
aurora_serverlessv2_scaling_configuration	serverlessv2 scaling properties	object({ min_capacity = number max_capacity = number })	null	no
aurora_storage_type	One of 'standard' (magnetic), 'gp2' / 'gp3' (general purpose SSD), or 'io1' (provisioned IOPS SSD) or aurora-iopt1	string	null	no
aurora_subnets	Subnets for the cluster to run in.	list(string)	[]	no
context	Single object for setting entire context at once. See description of individual variables for details. Leave string and numeric variables as null to use default value. Individual variable settings (non-null) override settings in context object, except for attributes, tags, and additional_tag_map, which are merged.	any	{ "additional_tag_map": {}, "attributes": [], "delimiter": null, "descriptor_formats": {}, "enabled": true, "environment": null, "id_length_limit": null, "label_key_case": null, "label_order": [], "label_value_case": null, "labels_as_tags": [ "unset" ], "name": null, "namespace": null, "regex_replace_chars": null, "stage": null, "tags": {}, "tenant": null }	no
deletion_protection	Protect the instance from being deleted	bool	false	no
deletion_window_in_days	n/a	number	10	no
delimiter	Delimiter to be used between ID elements. Defaults to - (hyphen). Set to "" to use no delimiter at all.	string	null	no
descriptor_formats	Describe additional descriptors to be output in the descriptors output map. Map of maps. Keys are names of descriptors. Values are maps of the form {<br> format = string<br> labels = list(string)<br>} (Type is any so the map values can later be enhanced to provide additional options.) format is a Terraform format string to be passed to the format() function. labels is a list of labels, in order, to pass to format() function. Label values will be normalized before being passed to format() so they will be identical to how they appear in id. Default is {} (descriptors output will be empty).	any	{}	no
enable_key_rotation	n/a	bool	true	no
enabled	Set to false to prevent the module from creating any resources	bool	null	no
enhanced_monitoring_arn	ARN to the enhanced monitoring policy	string	"arn:aws:iam::aws:policy/service-role/AmazonRDSEnhancedMonitoringRole"	no
enhanced_monitoring_name	Name to assign the enhanced monitoring resources.	string	n/a	yes
environment	ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'	string	n/a	yes
iam_database_authentication_enabled	Specifies whether or mappings of AWS Identity and Access Management (IAM) accounts to database accounts is enabled	bool	false	no
id_length_limit	Limit id to this many characters (minimum 6). Set to 0 for unlimited length. Set to null for keep the existing setting, which defaults to 0. Does not affect id_full.	number	null	no
kms_key_arn	The ARN for the KMS encryption key. When specifying kms_key_arn, storage_encrypted needs to be set to true	string	""	no
label_key_case	Controls the letter case of the tags keys (label names) for tags generated by this module. Does not affect keys of tags passed in via the tags input. Possible values: lower, title, upper. Default value: title.	string	null	no
label_order	The order in which the labels (ID elements) appear in the id. Defaults to ["namespace", "environment", "stage", "name", "attributes"]. You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.	list(string)	null	no
label_value_case	Controls the letter case of ID elements (labels) as included in id, set as tag values, and output by this module individually. Does not affect values of tags passed in via the tags input. Possible values: lower, title, upper and none (no transformation). Set this to title and set delimiter to "" to yield Pascal Case IDs. Default value: lower.	string	null	no
labels_as_tags	Set of labels (ID elements) to include as tags in the tags output. Default is to include all labels. Tags with empty values will not be included in the tags output. Set to [] to suppress all generated tags. Notes: The value of the name tag, if included, will be the id, not the name. Unlike other null-label inputs, the initial setting of labels_as_tags cannot be changed in later chained modules. Attempts to change it will be silently ignored.	set(string)	[ "default" ]	no
name	ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'. This is the only ID element not also included as a tag. The "name" tag is set to the full id string. There is no tag with the value of the name input.	string	null	no
namespace	ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique	string	n/a	yes
performance_insights_enabled	Whether to enable Performance Insights	bool	false	no
performance_insights_kms_key_id	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	string	""	no
performance_insights_retention_period	Amount of time in days to retain Performance Insights data. Either 7 (7 days) or 731 (2 years)	number	null	no
rds_enable_custom_option_group	Enable the custom Option Group for restoring backups via S3	bool	false	no
rds_enabled_cloudwatch_logs_exports	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), upgrade (PostgreSQL).	list(string)	[]	no
rds_instance_allocated_storage	The allocated storage in GBs. Required unless a snapshot_identifier or replicate_source_db is provided.	number	20	no
rds_instance_allow_major_version_upgrade	Allow major version upgrade	bool	false	no
rds_instance_allowed_cidr_blocks	The whitelisted CIDRs which to allow ingress traffic to the DB instance	list(string)	[]	no
rds_instance_apply_immediately	Specifies whether any database modifications are applied immediately, or during the next maintenance window	bool	true	no
rds_instance_auto_minor_version_upgrade	Allow automated minor version upgrade (e.g. from Postgres 9.5.3 to Postgres 9.5.4)	bool	true	no
rds_instance_backup_retention_period	Backup retention period in days. Must be > 0 to enable backups	number	0	no
rds_instance_backup_window	When AWS can perform DB snapshots, can't overlap with maintenance window	string	"22:00-03:00"	no
rds_instance_ca_cert_identifier	The identifier of the CA certificate for the DB instance	string	null	no
rds_instance_copy_tags_to_snapshot	Copy tags from DB to a snapshot	bool	true	no
rds_instance_database_name	The name of the database to create when the DB instance is created	string	null	no
rds_instance_database_password	Password for the primary DB user. Required unless a snapshot_identifier or replicate_source_db is provided.	string	""	no
rds_instance_database_port	Database port (_e.g._ 3306 for MySQL). Used in the DB Security Group to allow access to the DB instance from the provided security_group_ids	number	5432	no
rds_instance_database_user	The name of the database to create when the DB instance is created	string	"admin"	no
rds_instance_db_options	A list of DB options to apply with an option group. Depends on DB engine	list(object({ db_security_group_memberships = list(string) option_name = string port = number version = string vpc_security_group_memberships = list(string) option_settings = list(object({ name = string value = string })) }))	[]	no
rds_instance_db_parameter	A list of DB parameters to apply. Note that parameters may differ from a DB family to another	list(object({ apply_method = string name = string value = string }))	[]	no
rds_instance_db_parameter_group	The DB parameter group family name. The value depends on DB engine used. See DBParameterGroupFamily for instructions on how to retrieve applicable value	string	"postgres16"	no
rds_instance_db_parameter_group_name	Name of the DB parameter group to associate.	string	""	no
rds_instance_dns_zone_id	The ID of the DNS Zone in Route53 where a new DNS record will be created for the DB host name	string	""	no
rds_instance_enabled	Enable creation of an RDS instance	bool	false	no
rds_instance_engine	Database engine type. Required unless a snapshot_identifier or replicate_source_db is provided. For supported values, see the Engine parameter in API action CreateDBInstance.	string	"postgres"	no
rds_instance_engine_version	Database engine version, depends on engine type. Required unless a snapshot_identifier or replicate_source_db is provided.	string	"16.2"	no
rds_instance_host_name	The DB host name created in Route53	string	"db"	no
rds_instance_instance_class	Class of RDS instance	string	"db.t3.medium"	no
rds_instance_iops	RDS instance IOPS	number	0	no
rds_instance_license_model	License model for this DB. Optional, but required for some DB Engines. Valid values: license-included | bring-your-own-license | general-public-license	string	""	no
rds_instance_maintenance_window	The window to perform maintenance in. Syntax: 'ddd:hh24:mi-ddd:hh24:mi' UTC	string	"Mon:03:00-Mon:04:00"	no
rds_instance_major_engine_version	major_engine_version Database MAJOR engine version, depends on engine type	string	"16"	no
rds_instance_multi_az	Set to true if multi AZ deployment must be supported	bool	false	no
rds_instance_name	RDS Instance name	string	""	no
rds_instance_name_override	If true, this will set a the RDS Instance name to what is defined in var.rds_instance_name. If false, this will prepend ${var.namespace}-${var.environment} to ${var.rds_instance_name}"	bool	false	no
rds_instance_option_group_name	Name of the DB option group to associate	string	""	no
rds_instance_publicly_accessible	Determines if database can be publicly available (NOT recommended)	bool	false	no
rds_instance_security_group_ids	The IDs of the security groups from which to allow ingress traffic to the DB instance	list(string)	[]	no
rds_instance_skip_final_snapshot	If true (default), no snapshot will be made before deleting DB	bool	true	no
rds_instance_snapshot_identifier	Snapshot identifier e.g: rds:production-2019-06-26-06-05. If specified, the module create cluster from the snapshot	string	null	no
rds_instance_storage_encrypted	Specifies whether the DB instance is encrypted. The default is false if not specified	bool	true	no
rds_instance_storage_type	One of 'standard' (magnetic), 'gp2' / 'gp3' (general purpose SSD), or 'io1' (provisioned IOPS SSD)	string	"gp3"	no
rds_instance_subnet_ids	List of subnet IDs for the DB. DB instance will be created in the VPC associated with the DB subnet group provisioned using the subnet IDs. Specify one of subnet_ids, db_subnet_group_name or availability_zone	list(string)	[]	no
rds_kms_key_arn_override	Override the default created KMS key to encrypt storage	string	""	no
rds_kms_key_id_override	Override the default created KMS key ID to encrypt storage	string	""	no
rds_monitoring_interval	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 are 0, 1, 5, 10, 15, 30, 60	number	0	no
rds_random_admin_password_length	Length of the generated random password.	number	64	no
regex_replace_chars	Terraform regular expression (regex) string. Characters matching the regex will be removed from the ID elements. If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.	string	null	no
region	Region which the resource is deployed to	string	"us-east-1"	no
s3_kms_alias_override	Override the KMS key alias for the S3 bucket. Default is set to AWS Managed KMS alias.	string	""	no
stage	ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'	string	null	no
tags	Additional tags (e.g. {'BusinessUnit': 'XYZ'}). Neither the tag keys nor the tag values will be modified by this module.	map(string)	{}	no
tenant	ID element _(Rarely used, not included by default)_. A customer identifier, indicating who this instance of a resource is for	string	""	no
timeouts	A list of DB timeouts to apply to the running code while creating, updating, or deleting the DB instance.	object({ create = string update = string delete = string })	{ "create": "40m", "delete": "60m", "update": "80m" }	no
vpc_id	vpc_id for the VPC to run the cluster.	string	n/a	yes
vpc_security_group_ids	Additional security group IDs to apply to the cluster, in addition to the provisioned default security group with ingress traffic from existing CIDR blocks and existing security groups	list(string)	[]	no

Outputs

Name	Description
aurora_arn	Amazon Resource Name (ARN) of cluster
aurora_cluster_identifier	Cluster Identifier
aurora_endpoint	The DNS address of the RDS instance
aurora_master_host	DB Master hostname
aurora_master_username	Username for the master DB user
aurora_name	Database name
aurora_reader_endpoint	A read-only endpoint for the Aurora cluster, automatically load-balanced across replicas
aurora_replicas_host	Replicas hostname
rds_instance_arn	The RDS Instance AWS ARN.
rds_instance_endpoint	The DNS address to the RDS Instance.
rds_instance_hostname	Hostname of the RDS Instance.
rds_instance_id	The RDS Instance AWS ID.
rds_instance_kms_arn	RDS KMS Key ARN
rds_instance_kms_id	Output RDS KMS Key ID if the var.rds_kms_key_arn_override is ""
rds_instance_resource_id	The RDS Instance AWS resource ID.

Development

Prerequisites

• terraform
• terraform-docs
• pre-commit
• golang
• golint

Configurations

• Configure pre-commit hooks

pre-commit install

Git commits

while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch

For Example

git commit -m "your commit message #major"

By specifying this , it will bump the version and if you dont specify this in your commit message then by default it will consider patch and will bump that accordingly

Tests

• Tests are available in test directory
• Configure the dependencies

cd test
go mod init github.com/sourcefuse/terraform-aws-ref-arch-db
go get github.com/gruntwork-io/terratest/modules/terraform

• Now execute the test

cd test/
go test

Authors

This project is authored by:

• SourceFuse ARC Team