Skip to content

caioleonmendes/terraform-aws-rds-aurora

 
 

Repository files navigation

AWS RDS Aurora Terraform module

Terraform module which creates AWS RDS Aurora resources.

Available Features

  • Autoscaling of read-replicas
  • Global cluster
  • Enhanced monitoring
  • Serverless cluster
  • Import from S3
  • Fine grained control of individual cluster instances
  • Custom endpoints

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
  • 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 PostgreSQL and MySQL clusters

Documentation

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

Requirements

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

Providers

Name Version
aws >= 3.63
random >= 2.2

Modules

No modules.

Resources

Name Type
aws_appautoscaling_policy.this resource
aws_appautoscaling_target.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_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
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_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
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_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
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_subnet_group Determines whether to create the databae 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_parameter_group_name A cluster parameter group to associate with the cluster string null no
db_parameter_group_name The name of the DB parameter group to associate with instances string null 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
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 disble. 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
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
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) null 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 defintions to add to the security group created map(any) {} no
security_group_tags Additional tags for the security group 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
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_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.

Packages

No packages published

Languages

  • HCL 100.0%