Resource: awsRdsCluster

Manages a RDS Aurora Cluster. To manage cluster instances that inherit configuration from the cluster (when not running the cluster in serverless engine mode), see the awsRdsClusterInstance resource. To manage non-Aurora databases (e.g., MySQL, PostgreSQL, SQL Server, etc.), see the awsDbInstance 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 applyImmediately flag to instruct the service to apply the change immediately (see documentation below).

\~> Note: using applyImmediately can result in a brief downtime as the server reboots. See the AWS Docs on RDS Maintenance for more information.

\~> Note: All arguments including the username and password will be stored in the raw state as plain-text. Read more about sensitive data in state.

\~> NOTE on RDS Clusters and RDS Cluster Role Associations: Terraform provides both a standalone RDS Cluster Role Association - (an association between an RDS Cluster and a single IAM Role) and an RDS Cluster resource with iamRoles attributes. Use one resource or the other to associate IAM Roles and RDS Clusters. Not doing so will cause a conflict of associations and will result in the association being overwritten.

Example Usage

Aurora MySQL 2.x (MySQL 5.7)

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.rdsCluster.RdsCluster(this, "default", {
  availabilityZones: ["us-west-2a", "us-west-2b", "us-west-2c"],
  backupRetentionPeriod: 5,
  clusterIdentifier: "aurora-cluster-demo",
  databaseName: "mydb",
  engine: "aurora-mysql",
  engineVersion: "5.7.mysql_aurora.2.03.2",
  masterPassword: "bar",
  masterUsername: "foo",
  preferredBackupWindow: "07:00-09:00",
});

Aurora MySQL 1.x (MySQL 5.6)

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.rdsCluster.RdsCluster(this, "default", {
  availabilityZones: ["us-west-2a", "us-west-2b", "us-west-2c"],
  backupRetentionPeriod: 5,
  clusterIdentifier: "aurora-cluster-demo",
  databaseName: "mydb",
  masterPassword: "bar",
  masterUsername: "foo",
  preferredBackupWindow: "07:00-09:00",
});

Aurora with PostgreSQL engine

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.rdsCluster.RdsCluster(this, "postgresql", {
  availabilityZones: ["us-west-2a", "us-west-2b", "us-west-2c"],
  backupRetentionPeriod: 5,
  clusterIdentifier: "aurora-cluster-demo",
  databaseName: "mydb",
  engine: "aurora-postgresql",
  masterPassword: "bar",
  masterUsername: "foo",
  preferredBackupWindow: "07:00-09:00",
});

Aurora Multi-Master Cluster

-> More information about Aurora Multi-Master Clusters can be found in the RDS User Guide.

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.rdsCluster.RdsCluster(this, "example", {
  clusterIdentifier: "example",
  dbSubnetGroupName: "${aws_db_subnet_group.example.name}",
  engineMode: "multimaster",
  masterPassword: "barbarbarbar",
  masterUsername: "foo",
  skipFinalSnapshot: true,
});

RDS Multi-AZ Cluster

-> More information about RDS Multi-AZ Clusters can be found in the RDS User Guide.

To create a Multi-AZ RDS cluster, you must additionally specify the engine, storageType, allocatedStorage, iops and dbClusterInstanceClass attributes.

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.rdsCluster.RdsCluster(this, "example", {
  allocatedStorage: 100,
  availabilityZones: ["us-west-2a", "us-west-2b", "us-west-2c"],
  clusterIdentifier: "example",
  dbClusterInstanceClass: "db.r6gd.xlarge",
  engine: "mysql",
  iops: 1000,
  masterPassword: "mustbeeightcharaters",
  masterUsername: "test",
  storageType: "io1",
});

RDS Serverless v2 Cluster

-> More information about RDS Serverless v2 Clusters can be found in the RDS User Guide.

