DOCSEARCHbyAlgolia
Submit Docs

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

repository·master·Indexed 19 days ago

https://github.com/terraform-aws-modules/terraform-aws-rds-aurora

An AWS RDS Aurora Terraform module that simplifies the deployment of Aurora clusters. It supports features including autoscaling, global clusters, serverless (v1/v2), heterogeneous instance configurations, Aurora DSQL, and PostgreSQL Limitless clusters.

Tokens
22.6K
Snippets
31
Records
65
Agent score
64%

What's inside terraform-aws-modules/terraform-aws-rds-aurora

  1. Architecture of the Aurora Global Cluster Example

    master

    The global cluster example is composed of the following components:

    Modules

    • aurora_primary: The main Aurora cluster module (pointing to the root module).
    • aurora_secondary: The secondary Aurora cluster module (pointing to the root module).
    • primary_vpc: VPC module from terraform-aws-modules/vpc/aws (~> 6.0).
    • secondary_vpc: VPC module from terraform-aws-modules/vpc/aws (~> 6.0).

    Resources and Data Sources

    • Global Cluster: aws_rds_global_cluster.this links the primary and secondary clusters.
    • Encryption: aws_kms_key.primary and aws_kms_key.secondary provide KMS keys for each region.
    • Security: random_password.master generates the master password.
    • Network/Identity: Uses aws_availability_zones for both regions and aws_caller_identity for account context.
    • IAM: aws_iam_policy_document.rds defines policies for RDS access.

  2. What is the module wrapper pattern?

    master

    The wrappers directory provides a single module wrapper pattern designed for scenarios where native Terraform for_each is not feasible, such as when using Terragrunt. This pattern allows you to manage multiple instances of the RDS Aurora module within a single configuration file, avoiding the need to duplicate terragrunt.hcl files for every individual resource.

    Note that this wrapper does not add any new functionality; it simply provides a way to pass a map of configurations to the underlying root module.

  3. Configure cluster instances using the `instances` map

    master

    In v6.x, you no longer use replica_count, instances_parameters, or instance_type_replica. Instead, you define all instance configurations within the instances map. This allows you to specify unique attributes for every instance in the cluster.

    Note for Migration: Because the module switched from count to for_each, you must perform a Terraform state move for each instance to avoid recreation. You must map the old index (e.g., [0]) to the new key defined in your instances map.

  4. Configure Aurora Cluster Instance Types

    master

    The module provides several ways to configure instances within a cluster:

    1. Homogenous Cluster: All instances share the same configuration. Define cluster_instance_class and a map of instances where each entry is an empty object {}.
    2. Heterogeneous Cluster: Instances have different configurations. Use the instances map to specify unique instance_class, identifier, publicly_accessible, or promotion_tier for each member.
    3. Autoscaling: Enable autoscaling_enabled and set autoscaling_min_capacity and autoscaling_max_capacity. Note that autoscaling uses the cluster_instance_class for the new instances.
    # Heterogeneous cluster example
instances = {
  one = {
    instance_class      = "db.r8g.2xlarge"
    publicly_accessible = true
  }
  two = {
    identifier     = "static-member-1"
    instance_class = "db.r8g.2xlarge"
  }
  three = {
    identifier     = "excluded-member-1"
    instance_class = "db.r8g.large"
    promotion_tier = 15
  }
}

autoscaling_enabled      = true
autoscaling_min_capacity = 1
autoscaling_max_capacity = 5

  5. Understand the dsql module wrapper pattern

    master
    The wrappers/dsql directory implements a single module wrapper pattern. This pattern is designed for scenarios where using native Terraform for_each is not feasible, such as when using Terragrunt. It allows you to manage multiple instances of the underlying modules/dsql module within a single configuration file by defining a map of items. This avoids the need to duplicate terragrunt.hcl files for every individual resource instance.

  6. Perform Terraform state moves for v5.x to v6.x migration

    master

    When upgrading from v5.x to v6.x, you must move existing resources in your Terraform state to match the new resource addressing used by the module. This prevents Terraform from destroying and recreating your Aurora instances and autoscaling resources.

    Instance State Migration

    You must perform a terraform state mv for every instance in your cluster. Map the old list index (e.g., [0], [1]) to the new key used in your instances map (e.g., ["1"], ["2"]).

    Pattern: terraform state mv 'module.<name>.aws_rds_cluster_instance.this[<old_index>]' 'module.<name>.aws_rds_cluster_instance.this["<new_key>"]'

    Autoscaling State Migration

    Move the autoscaling policy and target resources as follows:

    1. Move the policy: terraform state mv 'module.<name>.aws_appautoscaling_policy.autoscaling_read_replica_count[0]' 'module.<name>.aws_appautoscaling_policy.this[0]'
    2. Move the target: terraform state mv 'module.<name>.aws_appautoscaling_target.read_replica_count[0]' 'module.<name>.aws_appautoscaling_target.this[0]'
    # Example for a module named 'aurora' with 2 instances
