README.yaml

name: terraform-aws-rds-cluster

tags:
  - aws
  - terraform
  - terraform-modules
  - databases
  - rds
  - rds-database
  - aurora
  - mysql
  - cluster

categories:
  - terraform-modules/databases

license: APACHE2

github_repo: cloudposse/terraform-aws-rds-cluster

badges:
  - name: Latest Release
    image: https://img.shields.io/github/release/cloudposse/terraform-aws-rds-cluster.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-rds-cluster/releases/latest
  - name: Last Updated
    image: https://img.shields.io/github/last-commit/cloudposse/terraform-aws-rds-cluster.svg?style=for-the-badge
    url: https://github.com/cloudposse/terraform-aws-rds-cluster/commits
  - name: Slack Community
    image: https://slack.cloudposse.com/for-the-badge.svg
    url: https://slack.cloudposse.com

# List any related terraform modules that this module may be used with or that this module depends on.
related:
  - name: terraform-aws-rds
    description: Terraform module to provision AWS RDS instances
    url: https://github.com/cloudposse/terraform-aws-rds
  - name: terraform-aws-rds-cloudwatch-sns-alarms
    description: Terraform module that configures important RDS alerts using CloudWatch and sends them to an SNS topic
    url: https://github.com/cloudposse/terraform-aws-rds-cloudwatch-sns-alarms