To create a Serverless v2 RDS cluster, you must additionally specify the engineMode and serverlessv2ScalingConfiguration attributes. An awsRdsClusterInstance resource must also be added to the cluster with the instanceClass attribute specified.

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsRdsClusterExample = new aws.rdsCluster.RdsCluster(this, "example", {
  clusterIdentifier: "example",
  databaseName: "test",
  engine: "aurora-postgresql",
  engineMode: "provisioned",
  engineVersion: "13.6",
  masterPassword: "must_be_eight_characters",
  masterUsername: "test",
  serverlessv2ScalingConfiguration: {
    maxCapacity: 1,
    minCapacity: 0.5,
  },
});
const awsRdsClusterInstanceExample =
  new aws.rdsClusterInstance.RdsClusterInstance(this, "example_1", {
    clusterIdentifier: awsRdsClusterExample.id,
    engine: awsRdsClusterExample.engine,
    engineVersion: awsRdsClusterExample.engineVersion,
    instanceClass: "db.serverless",
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsRdsClusterInstanceExample.overrideLogicalId("example");

Global Cluster Restored From Snapshot

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const dataAwsDbClusterSnapshotExample =
  new aws.dataAwsDbClusterSnapshot.DataAwsDbClusterSnapshot(this, "example", {
    dbClusterIdentifier: "example-original-cluster",
    mostRecent: true,
  });
const awsRdsClusterExample = new aws.rdsCluster.RdsCluster(this, "example_1", {
  clusterIdentifier: "example",
  engine: "aurora",
  engineVersion: "5.6.mysql_aurora.1.22.4",
  snapshotIdentifier: dataAwsDbClusterSnapshotExample.id,
});
awsRdsClusterExample.addOverride("lifecycle", [
  {
    ignore_changes: ["${snapshot_identifier}", "${global_cluster_identifier}"],
  },
]);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsRdsClusterExample.overrideLogicalId("example");
const awsRdsGlobalClusterExample = new aws.rdsGlobalCluster.RdsGlobalCluster(
  this,
  "example_2",
  {
    forceDestroy: true,
    globalClusterIdentifier: "example",
    sourceDbClusterIdentifier: awsRdsClusterExample.arn,
  }
);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsRdsGlobalClusterExample.overrideLogicalId("example");

Argument Reference

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

The following arguments are supported:

allowMajorVersionUpgrade - (Optional) Enable to allow major engine version upgrades when changing engine versions. Defaults to false.
applyImmediately - (Optional) Specifies whether any cluster modifications are applied immediately, or during the next maintenance window. Default is false. See Amazon RDS Documentation for more information.
availabilityZones - (Optional) 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. We recommend specifying 3 AZs or using the lifecycle configuration block ignoreChanges argument if necessary. A maximum of 3 AZs can be configured.
backtrackWindow - (Optional) The target backtrack window, in seconds. Only available for aurora and auroraMysql engines currently. To disable backtracking, set this value to 0. Defaults to 0. Must be between 0 and 259200 (72 hours)
backupRetentionPeriod - (Optional) The days to retain backups for. Default 1
clusterIdentifierPrefix - (Optional, Forces new resource) Creates a unique cluster identifier beginning with the specified prefix. Conflicts with clusterIdentifier.
clusterIdentifier - (Optional, Forces new resources) The cluster identifier. If omitted, Terraform will assign a random, unique identifier.
copyTagsToSnapshot – (Optional, boolean) Copy all Cluster tags to snapshots. Default is false.
databaseName - (Optional) Name for an automatically created database on cluster creation. There are different naming restrictions per database engine: RDS Naming Constraints
dbClusterParameterGroupName - (Optional) A cluster parameter group to associate with the cluster.
dbInstanceParameterGroupName - (Optional) Instance parameter group to associate with all instances of the DB cluster. The dbInstanceParameterGroupName parameter is only valid in combination with the allowMajorVersionUpgrade parameter.
dbSubnetGroupName - (Optional) A DB subnet group to associate with this DB instance. NOTE: This must match the dbSubnetGroupName specified on every awsRdsClusterInstance in the cluster.
deletionProtection - (Optional) 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.
enableHttpEndpoint - (Optional) Enable HTTP endpoint (data API). Only valid when engineMode is set to serverless.
enabledCloudwatchLogsExports - (Optional) 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 (PostgreSQL).
engine - (Optional) The name of the database engine to be used for this DB cluster. Defaults to aurora. Valid Values: aurora, auroraMysql, auroraPostgresql, mysql, postgres. (Note that mysql and postgres are Multi-AZ RDS clusters).
engineMode - (Optional) The database engine mode. Valid values: global (only valid for Aurora MySQL 1.21 and earlier), multimaster, parallelquery, provisioned, serverless. Defaults to: provisioned. See the RDS User Guide for limitations when using serverless.
engineVersion - (Optional) The database engine version. Updating this argument results in an outage. See the Aurora MySQL and Aurora Postgres documentation for your configured engine to determine this value, or by running awsRdsDescribeDbEngineVersions. For example with Aurora MySQL 2, a potential value for this argument is 57MysqlAurora2032. The value can contain a partial version where supported by the API. The actual engine version used is returned in the attribute engineVersionActual, , see Attributes Reference below.
dbClusterInstanceClass - (Optional) 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. For the full list of DB instance classes and availability for your engine, see DB instance class in the Amazon RDS User Guide. (This setting is required to create a Multi-AZ DB cluster).
finalSnapshotIdentifier - (Optional) The name of your final DB snapshot when this DB cluster is deleted. If omitted, no final snapshot will be made.
globalClusterIdentifier - (Optional) The global cluster identifier specified on awsRdsGlobalCluster.
enableGlobalWriteForwarding - (Optional) Whether cluster should forward writes to an associated global cluster. Applied to secondary clusters to enable them to forward writes to an awsRdsGlobalCluster's primary cluster. See the Aurora Userguide documentation for more information.
iamDatabaseAuthenticationEnabled - (Optional) Specifies whether or not mappings of AWS Identity and Access Management (IAM) accounts to database accounts is enabled. Please see AWS Documentation for availability and limitations.
iamRoles - (Optional) A List of ARNs for the IAM roles to associate to the RDS Cluster.
kmsKeyId - (Optional) The ARN for the KMS encryption key. When specifying kmsKeyId, storageEncrypted needs to be set to true.
masterPassword - (Required unless a snapshotIdentifier or replicationSourceIdentifier is provided or unless a globalClusterIdentifier is provided when the cluster is the "secondary" cluster of a global database) Password for the master DB user. Note that this may show up in logs, and it will be stored in the state file. Please refer to the RDS Naming Constraints
masterUsername - (Required unless a snapshotIdentifier or replicationSourceIdentifier is provided or unless a globalClusterIdentifier is provided when the cluster is the "secondary" cluster of a global database) Username for the master DB user. Please refer to the RDS Naming Constraints. This argument does not support in-place updates and cannot be changed during a restore from snapshot.
port - (Optional) The port on which the DB accepts connections
preferredBackupWindow - (Optional) The daily time range during which automated backups are created if automated backups are enabled using the BackupRetentionPeriod parameter.Time in UTC. Default: A 30-minute window selected at random from an 8-hour block of time per regionE.g., 04:00-09:00
preferredMaintenanceWindow - (Optional) The weekly time range during which system maintenance can occur, in (UTC) e.g., wed:04:00-wed:04:30
replicationSourceIdentifier - (Optional) ARN of a source DB cluster or DB instance if this DB cluster is to be created as a Read Replica. If DB Cluster is part of a Global Cluster, use the lifecycle configuration block ignoreChanges argument to prevent Terraform from showing differences for this argument instead of configuring this value.
networkType - (Optional) The network type of the cluster. Valid values: ipv4, dual.
restoreToPointInTime - (Optional) Nested attribute for point in time restore. More details below.
scalingConfiguration - (Optional) Nested attribute with scaling properties. Only valid when engineMode is set to serverless. More details below.
serverlessv2ScalingConfiguration- (Optional) Nested attribute with scaling properties for ServerlessV2. Only valid when engineMode is set to provisioned. More details below.
skipFinalSnapshot - (Optional) Determines whether a final DB snapshot is created before the DB cluster is deleted. If true is specified, no DB snapshot is created. If false is specified, a DB snapshot is created before the DB cluster is deleted, using the value from finalSnapshotIdentifier. Default is false.
snapshotIdentifier - (Optional) 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. Conflicts with globalClusterIdentifier. Clusters cannot be restored from snapshot and joined to an existing global cluster in a single operation. See the AWS documentation or the Global Cluster Restored From Snapshot example for instructions on building a global cluster starting with a snapshot.
sourceRegion - (Optional) The source region for an encrypted replica DB cluster.
allocatedStorage - (Optional) 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).
storageType - (Optional) 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.
iops - (Optional) The amount of Provisioned IOPS (input/output operations per second) to be initially allocated for each DB instance in the Multi-AZ DB cluster. For information about valid Iops values, see Amazon RDS Provisioned IOPS storage to improve performance in the Amazon RDS User Guide. (This setting is required to create a Multi-AZ DB cluster). Must be a multiple between .5 and 50 of the storage amount for the DB cluster.
storageEncrypted - (Optional) Specifies whether the DB cluster is encrypted. The default is false for provisioned engineMode and true for serverless engineMode. When restoring an unencrypted snapshotIdentifier, the kmsKeyId argument must be provided to encrypt the restored cluster. Terraform will only perform drift detection if a configuration value is provided.
tags - (Optional) A map of tags to assign to the DB cluster. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.
vpcSecurityGroupIds - (Optional) List of VPC security groups to associate with the Cluster

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:

\~> NOTE: RDS Aurora Serverless does not support loading data from S3, so its not possible to directly use engineMode set to serverless with s3Import.

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.rdsCluster.RdsCluster(this, "db", {
  engine: "aurora",
  s3Import: {
    bucketName: "mybucket",
    bucketPrefix: "backups",
    ingestionRole: "arn:aws:iam::1234567890:role/role-xtrabackup-rds-restore",
    sourceEngine: "mysql",
    sourceEngineVersion: "5.6",
  },
});

bucketName - (Required) The bucket name where your backup is stored
bucketPrefix - (Optional) Can be blank, but is the path to your backup
ingestionRole - (Required) Role applied to load the data.
sourceEngine - (Required) Source engine for the backup
sourceEngineVersion - (Required) Version of the source engine used to make the backup

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

\~> NOTE: The DB cluster is created from the source DB cluster with the same configuration as the original DB cluster, except that the new DB cluster is created with the default DB security group. Thus, the following arguments should only be specified with the source DB cluster's respective values: databaseName, masterUsername, storageEncrypted, replicationSourceIdentifier, and sourceRegion.

Example:

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.rdsCluster.RdsCluster(this, "example-clone", {
  restoreToPointInTime: {
    restoreType: "copy-on-write",
    sourceClusterIdentifier: "example",
    useLatestRestorableTime: true,
  },
});

sourceClusterIdentifier - (Required) The identifier of the source database cluster from which to restore.
restoreType - (Optional) Type of restore to be performed. Valid options are fullCopy (default) and copyOnWrite.
useLatestRestorableTime - (Optional) Set to true to restore the database cluster to the latest restorable backup time. Defaults to false. Conflicts with restoreToTime.
restoreToTime - (Optional) Date and time in UTC format to restore the database cluster to. Conflicts with useLatestRestorableTime.

scaling_configuration Argument Reference

\~> NOTE: scalingConfiguration configuration is only valid when engineMode is set to serverless.

Example:

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.rdsCluster.RdsCluster(this, "example", {
  engineMode: "serverless",
  scalingConfiguration: {
    autoPause: true,
    maxCapacity: 256,
    minCapacity: 2,
    secondsUntilAutoPause: 300,
    timeoutAction: "ForceApplyCapacityChange",
  },
});

autoPause - (Optional) Whether to enable automatic pause. A DB cluster can be paused only when it's idle (it has no connections). If a DB cluster is paused for more than seven days, the DB cluster might be backed up with a snapshot. In this case, the DB cluster is restored when there is a request to connect to it. Defaults to true.
maxCapacity - (Optional) The maximum capacity for an Aurora DB cluster in serverless DB engine mode. The maximum capacity must be greater than or equal to the minimum capacity. Valid Aurora MySQL capacity values are 1, 2, 4, 8, 16, 32, 64, 128, 256. Valid Aurora PostgreSQL capacity values are (2, 4, 8, 16, 32, 64, 192, and 384). Defaults to 16.
minCapacity - (Optional) The minimum capacity for an Aurora DB cluster in serverless DB engine mode. The minimum capacity must be lesser than or equal to the maximum capacity. Valid Aurora MySQL capacity values are 1, 2, 4, 8, 16, 32, 64, 128, 256. Valid Aurora PostgreSQL capacity values are (2, 4, 8, 16, 32, 64, 192, and 384). Defaults to 1.
secondsUntilAutoPause - (Optional) The time, in seconds, before an Aurora DB cluster in serverless mode is paused. Valid values are 300 through 86400. Defaults to 300.
timeoutAction - (Optional) The action to take when the timeout is reached. Valid values: forceApplyCapacityChange, rollbackCapacityChange. Defaults to rollbackCapacityChange. See documentation.

serverlessv2_scaling_configuration Argument Reference

\~> NOTE: serverlessv2_scaling_configuration configuration is only valid when engine_mode is set to provisioned

Example:

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.rdsCluster.RdsCluster(this, "example", {
  serverlessv2ScalingConfiguration: {
    maxCapacity: 128,
    minCapacity: 0.5,
  },
});

maxCapacity - (Required) The maximum capacity for an Aurora DB cluster in provisioned DB engine mode. The maximum capacity must be greater than or equal to the minimum capacity. Valid capacity values are in a range of 05 up to 128 in steps of 05.
minCapacity - (Required) The minimum capacity for an Aurora DB cluster in provisioned DB engine mode. The minimum capacity must be lesser than or equal to the maximum capacity. Valid capacity values are in a range of 05 up to 128 in steps of 05.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

arn - Amazon Resource Name (ARN) of cluster
id - The RDS Cluster Identifier
clusterIdentifier - The RDS Cluster Identifier
clusterResourceId - The RDS Cluster Resource ID
clusterMembers – List of RDS Instances that are a part of this cluster
availabilityZones - The availability zone of the instance
backupRetentionPeriod - The backup retention period
preferredBackupWindow - The daily time range during which the backups happen
preferredMaintenanceWindow - The maintenance window
endpoint - The DNS address of the RDS instance
readerEndpoint - A read-only endpoint for the Aurora cluster, automatically load-balanced across replicas
engine - The database engine
engineVersionActual - The running version of the database.
databaseName - The database name
port - The database port
masterUsername - The master username for the database
storageEncrypted - Specifies whether the DB cluster is encrypted
replicationSourceIdentifier - ARN of the source DB cluster or DB instance if this DB cluster is created as a Read Replica.
hostedZoneId - The Route53 Hosted Zone ID of the endpoint
tagsAll - A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.

Timeouts

Configuration options:

create - (Default 120M)
update - (Default 120M)
delete - (Default 120M) any cleanup task during the destroying process.

Import

RDS Clusters can be imported using the clusterIdentifier, e.g.,

$ terraform import aws_rds_cluster.aurora_cluster aurora-prod-cluster