terraform state mv 'module.aurora.aws_rds_cluster_instance.this[0]' 'module.aurora.aws_rds_cluster_instance.this["1"]'
terraform state mv 'module.aurora.aws_rds_cluster_instance.this[1]' 'module.aurora.aws_rds_cluster_instance.this["2"]'

# Move autoscaling resources
terraform state mv 'module.aurora.aws_appautoscaling_policy.autoscaling_read_replica_count[0]' 'module.aurora.aws_appautoscaling_policy.this[0]'
terraform state mv 'module.aurora.aws_appautoscaling_target.read_replica_count[0]' 'module.aurora.aws_appautoscaling_target.this[0]'

  7. Deploy an Aurora cluster with autoscaling

    master

    This example demonstrates how to configure an Aurora cluster with autoscaling enabled using the terraform-aws-modules/terraform-aws-rds-aurora module. It integrates with a VPC and uses the aws_availability_zones data source to distribute resources across available zones.

    Requirements

    • Terraform: >= 1.11.1
    • AWS Provider: >= 6.54

    Deployment Steps

    To deploy the autoscaling configuration, execute the following commands in your terminal:

    $ terraform init
$ terraform plan
$ terraform apply
    WARNING

    This example creates resources that incur costs. Run terraform destroy to clean up resources when they are no longer needed.

  8. Deploy a PostgreSQL Aurora Global Cluster

    master

    This example demonstrates how to configure a PostgreSQL Aurora global cluster spanning two different VPCs (primary and secondary). It utilizes the terraform-aws-modules/rds-aurora module twice: once for the primary cluster and once for the secondary cluster, linked via an aws_rds_global_cluster resource.

    Requirements

    • terraform: >= 1.11.1
    • aws: >= 6.54
    • random: >= 3.5

    Deployment Steps

    To deploy this architecture, execute the following commands in the example directory:

    terraform init
terraform plan
terraform apply
    WARNING

    This configuration creates resources that incur costs. Use terraform destroy to clean up resources when they are no longer needed.

    $ terraform init
$ terraform plan
$ terraform apply

  9. Use the module wrapper with Terraform

    master

    When calling the wrapper directly in Terraform, use the module block. You must provide a defaults map for shared settings and an items map where each key defines a specific module instance using the standard RDS Aurora module arguments.

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

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

  items = {
    my-item = {
      # can be any argument supported by the module
    }
    my-second-item = {
      # can be any argument supported by the module
    }
  }
}

  10. Migrate variable structures to v10.x

    master

    In v10.x, several configuration blocks have been consolidated into single objects. To upgrade, move your existing top-level variables into these new nested structures:

    Shard Group (Limitless Databases)

    Move create_shard_group, compute_redundancy, db_shard_group_identifier, max_acu, min_acu, publicly_accessible, shard_group_tags, and shard_group_timeouts into a shard_group object. Set shard_group to null to disable.

    Cluster Activity Stream

    Move create_db_cluster_activity_stream, db_cluster_activity_stream_kms_key_id, and db_cluster_activity_stream_mode into a cluster_activity_stream object. Set cluster_activity_stream to null to disable.

    Cluster Parameter Group

    Move create_db_cluster_parameter_group, db_cluster_parameter_group_name, db_cluster_parameter_group_use_name_prefix, db_cluster_parameter_group_description, db_cluster_parameter_group_family, and db_cluster_parameter_group_parameters into a cluster_parameter_group object. Set cluster_parameter_group to null to disable.

    DB Parameter Group

    Move create_db_parameter_group, db_parameter_group_name, db_parameter_group_use_name_prefix, db_parameter_group_description, db_parameter_group_family, and db_parameter_group_parameters into a db_parameter_group object. Set db_parameter_group to null to disable.

  12. Deploy a PostgreSQL Aurora cluster

    master

    This example demonstrates how to configure and deploy an AWS Aurora PostgreSQL cluster using the terraform-aws-modules/terraform-aws-rds-aurora module. The configuration integrates with the VPC module for networking and the KMS module for encryption.

    Requirements

    NameVersion
    terraform>= 1.11.1
    aws>= 6.54

    Providers

    NameVersion
    aws>= 6.54

    Modules Used

    NameSourceVersion
    aurora../../n/a
    kmsterraform-aws-modules/kms/aws~> 4.0
    vpcterraform-aws-modules/vpc/aws~> 6.0

    Deployment Steps

    To deploy the cluster, execute the following commands in your terminal:

    $ terraform init
$ terraform plan
$ terraform apply
    WARNING

    This example creates resources that incur AWS costs. Run terraform destroy to clean up the resources when they are no longer needed.