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	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_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 6^th), 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¶

Configurations¶

Configure pre-commit hooks

1	`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

terraform-aws-arc-db¶