Resource: aws_rds_cluster

Manages a RDS Aurora Cluster or a RDS Multi-AZ DB Cluster. To manage cluster instances that inherit configuration from the cluster (when not running the cluster in serverless engine mode), see the aws_rds_cluster_instance resource. To manage non-Aurora DB instances (e.g., MySQL, PostgreSQL, SQL Server, etc.), see the aws_db_instance resource.

For information on the difference between the available Aurora MySQL engines see Comparison between Aurora MySQL 1 and Aurora MySQL 2 in the Amazon RDS User Guide.

Changes to an RDS Cluster can occur when you manually change a parameter, such as port, and are reflected in the next maintenance window. Because of this, Terraform may report a difference in its planning phase because a modification has not yet taken place. You can use the apply_immediately flag to instruct the service to apply the change immediately (see documentation below).

Example Usage

Aurora MySQL 2.x (MySQL 5.7)

resource "aws_rds_cluster" "default" {
  cluster_identifier      = "aurora-cluster-demo"
  engine                  = "aurora-mysql"
  engine_version          = "5.7.mysql_aurora.2.03.2"
  availability_zones      = ["us-west-2a", "us-west-2b", "us-west-2c"]
  database_name           = "mydb"
  master_username         = "foo"
  master_password         = "bar"
  backup_retention_period = 5
  preferred_backup_window = "07:00-09:00"
}

Aurora MySQL 1.x (MySQL 5.6)

resource "aws_rds_cluster" "default" {
  cluster_identifier      = "aurora-cluster-demo"
  availability_zones      = ["us-west-2a", "us-west-2b", "us-west-2c"]
  database_name           = "mydb"
  master_username         = "foo"
  master_password         = "bar"
  backup_retention_period = 5
  preferred_backup_window = "07:00-09:00"
}

Aurora with PostgreSQL engine

resource "aws_rds_cluster" "postgresql" {
  cluster_identifier      = "aurora-cluster-demo"
  engine                  = "aurora-postgresql"
  availability_zones      = ["us-west-2a", "us-west-2b", "us-west-2c"]
  database_name           = "mydb"
  master_username         = "foo"
  master_password         = "bar"
  backup_retention_period = 5
  preferred_backup_window = "07:00-09:00"
}

RDS Multi-AZ Cluster

To create a Multi-AZ RDS cluster, you must additionally specify the engine, storage_type, allocated_storage, iops and db_cluster_instance_class attributes.

resource "aws_rds_cluster" "example" {
  cluster_identifier        = "example"
  availability_zones        = ["us-west-2a", "us-west-2b", "us-west-2c"]
  engine                    = "mysql"
  db_cluster_instance_class = "db.r6gd.xlarge"
  storage_type              = "io1"
  allocated_storage         = 100
  iops                      = 1000
  master_username           = "test"
  master_password           = "mustbeeightcharaters"
}

RDS Serverless v2 Cluster

To create a Serverless v2 RDS cluster, you must additionally specify the engine_mode and serverlessv2_scaling_configuration attributes. An aws_rds_cluster_instance resource must also be added to the cluster with the instance_class attribute specified.

resource "aws_rds_cluster" "example" {
  cluster_identifier = "example"
  engine             = "aurora-postgresql"
  engine_mode        = "provisioned"
  engine_version     = "13.6"
  database_name      = "test"
  master_username    = "test"
  master_password    = "must_be_eight_characters"
  storage_encrypted  = true

  serverlessv2_scaling_configuration {
    max_capacity = 1.0
    min_capacity = 0.5
  }
}

resource "aws_rds_cluster_instance" "example" {
  cluster_identifier = aws_rds_cluster.example.id
  instance_class     = "db.serverless"
  engine             = aws_rds_cluster.example.engine
  engine_version     = aws_rds_cluster.example.engine_version
}

RDS/Aurora Managed Master Passwords via Secrets Manager, default KMS Key

