Skip to content

terraform-aws-modules/terraform-aws-rds-aurora

master
Switch branches/tags
Code

Latest commit

### [7.5.1](v7.5.0...v7.5.1) (2022-09-12)

### Bug Fixes

* Update miminum provider version required for current arguments supported ([#324](#324)) ([5f61877](5f61877))
7d4c25b

Git stats

Files

Permalink
Failed to load latest commit information.

AWS RDS Aurora Terraform module

Terraform module which creates AWS RDS Aurora resources.

SWUbanner

Available Features

  • Autoscaling of read-replicas
  • Global cluster
  • Enhanced monitoring
  • Serverless cluster (v1 and v2)
  • Import from S3
  • Fine grained control of individual cluster instances
  • Custom endpoints
  • RDS multi-AZ support (not Aurora)

Usage

module "cluster" {
  source  = "terraform-aws-modules/rds-aurora/aws"

  name           = "test-aurora-db-postgres96"
  engine         = "aurora-postgresql"
  engine_version = "11.12"
  instance_class = "db.r6g.large"
  instances = {
    one = {}
    2 = {
      instance_class = "db.r6g.2xlarge"
    }
  }

  vpc_id  = "vpc-12345678"
  subnets = ["subnet-12345678", "subnet-87654321"]

  allowed_security_groups = ["sg-12345678"]
  allowed_cidr_blocks     = ["10.20.0.0/20"]

  storage_encrypted   = true
  apply_immediately   = true
  monitoring_interval = 10

  db_parameter_group_name         = "default"
  db_cluster_parameter_group_name = "default"

  enabled_cloudwatch_logs_exports = ["postgresql"]

  tags = {
    Environment = "dev"
    Terraform   = "true"
  }
}

Cluster Instance Configuration

There are a couple different configuration methods that can be used to create instances within the cluster:

ℹ️ Only the pertinent attributes are shown for brevity

  1. Create homogenous cluster of any number of instances
  • Resources created:
    • Writer: 1
    • Reader(s): 2
  instance_class = "db.r6g.large"
  instances = {
    one   = {}
    two   = {}
    three = {}
  }
  1. Create homogenous cluster of instances w/ autoscaling enabled. This is redundant and we'll show why in the next example.
  • Resources created:
    • Writer: 1
    • Reader(s):
      • At least 4 readers (2 created directly, 2 created by appautoscaling)
      • At most 7 reader instances (2 created directly, 5 created by appautoscaling)

ℹ️ Autoscaling uses the instance class specified by instance_class.

  instance_class = "db.r6g.large"
  instances = {
    one   = {}
    two   = {}
    three = {}
  }

  autoscaling_enabled      = true
  autoscaling_min_capacity = 2
  autoscaling_max_capacity = 5
  1. Create homogeneous cluster scaled via autoscaling. At least one instance (writer) is required
  • Resources created:
    • Writer: 1
    • Reader(s):
      • At least 1 reader
      • At most 5 readers
  instance_class = "db.r6g.large"
  instances = {
    one = {}
  }

  autoscaling_enabled      = true
  autoscaling_min_capacity = 1
  autoscaling_max_capacity = 5
  1. Create heterogenous cluster to support mixed-use workloads

    It is common in this configuration to independently control the instance promotion_tier paired with endpoints to create custom endpoints directed at select instances or instance groups.

  • Resources created:
    • Writer: 1
    • Readers: 2
  instance_class = "db.r5.large"
  instances = {
    one = {
      instance_class      = "db.r5.2xlarge"
      publicly_accessible = true
    }
    two = {
      identifier     = "static-member-1"
      instance_class = "db.r5.2xlarge"
    }
    three = {
      identifier     = "excluded-member-1"
      instance_class = "db.r5.large"
      promotion_tier = 15
    }
  }
  1. Create heterogenous cluster to support mixed-use workloads w/ autoscaling enabled
  • Resources created:
    • Writer: 1
    • Reader(s):
      • At least 3 readers (2 created directly, 1 created through appautoscaling)
      • At most 7 readers (2 created directly, 5 created through appautoscaling)

ℹ️ Autoscaling uses the instance class specified by instance_class.

  instance_class = "db.r5.large"
  instances = {
    one = {
      instance_class      = "db.r5.2xlarge"
      publicly_accessible = true
    }
    two = {
      identifier     = "static-member-1"
      instance_class = "db.r5.2xlarge"
    }
    three = {
      identifier     = "excluded-member-1"
      instance_class = "db.r5.large"
      promotion_tier = 15
    }
  }

  autoscaling_enabled      = true
  autoscaling_min_capacity = 1
  autoscaling_max_capacity = 5

Conditional Creation

The following values are provided to toggle on/off creation of the associated resources as desired:

# This RDS cluster will not be created
module "cluster" {
  source  = "terraform-aws-modules/rds-aurora/aws"

  # Disable creation of cluster and all resources
  create_cluster = false

  # Disable creation of subnet group - provide a subnet group
  create_db_subnet_group = false

  # Disable creation of security group - provide a security group
  create_security_group = false

  # Disable creation of monitoring IAM role - provide a role ARN
  create_monitoring_role = false

  # Disable creation of random password - AWS API provides the password
  create_random_password = false

  # ... omitted
}

Examples

  • Autoscaling: A PostgreSQL cluster with enhanced monitoring and autoscaling enabled
  • Global Cluster: A PostgreSQL global cluster with clusters provisioned in two different region
  • Multi-AZ: A multi-AZ RDS cluster (not using Aurora engine)
  • MySQL: A simple MySQL cluster
  • PostgreSQL: A simple PostgreSQL cluster
  • S3 Import: A MySQL cluster created from a Percona Xtrabackup stored in S3
  • Serverless: Serverless V1 and V2 (PostgreSQL and MySQL)

Documentation

Terraform documentation is generated automatically using pre-commit hooks. Follow installation instructions here.

Requirements

Name Version
terraform >= 0.13
aws >= 4.30
random >= 2.2

Providers

Name Version
aws >= 4.30
random >= 2.2

Modules

No modules.

Resources

Name Type
aws_appautoscaling_policy.this resource
aws_appautoscaling_target.this resource
aws_db_parameter_group.this resource
aws_db_subnet_group.this resource
aws_iam_role.rds_enhanced_monitoring resource
aws_iam_role_policy_attachment.rds_enhanced_monitoring resource
aws_rds_cluster.this resource
aws_rds_cluster_endpoint.this resource
aws_rds_cluster_instance.this resource
aws_rds_cluster_parameter_group.this resource
aws_rds_cluster_role_association.this resource
aws_security_group.this resource
aws_security_group_rule.cidr_ingress resource
aws_security_group_rule.default_ingress resource
aws_security_group_rule.egress resource
random_id.snapshot_identifier resource
random_password.master_password resource
aws_iam_policy_document.monitoring_rds_assume_role data source
aws_partition.current data source

Inputs

Name Description Type Default Required
allocated_storage The amount of storage in gibibytes (GiB) to allocate to each DB instance in the Multi-AZ DB cluster. (This setting is required to create a Multi-AZ DB cluster) number null no
allow_major_version_upgrade Enable to allow major engine version upgrades when changing engine versions. Defaults to false bool false no
allowed_cidr_blocks A list of CIDR blocks which are allowed to access the database list(string) [] no
allowed_security_groups A list of Security Group ID's to allow access to list(string) [] no
apply_immediately Specifies whether any cluster modifications are applied immediately, or during the next maintenance window. Default is false bool null no
auto_minor_version_upgrade Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window. Default true bool null no
autoscaling_enabled Determines whether autoscaling of the cluster read replicas is enabled bool false no
autoscaling_max_capacity Maximum number of read replicas permitted when autoscaling is enabled number 2 no
autoscaling_min_capacity Minimum number of read replicas permitted when autoscaling is enabled number 0 no
autoscaling_policy_name Autoscaling policy name string "target-metric" no
autoscaling_scale_in_cooldown Cooldown in seconds before allowing further scaling operations after a scale in number 300 no
autoscaling_scale_out_cooldown Cooldown in seconds before allowing further scaling operations after a scale out number 300 no
autoscaling_target_connections Average number of connections threshold which will initiate autoscaling. Default value is 70% of db.r4/r5/r6g.large's default max_connections number 700 no
autoscaling_target_cpu CPU threshold which will initiate autoscaling number 70 no
availability_zones List of EC2 Availability Zones for the DB cluster storage where DB cluster instances can be created. RDS automatically assigns 3 AZs if less than 3 AZs are configured, which will show as a difference requiring resource recreation next Terraform apply list(string) null no
backtrack_window The target backtrack window, in seconds. Only available for aurora engine currently. To disable backtracking, set this value to 0. Must be between 0 and 259200 (72 hours) number null no
backup_retention_period The days to retain backups for. Default 7 number 7 no
ca_cert_identifier The identifier of the CA certificate for the DB instance string null no
cluster_members List of RDS Instances that are a part of this cluster list(string) null no
cluster_tags A map of tags to add to only the cluster. Used for AWS Instance Scheduler tagging map(string) {} no
cluster_timeouts Create, update, and delete timeout configurations for the cluster map(string) {} no
cluster_use_name_prefix Whether to use name as a prefix for the cluster bool false no
copy_tags_to_snapshot Copy all Cluster tags to snapshots bool null no
create_cluster Whether cluster should be created (affects nearly all resources) bool true no
create_db_cluster_parameter_group Determines whether a cluster parameter should be created or use existing bool false no
create_db_parameter_group Determines whether a DB parameter should be created or use existing bool false no
create_db_subnet_group Determines whether to create the database subnet group or use existing bool true no
create_monitoring_role Determines whether to create the IAM role for RDS enhanced monitoring bool true no
create_random_password Determines whether to create random password for RDS primary cluster bool true no
create_security_group Determines whether to create security group for RDS cluster bool true no
database_name Name for an automatically created database on cluster creation string null no
db_cluster_db_instance_parameter_group_name Instance parameter group to associate with all instances of the DB cluster. The db_cluster_db_instance_parameter_group_name is only valid in combination with allow_major_version_upgrade string null no
db_cluster_instance_class The compute and memory capacity of each DB instance in the Multi-AZ DB cluster, for example db.m6g.xlarge. Not all DB instance classes are available in all AWS Regions, or for all database engines string null no
db_cluster_parameter_group_description The description of the DB cluster parameter group. Defaults to "Managed by Terraform" string null no
db_cluster_parameter_group_family The family of the DB cluster parameter group string "" no
db_cluster_parameter_group_name The name of the DB cluster parameter group string null no
db_cluster_parameter_group_parameters A list of DB cluster parameters to apply. Note that parameters may differ from a family to an other list(map(string)) [] no
db_cluster_parameter_group_use_name_prefix Determines whether the DB cluster parameter group name is used as a prefix bool true no
db_parameter_group_description The description of the DB parameter group. Defaults to "Managed by Terraform" string null no
db_parameter_group_family The family of the DB parameter group string "" no
db_parameter_group_name The name of the DB parameter group string null no
db_parameter_group_parameters A list of DB parameters to apply. Note that parameters may differ from a family to an other list(map(string)) [] no
db_parameter_group_use_name_prefix Determines whether the DB parameter group name is used as a prefix bool true no
db_subnet_group_name The name of the subnet group name (existing or created) string "" no
deletion_protection If the DB instance should have deletion protection enabled. The database can't be deleted when this value is set to true. The default is false bool null no
enable_global_write_forwarding Whether cluster should forward writes to an associated global cluster. Applied to secondary clusters to enable them to forward writes to an aws_rds_global_cluster's primary cluster bool null no
enable_http_endpoint Enable HTTP endpoint (data API). Only valid when engine_mode is set to serverless bool null no
enabled_cloudwatch_logs_exports Set of log types to export to cloudwatch. If omitted, no logs will be exported. The following log types are supported: audit, error, general, slowquery, postgresql list(string) [] no
endpoints Map of additional cluster endpoints and their attributes to be created any {} no
engine The name of the database engine to be used for this DB cluster. Defaults to aurora. Valid Values: aurora, aurora-mysql, aurora-postgresql string null no
engine_mode The database engine mode. Valid values: global, multimaster, parallelquery, provisioned, serverless. Defaults to: provisioned string null no
engine_version The database engine version. Updating this argument results in an outage string null no
final_snapshot_identifier_prefix The prefix name to use when creating a final snapshot on cluster destroy; a 8 random digits are appended to name to ensure it's unique string "final" no
global_cluster_identifier The global cluster identifier specified on aws_rds_global_cluster string null no
iam_database_authentication_enabled Specifies whether or mappings of AWS Identity and Access Management (IAM) accounts to database accounts is enabled bool null no
iam_role_description Description of the monitoring role string null no
iam_role_force_detach_policies Whether to force detaching any policies the monitoring role has before destroying it bool null no
iam_role_managed_policy_arns Set of exclusive IAM managed policy ARNs to attach to the monitoring role list(string) null no
iam_role_max_session_duration Maximum session duration (in seconds) that you want to set for the monitoring role number null no
iam_role_name Friendly name of the monitoring role string null no
iam_role_path Path for the monitoring role string null no
iam_role_permissions_boundary The ARN of the policy that is used to set the permissions boundary for the monitoring role string null no
iam_role_use_name_prefix Determines whether to use iam_role_name as is or create a unique name beginning with the iam_role_name as the prefix bool false no
iam_roles Map of IAM roles and supported feature names to associate with the cluster map(map(string)) {} no
instance_class Instance type to use at master instance. Note: if autoscaling_enabled is true, this will be the same instance class used on instances created by autoscaling string "" no
instance_timeouts Create, update, and delete timeout configurations for the cluster instance(s) map(string) {} no
instances Map of cluster instances and any specific/overriding attributes to be created any {} no
instances_use_identifier_prefix Determines whether cluster instance identifiers are used as prefixes bool false no
iops The amount of Provisioned IOPS (input/output operations per second) to be initially allocated for each DB instance in the Multi-AZ DB cluster number null no
is_primary_cluster Determines whether cluster is primary cluster with writer instance (set to false for global cluster and replica clusters) bool true no
kms_key_id The ARN for the KMS encryption key. When specifying kms_key_id, storage_encrypted needs to be set to true string null no
master_password Password for the master DB user. Note - when specifying a value here, 'create_random_password' should be set to false string null no
master_username Username for the master DB user string "root" no
monitoring_interval The interval, in seconds, between points when Enhanced Monitoring metrics are collected for instances. Set to 0 to disable. Default is 0 number 0 no
monitoring_role_arn IAM role used by RDS to send enhanced monitoring metrics to CloudWatch string "" no
name Name used across resources created string "" no
network_type The type of network stack to use (IPV4 or DUAL) string null no
performance_insights_enabled Specifies whether Performance Insights is enabled or not bool null no
performance_insights_kms_key_id The ARN for the KMS key to encrypt Performance Insights data string null 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
port The port on which the DB accepts connections string null no
predefined_metric_type The metric type to scale on. Valid values are RDSReaderAverageCPUUtilization and RDSReaderAverageDatabaseConnections string "RDSReaderAverageCPUUtilization" no
preferred_backup_window The daily time range during which automated backups are created if automated backups are enabled using the backup_retention_period parameter. Time in UTC string "02:00-03:00" no
preferred_maintenance_window The weekly time range during which system maintenance can occur, in (UTC) string "sun:05:00-sun:06:00" no
publicly_accessible Determines whether instances are publicly accessible. Default false bool null no
putin_khuylo Do you agree that Putin doesn't respect Ukrainian sovereignty and territorial integrity? More info: https://en.wikipedia.org/wiki/Putin_khuylo! bool true no
random_password_length Length of random password to create. Defaults to 10 number 10 no
replication_source_identifier ARN of a source DB cluster or DB instance if this DB cluster is to be created as a Read Replica string null no
restore_to_point_in_time Map of nested attributes for cloning Aurora cluster map(string) {} no
s3_import Configuration map used to restore from a Percona Xtrabackup in S3 (only MySQL is supported) map(string) {} no
scaling_configuration Map of nested attributes with scaling properties. Only valid when engine_mode is set to serverless map(string) {} no
security_group_description The description of the security group. If value is set to empty string it will contain cluster name in the description string null no
security_group_egress_rules A map of security group egress rule definitions to add to the security group created map(any) {} no
security_group_tags Additional tags for the security group map(string) {} no
security_group_use_name_prefix Determines whether the security group name (name) is used as a prefix bool true no
serverlessv2_scaling_configuration Map of nested attributes with serverless v2 scaling properties. Only valid when engine_mode is set to provisioned map(string) {} no
skip_final_snapshot Determines whether a final snapshot is created before the cluster is deleted. If true is specified, no snapshot is created bool null no
snapshot_identifier Specifies whether or not to create this cluster from a snapshot. You can use either the name or ARN when specifying a DB cluster snapshot, or the ARN when specifying a DB snapshot string null no
source_region The source region for an encrypted replica DB cluster string null no
storage_encrypted Specifies whether the DB cluster is encrypted. The default is true bool true no
storage_type Specifies the storage type to be associated with the DB cluster. (This setting is required to create a Multi-AZ DB cluster). Valid values: io1, Default: io1 string null no
subnets List of subnet IDs used by database subnet group created list(string) [] no
tags A map of tags to add to all resources map(string) {} no
vpc_id ID of the VPC where to create security group string "" no
vpc_security_group_ids List of VPC security groups to associate to the cluster in addition to the SG we create in this module list(string) [] no

Outputs

Name Description
additional_cluster_endpoints A map of additional cluster endpoints and their attributes
cluster_arn Amazon Resource Name (ARN) of cluster
cluster_database_name Name for an automatically created database on cluster creation
cluster_endpoint Writer endpoint for the cluster
cluster_engine_version_actual The running version of the cluster database
cluster_hosted_zone_id The Route53 Hosted Zone ID of the endpoint
cluster_id The RDS Cluster Identifier
cluster_instances A map of cluster instances and their attributes
cluster_master_password The database master password
cluster_master_username The database master username
cluster_members List of RDS Instances that are a part of this cluster
cluster_port The database port
cluster_reader_endpoint A read-only endpoint for the cluster, automatically load-balanced across replicas
cluster_resource_id The RDS Cluster Resource ID
cluster_role_associations A map of IAM roles associated with the cluster and their attributes
db_cluster_parameter_group_arn The ARN of the DB cluster parameter group created
db_cluster_parameter_group_id The ID of the DB cluster parameter group created
db_parameter_group_arn The ARN of the DB parameter group created
db_parameter_group_id The ID of the DB parameter group created
db_subnet_group_name The db subnet group name
enhanced_monitoring_iam_role_arn The Amazon Resource Name (ARN) specifying the enhanced monitoring role
enhanced_monitoring_iam_role_name The name of the enhanced monitoring role
enhanced_monitoring_iam_role_unique_id Stable and unique string identifying the enhanced monitoring role
security_group_id The security group ID of the cluster

Authors

Module is maintained by Anton Babenko with help from these awesome contributors.

License

Apache 2 Licensed. See LICENSE for full details.

Additional information for users from Russia and Belarus