description: |-
  Terraform module to provision an [`RDS Aurora`](https://aws.amazon.com/rds/aurora) cluster for MySQL or Postgres.

  Supports [Amazon Aurora Serverless](https://aws.amazon.com/rds/aurora/serverless/).

usage: |2-

  For a complete example, see [examples/complete](examples/complete).

  For automated tests of the complete example using [bats](https://github.com/bats-core/bats-core) and [Terratest](https://github.com/gruntwork-io/terratest) (which tests and deploys the example on AWS), see [test](test).

  [Basic example](examples/basic)

  ```hcl
  module "rds_cluster_aurora_postgres" {
    source = "cloudposse/rds-cluster/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"

    name            = "postgres"
    engine          = "aurora-postgresql"
    cluster_family  = "aurora-postgresql9.6"
    # 1 writer, 1 reader
    cluster_size    = 2
    # 1 writer, 3 reader
    # cluster_size    = 4
    # 1 writer, 5 reader
    # cluster_size    = 6
    namespace       = "eg"
    stage           = "dev"
    admin_user      = "admin1"
    admin_password  = "Test123456789"
    db_name         = "dbname"
    db_port         = 5432
    instance_type   = "db.r4.large"
    vpc_id          = "vpc-xxxxxxxx"
    security_groups = ["sg-xxxxxxxx"]
    subnets         = ["subnet-xxxxxxxx", "subnet-xxxxxxxx"]
    zone_id         = "Zxxxxxxxx"
  }
  ```


  [Serverless Aurora MySQL 5.6](examples/serverless_mysql)

  ```hcl
  module "rds_cluster_aurora_mysql_serverless" {
    source = "cloudposse/rds-cluster/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"
    namespace            = "eg"
    stage                = "dev"
    name                 = "db"
    engine               = "aurora"
    engine_mode          = "serverless"
    cluster_family       = "aurora5.6"
    cluster_size         = 0
    admin_user           = "admin1"
    admin_password       = "Test123456789"
    db_name              = "dbname"
    db_port              = 3306
    instance_type        = "db.t2.small"
    vpc_id               = "vpc-xxxxxxxx"
    security_groups      = ["sg-xxxxxxxx"]
    subnets              = ["subnet-xxxxxxxx", "subnet-xxxxxxxx"]
    zone_id              = "Zxxxxxxxx"
    enable_http_endpoint = true

    scaling_configuration = [
      {
        auto_pause               = true
        max_capacity             = 256
        min_capacity             = 2
        seconds_until_auto_pause = 300
      }
    ]
  }
  ```

  [Serverless Aurora 2.07.1 MySQL 5.7](examples/serverless_mysql57)

  ```hcl
  module "rds_cluster_aurora_mysql_serverless" {
    source = "cloudposse/rds-cluster/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"
    namespace            = "eg"
    stage                = "dev"
    name                 = "db"
    engine               = "aurora-mysql"
    engine_mode          = "serverless"
    engine_version       = "5.7.mysql_aurora.2.07.1"
    cluster_family       = "aurora-mysql5.7"
    cluster_size         = 0
    admin_user           = "admin1"
    admin_password       = "Test123456789"
    db_name              = "dbname"
    db_port              = 3306
    vpc_id               = "vpc-xxxxxxxx"
    security_groups      = ["sg-xxxxxxxx"]
    subnets              = ["subnet-xxxxxxxx", "subnet-xxxxxxxx"]
    zone_id              = "Zxxxxxxxx"
    enable_http_endpoint = true

    scaling_configuration = [
      {
        auto_pause               = true
        max_capacity             = 16
        min_capacity             = 1
        seconds_until_auto_pause = 300
        timeout_action           = "ForceApplyCapacityChange"
      }
    ]
  }
  ```

  [With cluster parameters](examples/with_cluster_parameters)

  ```hcl
  module "rds_cluster_aurora_mysql" {
    source = "cloudposse/rds-cluster/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"
    engine          = "aurora"
    cluster_family  = "aurora-mysql5.7"
    cluster_size    = 2
    namespace       = "eg"
    stage           = "dev"
    name            = "db"
    admin_user      = "admin1"
    admin_password  = "Test123456789"
    db_name         = "dbname"
    instance_type   = "db.t2.small"
    vpc_id          = "vpc-xxxxxxx"
    security_groups = ["sg-xxxxxxxx"]
    subnets         = ["subnet-xxxxxxxx", "subnet-xxxxxxxx"]
    zone_id         = "Zxxxxxxxx"

    cluster_parameters = [
      {
        name  = "character_set_client"
        value = "utf8"
      },
      {
        name  = "character_set_connection"
        value = "utf8"
      },
      {
        name  = "character_set_database"
        value = "utf8"
      },
      {
        name  = "character_set_results"
        value = "utf8"
      },
      {
        name  = "character_set_server"
        value = "utf8"
      },
      {
        name  = "collation_connection"
        value = "utf8_bin"
      },
      {
        name  = "collation_server"
        value = "utf8_bin"
      },
      {
        name         = "lower_case_table_names"
        value        = "1"
        apply_method = "pending-reboot"
      },
      {
        name         = "skip-character-set-client-handshake"
        value        = "1"
        apply_method = "pending-reboot"
      }
    ]
  }
  ```

  [With enhanced monitoring](examples/enhanced_monitoring)

  ```hcl
  # create IAM role for monitoring
  resource "aws_iam_role" "enhanced_monitoring" {
    name               = "rds-cluster-example-1"
    assume_role_policy = data.aws_iam_policy_document.enhanced_monitoring.json
  }

  # Attach Amazon's managed policy for RDS enhanced monitoring
  resource "aws_iam_role_policy_attachment" "enhanced_monitoring" {
    role       = aws_iam_role.enhanced_monitoring.name
    policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonRDSEnhancedMonitoringRole"
  }

  # allow rds to assume this role
  data "aws_iam_policy_document" "enhanced_monitoring" {
    statement {
        actions = [
        "sts:AssumeRole",
      ]

      effect = "Allow"

      principals {
        type        = "Service"
        identifiers = ["monitoring.rds.amazonaws.com"]
      }
    }
  }

  module "rds_cluster_aurora_postgres" {
    source = "cloudposse/rds-cluster/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version     = "x.x.x"
    engine          = "aurora-postgresql"
    cluster_family  = "aurora-postgresql9.6"
    cluster_size    = 2
    namespace       = "eg"
    stage           = "dev"
    name            = "db"
    admin_user      = "admin1"
    admin_password  = "Test123456789"
    db_name         = "dbname"
    db_port         = 5432
    instance_type   = "db.r4.large"
    vpc_id          = "vpc-xxxxxxx"
    security_groups = ["sg-xxxxxxxx"]
    subnets         = ["subnet-xxxxxxxx", "subnet-xxxxxxxx"]
    zone_id         = "Zxxxxxxxx"

    # enable monitoring every 30 seconds
    rds_monitoring_interval = 30

    # reference iam role created above
    rds_monitoring_role_arn = aws_iam_role.enhanced_monitoring.arn
  }
  ```

examples: |-
  Review the [complete example](examples/complete) to see how to use this module.

include:
  - docs/targets.md
  - docs/terraform.md

contributors: []