You can specify the manage_master_user_password attribute to enable managing the master password with Secrets Manager. You can also update an existing cluster to use Secrets Manager by specify the manage_master_user_password attribute and removing the master_password attribute (removal is required).

resource "aws_rds_cluster" "test" {
  cluster_identifier          = "example"
  database_name               = "test"
  manage_master_user_password = true
  master_username             = "test"
}

RDS/Aurora Managed Master Passwords via Secrets Manager, specific KMS Key

You can specify the master_user_secret_kms_key_id attribute to specify a specific KMS Key.

resource "aws_kms_key" "example" {
  description = "Example KMS Key"
}

resource "aws_rds_cluster" "test" {
  cluster_identifier            = "example"
  database_name                 = "test"
  manage_master_user_password   = true
  master_username               = "test"
  master_user_secret_kms_key_id = aws_kms_key.example.key_id
}

Global Cluster Restored From Snapshot

data "aws_db_cluster_snapshot" "example" {
  db_cluster_identifier = "example-original-cluster"
  most_recent           = true
}

resource "aws_rds_cluster" "example" {
  # Because the global cluster is sourced from this cluster, the initial 
  # engine and engine_version values are defined here and automatically
  # inherited by the global cluster.
  engine         = "aurora"
  engine_version = "5.6.mysql_aurora.1.22.4"

  cluster_identifier  = "example"
  snapshot_identifier = data.aws_db_cluster_snapshot.example.id

  lifecycle {
    ignore_changes = [snapshot_identifier, global_cluster_identifier]
  }
}

resource "aws_rds_global_cluster" "example" {
  global_cluster_identifier    = "example"
  source_db_cluster_identifier = aws_rds_cluster.example.arn
  force_destroy                = true
}

Argument Reference

For more detailed documentation about each argument, refer to the AWS official documentation :

This argument supports the following arguments:

S3 Import Options

Full details on the core parameters and impacts are in the API Docs: RestoreDBClusterFromS3. Requires that the S3 bucket be in the same region as the RDS cluster you're trying to create. Sample:

resource "aws_rds_cluster" "db" {
  engine = "aurora"

  s3_import {
    source_engine         = "mysql"
    source_engine_version = "5.6"
    bucket_name           = "mybucket"
    bucket_prefix         = "backups"
    ingestion_role        = "arn:aws:iam::1234567890:role/role-xtrabackup-rds-restore"
  }
}

This will not recreate the resource if the S3 object changes in some way. It's only used to initialize the database. This only works currently with the aurora engine. See AWS for currently supported engines and options. See Aurora S3 Migration Docs.

restore_to_point_in_time Argument Reference

Example:

resource "aws_rds_cluster" "example-clone" {
  # ... other configuration ...

  restore_to_point_in_time {
    source_cluster_identifier  = "example"
    restore_type               = "copy-on-write"
    use_latest_restorable_time = true
  }
}

scaling_configuration Argument Reference

Example:

resource "aws_rds_cluster" "example" {
  # ... other configuration ...

  engine_mode = "serverless"

  scaling_configuration {
    auto_pause               = true
    max_capacity             = 256
    min_capacity             = 2
    seconds_until_auto_pause = 300
    timeout_action           = "ForceApplyCapacityChange"
  }
}

serverlessv2_scaling_configuration Argument Reference

Example:

resource "aws_rds_cluster" "example" {
  # ... other configuration ...

  serverlessv2_scaling_configuration {
    max_capacity = 128.0
    min_capacity = 0.5
  }
}

Attribute Reference

This resource exports the following attributes in addition to the arguments above:

master_user_secret

The master_user_secret configuration block supports the following attributes:

Timeouts

Configuration options:

Import

In Terraform v1.5.0 and later, use an import block to import RDS Clusters using the cluster_identifier. For example:

import {
  to = aws_rds_cluster.aurora_cluster
  id = "aurora-prod-cluster"
}

Using terraform import, import RDS Clusters using the cluster_identifier. For example:

% terraform import aws_rds_cluster.aurora_cluster aurora-prod-cluster