Skip to content

Module Structure

terraform-aws-arc-db

Latest Release Last Updated Terraform GitHub Actions

Quality gate

Known Vulnerabilities

Overview

The SourceFuse AWS Reference Architecture (ARC) Terraform module offers a comprehensive solution for efficiently managing Aurora, RDS cluster, RDS proxy 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, < 6.0
null >= 3.1
random >= 3.4

Providers

Name Version
aws 5.73.0
random 3.6.3

Modules

Name Source Version
proxy_security_group ./modules/security-group n/a
security_group ./modules/security-group n/a

Resources

Name Type
aws_db_instance.this resource
aws_db_option_group.this resource
aws_db_parameter_group.this resource
aws_db_proxy.this resource
aws_db_proxy_default_target_group.this resource
aws_db_proxy_target.this resource
aws_db_subnet_group.this resource
aws_iam_policy.logs resource
aws_iam_policy.read_secrets resource
aws_iam_role.enhanced_monitoring resource
aws_iam_role.proxy resource
aws_iam_role_policy_attachment.attach_policy resource
aws_iam_role_policy_attachment.enhanced_monitoring resource
aws_iam_role_policy_attachment.proxy resource
aws_kms_alias.this resource
aws_kms_key.secret resource
aws_kms_key.this resource
aws_rds_cluster.this resource
aws_rds_cluster_instance.this resource
aws_secretsmanager_secret.this resource
aws_secretsmanager_secret_version.db_secret_version resource
aws_ssm_parameter.database_creds resource
random_password.master resource
aws_caller_identity.current data source
aws_iam_policy.enhanced_monitoring data source
aws_kms_alias.rds data source
aws_region.current data source

Inputs

Name Description Type Default Required
allocated_storage (optional) Storage for RDS instance string 20 no
allow_major_version_upgrade Whether major version upgrades are allowed during maintenance windows. bool false no
apply_immediately Whether to apply changes immediately or during the next maintenance window. bool false no
auto_minor_version_upgrade Whether minor engine upgrades are applied automatically during the maintenance window. bool true no
backup_retention_period The number of days to retain backups for the DB cluster. number 7 no
ca_cert_identifier The identifier of the CA certificate for the DB instance. If not specified, the RDS default CA is used. string null no
ca_certificate_identifier (optional) The CA certificate identifier to use for the DB cluster's server certificate. string null no
copy_tags_to_snapshot Whether to copy all tags to snapshots. bool true no
database_name The name of the database to create when the cluster is created. string null no
db_cluster_parameter_group_name (optional) A cluster parameter group to associate with the cluster. string null no
db_instance_parameter_group_name (optional) Instance parameter group to associate with all instances of the DB cluster. The db_instance_parameter_group_name parameter is only valid in combination with the allow_major_version_upgrade parameter. string null no
db_server_class Instance class for RDS instance string "db.t3.medium" no
db_subnet_group_data (optional) DB Subnet Group details 
object({
    name        = string
    create      = optional(bool, false)
    description = optional(string, null)
    subnet_ids  = optional(list(string), [])
  })
 n/a yes
delete_automated_backups (optional) Specifies whether to remove automated backups immediately after the DB cluster is deleted. Default is true. string true no
deletion_protection Whether to enable deletion protection for the DB cluster. bool false no
enable_multi_az Whether to enable Multi-AZ deployment for the RDS instance. bool false no
enabled_cloudwatch_logs_exports List of log types to export to CloudWatch Logs. Valid values: audit, error, general, slowquery. list(string) [] no
engine The database engine to use for the RDS cluster (e.g., aurora, aurora-mysql, aurora-postgresql). string n/a yes
engine_lifecycle_support (optional) The life cycle type for this DB instance. This setting is valid for cluster types Aurora DB clusters and Multi-AZ DB clusters. Valid values are open-source-rds-extended-support, open-source-rds-extended-support-disabled. Default value is open-source-rds-extended-support string "open-source-rds-extended-support" no
engine_mode (optional) Database engine mode. Valid values: global (only valid for Aurora MySQL 1.21 and earlier), parallelquery, provisioned, serverless. Defaults to: provisioned
Note :- For Serverless V2 , engine_mode should be "provisioned" but for simplecity "serverless" is expected
Refer : https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/rds_cluster#rds-serverless-v2-cluster		 string "provisioned" no
engine_type (optional) Engine type, valid values are 'rds' or 'cluster' string n/a yes
engine_version The version of the database engine to use. 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
final_snapshot_identifier (optional) Name of your final DB snapshot when this DB cluster is deleted. If omitted, no final snapshot will be made. string null no
iam_database_authentication_enabled Enable IAM database authentication for the RDS cluster. bool false no
iops The amount of provisioned IOPS. Required if using io1 storage type. number 0 no
kms_data Configuration for KMS key settings for RDS encryption and performance insights:
- create: (Optional) If true, a new KMS key is created.
- kms_key_id: (Optional) The ID of an existing KMS key for RDS encryption. If null it used AWS managed keys
- performance_insights_kms_key_id: (Optional) Key ID for Performance Insights. If null it used AWS managed keys
- description: (Optional) description for the KMS key.
- policy: (Optional) Specific policy for the KMS key.
- deletion_window_in_days: (Optional) Number of days before deletion, default is 7.
- enable_key_rotation: (Optional) Enables key rotation for security; defaults to true.		 
object({
    create                          = optional(bool, true)
    kms_key_id                      = optional(string, null)
    performance_insights_kms_key_id = optional(string, null)
    name                            = optional(string, null)
    description                     = optional(string, null)
    policy                          = optional(string, null)
    deletion_window_in_days         = optional(number, 7)
    enable_key_rotation             = optional(bool, true)
  })
 
{
  "create": false
}
 no
license_model The license model for the DB instance (e.g., license-included, bring-your-own-license, general-public-license). string n/a yes
manage_user_password (optional) Set to true to allow RDS to manage the master user password in Secrets Manager. Cannot be set if master_password is provided."
null - is equal to 'false', don't set it to false , known bug : https://github.com/hashicorp/terraform-provider-aws/issues/31179		 bool null no
monitoring_interval The interval, in seconds, between points when Enhanced Monitoring metrics are collected. Valid values are 0, 1, 5, 10, 15, 30, 60. number 0 no
monitoring_role_arn The ARN for the IAM role that allows RDS to send Enhanced Monitoring metrics to CloudWatch Logs. string null no
name The identifier for the RDS instance or cluster. string n/a yes
namespace Namespace for the resources. string n/a yes
network_type (optional) Network type of the cluster. Valid values: IPV4, DUAL. string "IPV4" no
option_group_config Configuration for RDS option group, with attributes to create or specify a group name, engine details, and database options including settings, ports, and versions. 
object({
    create               = optional(bool, false)
    name                 = optional(string, null)
    engine_name          = optional(string)
    major_engine_version = optional(string)
    description          = optional(string, "Managed by Terraform")
    options = map(object({
      option_name = string
      port        = number
      version     = string
      option_settings = map(object({
        name  = string
        value = string
      }))
    }))
  })
 
{
  "name": null,
  "options": {}
}
 no
parameter_group_config Configuration for RDS parameter group, with options to create or specify a group name, family, and a map of database parameters including settings and apply methods. 
object({
    create      = optional(bool, false)
    name        = optional(string, null)
    family      = optional(string)
    description = optional(string, "Managed by Terraform")
    parameters = map(object({
      name         = string
      value        = string
      apply_method = optional(string, "immediate") # Options: "immediate" or "pending-reboot"
    }))
  })
 
{
  "name": null,
  "parameters": {}
}
 no
password The password for the database. string null no
performance_insights_enabled (optional) Valid only for Non-Aurora Multi-AZ DB Clusters. Enables Performance Insights for the RDS Cluster bool false no
performance_insights_retention_period The retention period (in days) for Performance Insights data. Valid values are 7, 731, or any value between 8 and 730. number 7 no
port Port on which the DB accepts connections number n/a yes
preferred_backup_window The daily time range during which backups are taken. string "07:00-09:00" no
preferred_maintenance_window The weekly time range during which maintenance can occur. string "sun:06:00-sun:07:00" no
proxy_config Configuration object for setting up an AWS RDS Proxy. It includes options for creating the proxy, connection pooling, authentication, and other proxy-specific settings.

- create (optional): A boolean that determines whether to create the RDS Proxy resource. Defaults to false.
- name (optional): The name of the RDS Proxy. If not specified, Terraform will create a default name.
- engine_family: The database engine family for the proxy (e.g., "MYSQL", "POSTGRESQL").
- vpc_subnet_ids: List of VPC subnet IDs in which the proxy will be deployed.
- security_group_data: List of security groups to associate with the RDS Proxy.
- require_tls (optional): Boolean flag to enforce the use of TLS for client connections to the proxy. Defaults to false.
- debug_logging (optional): Boolean flag to enable debug logging for the proxy. Defaults to false.
- idle_client_timeout_secs (optional): Number of seconds before the proxy closes idle client connections. The minimum is 60 seconds (1 minute), and the maximum is 28,800 seconds (8 hours). Defaults to 1,800 seconds (30 minutes).
- role_arn (optional): The ARN of the IAM role used by the proxy for accessing database credentials in AWS Secrets Manager. If null, Terraform will create a new IAM role.

Authentication settings:
- auth.auth_scheme: The authentication scheme to use (e.g., "SECRETS").
- auth.description (optional): A description of the authentication method. Defaults to null.
- auth.iam_auth (optional): Specifies whether to use IAM authentication for the proxy. Defaults to "DISABLED".
- auth.secret_arn: The ARN of the AWS Secrets Manager secret that contains the database credentials.
- auth.client_password_auth_type: Specifies the password authentication type for the database.

Connection pool configuration:
- connection_pool_config.connection_borrow_timeout (optional): The amount of time (in seconds) a client connection can be held open before being returned to the pool. Defaults to 5 seconds.
- connection_pool_config.init_query (optional): An optional initialization query executed when a connection is first established. Defaults to null.
- connection_pool_config.max_connections_percent (optional): The maximum percentage of available database connections that the proxy can use. Defaults to 100%.
- connection_pool_config.max_idle_connections_percent (optional): The maximum percentage of idle database connections that the proxy can keep open. Defaults to 50%.
- connection_pool_config.session_pinning_filters (optional): List of filters for controlling session pinning behavior. Defaults to an empty list.		 
object({
    create                   = optional(bool, false)
    name                     = optional(string, null)
    engine_family            = string
    vpc_subnet_ids           = list(string)
    require_tls              = optional(bool, false)
    debug_logging            = optional(bool, false)
    idle_client_timeout_secs = optional(number, 30 * 60) // in seconds The minimum is 1 minute and the maximum is 8 hours.
    role_arn                 = optional(string, null)    // null value will create new role
    auth = object({
      auth_scheme               = string
      description               = optional(string, null)
      iam_auth                  = optional(string, "DISABLED")
      client_password_auth_type = string
    })
    additional_auth_list = optional(list(object({
      auth_scheme               = string
      secret_arn                = optional(string, null)
      description               = optional(string, null)
      iam_auth                  = optional(string, "DISABLED")
      client_password_auth_type = string
    })), [])
    connection_pool_config = object({
      connection_borrow_timeout    = optional(number, 5)
      init_query                   = optional(string, null)
      max_connections_percent      = optional(number, 100)
      max_idle_connections_percent = optional(number, 50)
      session_pinning_filters      = optional(list(string), [])
    })
    security_group_data = optional(object({
      security_group_ids_to_attach = optional(list(string), [])
      create                       = optional(bool, true)
      description                  = optional(string, null)
      ingress_rules = optional(list(object({
        description              = optional(string, null)
        cidr_block               = optional(string, null)
        source_security_group_id = optional(string, null)
        from_port                = number
        ip_protocol              = string
        to_port                  = string
        self                     = optional(bool, false)
      })), [])
      egress_rules = optional(list(object({
        description                   = optional(string, null)
        cidr_block                    = optional(string, null)
        destination_security_group_id = optional(string, null)
        from_port                     = number
        ip_protocol                   = string
        to_port                       = string
      })), [])
    }))
  })
 
{
  "auth": null,
  "connection_pool_config": null,
  "create": false,
  "engine_family": "POSTGRESQL",
  "security_group_data": {
    "create": false
  },
  "vpc_subnet_ids": []
}
 no
publicly_accessible Whether the RDS instance should be publicly accessible. bool false no
rds_cluster_instances "(optional) A list of objects defining configurations for RDS Cluster instances. Each object represents a single RDS instance configuration within the cluster, including options for instance class, monitoring, performance insights, maintenance windows, and other instance-specific settings."
name: Optional. Name of the instance (default: null).
instance_class: The instance class for the RDS instance (e.g., db.r5.large).
availability_zone: Optional. Specifies the availability zone for the instance (default: null).
publicly_accessible: Optional. Whether the instance is publicly accessible (default: false).
db_parameter_group_name: Optional. The name of the DB parameter group to associate with the instance (default: null).
apply_immediately: Optional. Apply modifications immediately or during the next maintenance window (default: false).
ca_cert_identifier: Optional. Identifier for the CA certificate for the instance (default: null).
promotion_tier: Optional. Promotion tier for the instance within the cluster (default: 0).
copy_tags_to_snapshot: Optional. Copy tags to snapshots (default: true).		 
list(object({
    name                    = optional(string, null)
    instance_class          = string
    availability_zone       = optional(string, null)
    publicly_accessible     = optional(bool, false)
    db_parameter_group_name = optional(string, null)
    promotion_tier          = optional(number, 0)
    copy_tags_to_snapshot   = optional(bool, true)
  }))
 [] no
security_group_data (optional) Security Group data 
object({
    security_group_ids_to_attach = optional(list(string), [])
    create                       = optional(bool, true)
    description                  = optional(string, null)
    ingress_rules = optional(list(object({
      description              = optional(string, null)
      cidr_block               = optional(string, null)
      source_security_group_id = optional(string, null)
      from_port                = number
      ip_protocol              = string
      to_port                  = string
    })), [])
    egress_rules = optional(list(object({
      description                   = optional(string, null)
      cidr_block                    = optional(string, null)
      destination_security_group_id = optional(string, null)
      from_port                     = number
      ip_protocol                   = string
      to_port                       = string
    })), [])
  })
 
{
  "create": false
}
 no
serverlessv2_scaling_config Configuration for Serverless V2 scaling:
- max_capacity: (Required) The maximum ACU capacity for scaling (e.g., 256.0).
- min_capacity: (Required) The minimum ACU capacity for scaling (e.g., 0.5).		 
object({
    max_capacity = number
    min_capacity = number
  })
 
{
  "max_capacity": 1,
  "min_capacity": 0.5
}
 no
skip_final_snapshot (optional) Determines whether a final DB snapshot is created before the DB cluster is deleted. If true is specified, no DB snapshot is created. If false is specified, a DB snapshot is created before the DB cluster is deleted, using the value from final_snapshot_identifier. Default is false. string true no
storage_encrypted Whether to enable storage encryption. bool true no
storage_type (optional) Required for Multi-AZ DB cluster) (Forces new for Multi-AZ DB clusters) Specifies the storage type to be associated with the DB cluster. For Aurora DB clusters, storage_type modifications can be done in-place. For Multi-AZ DB Clusters, the iops argument must also be set. Valid values are: "", aurora-iopt1 (Aurora DB Clusters); io1, io2 (Multi-AZ DB Clusters). Default: "" (Aurora DB Clusters); io1 (Multi-AZ DB Clusters). string "" no
tags A map of tags to assign to the DB Cluster. map(string) {} no
username The username for the database. string n/a yes
vpc_id VPC Id for creating security group string n/a yes

Outputs

Name Description
arn Instance or Cluster ARN
database database name
endpoint Instance or Cluster Endpoint
id Instance or Cluster ID
identifier Instance or Cluster Identifier
kms_key_id Instance or Cluster KM Key ID
monitoring_role_arn Instance or Cluster Monitoring role arn
performance_insights_kms_key_id Instance or Cluster Performance insight KM Key ID
port Dtabase server port
username Username for the Database

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

1
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
1
2
3
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
1
2
cd test/
go test

Authors

This project is authored by:

  • SourceFuse ARC Team