Resource: awsRdsGlobalCluster
Manages an RDS Global Cluster, which is an Aurora global database spread across multiple regions. The global database contains a single primary cluster with read-write capability, and a read-only secondary cluster that receives data from the primary cluster through high-speed replication performed by the Aurora storage subsystem.
More information about Aurora global databases can be found in the Aurora User Guide.
Example Usage
New MySQL Global Cluster
/*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 awsRdsGlobalClusterExample = new aws.rdsGlobalCluster.RdsGlobalCluster(
this,
"example",
{
databaseName: "example_db",
engine: "aurora",
engineVersion: "5.6.mysql_aurora.1.22.2",
globalClusterIdentifier: "global-test",
}
);
const awsRdsClusterPrimary = new aws.rdsCluster.RdsCluster(this, "primary", {
clusterIdentifier: "test-primary-cluster",
databaseName: "example_db",
dbSubnetGroupName: "default",
engine: awsRdsGlobalClusterExample.engine,
engineVersion: awsRdsGlobalClusterExample.engineVersion,
globalClusterIdentifier: awsRdsGlobalClusterExample.id,
masterPassword: "somepass123",
masterUsername: "username",
provider: "${aws.primary}",
});
const awsRdsClusterInstancePrimary =
new aws.rdsClusterInstance.RdsClusterInstance(this, "primary_2", {
clusterIdentifier: awsRdsClusterPrimary.id,
dbSubnetGroupName: "default",
engine: awsRdsGlobalClusterExample.engine,
engineVersion: awsRdsGlobalClusterExample.engineVersion,
identifier: "test-primary-cluster-instance",
instanceClass: "db.r4.large",
provider: "${aws.primary}",
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsRdsClusterInstancePrimary.overrideLogicalId("primary");
const awsRdsClusterSecondary = new aws.rdsCluster.RdsCluster(
this,
"secondary",
{
clusterIdentifier: "test-secondary-cluster",
dbSubnetGroupName: "default",
depends_on: [`\${${awsRdsClusterInstancePrimary.fqn}}`],
engine: awsRdsGlobalClusterExample.engine,
engineVersion: awsRdsGlobalClusterExample.engineVersion,
globalClusterIdentifier: awsRdsGlobalClusterExample.id,
provider: "${aws.secondary}",
}
);
const awsRdsClusterInstanceSecondary =
new aws.rdsClusterInstance.RdsClusterInstance(this, "secondary_4", {
clusterIdentifier: awsRdsClusterSecondary.id,
dbSubnetGroupName: "default",
engine: awsRdsGlobalClusterExample.engine,
engineVersion: awsRdsGlobalClusterExample.engineVersion,
identifier: "test-secondary-cluster-instance",
instanceClass: "db.r4.large",
provider: "${aws.secondary}",
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsRdsClusterInstanceSecondary.overrideLogicalId("secondary");
New PostgreSQL Global Cluster
/*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 awsPrimary = new aws.provider.AwsProvider(this, "aws", {
alias: "primary",
region: "us-east-2",
});
const awsSecondary = new aws.provider.AwsProvider(this, "aws_1", {
alias: "secondary",
region: "us-east-1",
});
const awsRdsGlobalClusterExample = new aws.rdsGlobalCluster.RdsGlobalCluster(
this,
"example",
{
databaseName: "example_db",
engine: "aurora-postgresql",
engineVersion: "11.9",
globalClusterIdentifier: "global-test",
}
);
const awsRdsClusterPrimary = new aws.rdsCluster.RdsCluster(this, "primary", {
clusterIdentifier: "test-primary-cluster",
databaseName: "example_db",
dbSubnetGroupName: "default",
engine: awsRdsGlobalClusterExample.engine,
engineVersion: awsRdsGlobalClusterExample.engineVersion,
globalClusterIdentifier: awsRdsGlobalClusterExample.id,
masterPassword: "somepass123",
masterUsername: "username",
provider: `\${${awsPrimary.fqn}}`,
});
const awsRdsClusterInstancePrimary =
new aws.rdsClusterInstance.RdsClusterInstance(this, "primary_4", {
clusterIdentifier: awsRdsClusterPrimary.id,
dbSubnetGroupName: "default",
engine: awsRdsGlobalClusterExample.engine,
engineVersion: awsRdsGlobalClusterExample.engineVersion,
identifier: "test-primary-cluster-instance",
instanceClass: "db.r4.large",
provider: `\${${awsPrimary.fqn}}`,
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsRdsClusterInstancePrimary.overrideLogicalId("primary");
const awsRdsClusterSecondary = new aws.rdsCluster.RdsCluster(
this,
"secondary",
{
clusterIdentifier: "test-secondary-cluster",
dbSubnetGroupName: "default",
depends_on: [`\${${awsRdsClusterInstancePrimary.fqn}}`],
engine: awsRdsGlobalClusterExample.engine,
engineVersion: awsRdsGlobalClusterExample.engineVersion,
globalClusterIdentifier: awsRdsGlobalClusterExample.id,
provider: `\${${awsSecondary.fqn}}`,
skipFinalSnapshot: true,
}
);
const awsRdsClusterInstanceSecondary =
new aws.rdsClusterInstance.RdsClusterInstance(this, "secondary_6", {
clusterIdentifier: awsRdsClusterSecondary.id,
dbSubnetGroupName: "default",
engine: awsRdsGlobalClusterExample.engine,
engineVersion: awsRdsGlobalClusterExample.engineVersion,
identifier: "test-secondary-cluster-instance",
instanceClass: "db.r4.large",
provider: `\${${awsSecondary.fqn}}`,
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsRdsClusterInstanceSecondary.overrideLogicalId("secondary");
New Global Cluster From Existing DB Cluster
/*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", {});
awsRdsClusterExample.addOverride("lifecycle", [
{
ignore_changes: ["${global_cluster_identifier}"],
},
]);
const awsRdsGlobalClusterExample = new aws.rdsGlobalCluster.RdsGlobalCluster(
this,
"example_1",
{
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");
Upgrading Engine Versions
When you upgrade the version of an awsRdsGlobalCluster
, Terraform will attempt to in-place upgrade the engine versions of all associated clusters. Since the awsRdsCluster
resource is being updated through the awsRdsGlobalCluster
, you are likely to get an error (providerProducedInconsistentFinalPlan
). To avoid this, use the lifecycle
ignoreChanges
meta argument as shown below on the awsRdsCluster
.
/*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 awsRdsGlobalClusterExample = new aws.rdsGlobalCluster.RdsGlobalCluster(
this,
"example",
{
engine: "aurora-mysql",
engineVersion: "5.7.mysql_aurora.2.07.5",
globalClusterIdentifier: "kyivkharkiv",
}
);
const awsRdsClusterPrimary = new aws.rdsCluster.RdsCluster(this, "primary", {
allowMajorVersionUpgrade: true,
applyImmediately: true,
clusterIdentifier: "odessadnipro",
databaseName: "totoro",
engine: awsRdsGlobalClusterExample.engine,
engineVersion: awsRdsGlobalClusterExample.engineVersion,
globalClusterIdentifier: awsRdsGlobalClusterExample.id,
masterPassword: "satsukimae",
masterUsername: "maesatsuki",
skipFinalSnapshot: true,
});
awsRdsClusterPrimary.addOverride("lifecycle", [
{
ignore_changes: ["${engine_version}"],
},
]);
const awsRdsClusterInstancePrimary =
new aws.rdsClusterInstance.RdsClusterInstance(this, "primary_2", {
applyImmediately: true,
clusterIdentifier: awsRdsClusterPrimary.id,
engine: awsRdsClusterPrimary.engine,
engineVersion: awsRdsClusterPrimary.engineVersion,
identifier: "donetsklviv",
instanceClass: "db.r4.large",
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsRdsClusterInstancePrimary.overrideLogicalId("primary");
Argument Reference
The following arguments are supported:
globalClusterIdentifier
- (Required, Forces new resources) Global cluster identifier.databaseName
- (Optional, Forces new resources) Name for an automatically created database on cluster creation.deletionProtection
- (Optional) If the Global Cluster should have deletion protection enabled. The database can't be deleted when this value is set totrue
. The default isfalse
.engine
- (Optional, Forces new resources) Name of the database engine to be used for this DB cluster. Terraform will only perform drift detection if a configuration value is provided. Valid values:aurora
,auroraMysql
,auroraPostgresql
. Defaults toaurora
. Conflicts withsourceDbClusterIdentifier
.engineVersion
- (Optional) Engine version of the Aurora global database. Theengine
,engineVersion
, andinstanceClass
(on theawsRdsClusterInstance
) must together support global databases. See Using Amazon Aurora global databases for more information. By upgrading the engine version, Terraform will upgrade cluster members. NOTE: To avoid aninconsistentFinalPlan
error while upgrading, use thelifecycle
ignoreChanges
forengineVersion
meta argument on the associatedawsRdsCluster
resource as shown above in Upgrading Engine Versions example.forceDestroy
- (Optional) Enable to remove DB Cluster members from Global Cluster on destroy. Required withsourceDbClusterIdentifier
.sourceDbClusterIdentifier
- (Optional) Amazon Resource Name (ARN) to use as the primary DB Cluster of the Global Cluster on creation. Terraform cannot perform drift detection of this value.storageEncrypted
- (Optional, Forces new resources) Specifies whether the DB cluster is encrypted. The default isfalse
unlesssourceDbClusterIdentifier
is specified and encrypted. Terraform will only perform drift detection if a configuration value is provided.
Attributes Reference
In addition to all arguments above, the following attributes are exported:
arn
- RDS Global Cluster Amazon Resource Name (ARN)globalClusterMembers
- Set of objects containing Global Cluster members.dbClusterArn
- Amazon Resource Name (ARN) of member DB ClusterisWriter
- Whether the member is the primary DB ClusterglobalClusterResourceId
- AWS Region-unique, immutable identifier for the global database cluster. This identifier is found in AWS CloudTrail log entries whenever the AWS KMS key for the DB cluster is accessedid
- RDS Global Cluster identifier
Timeouts
create
- (Default30M
)update
- (Default90M
)delete
- (Default30M
)
Import
awsRdsGlobalCluster
can be imported by using the RDS Global Cluster identifier, e.g.,
Certain resource arguments, like forceDestroy
, only exist within Terraform. If the argument is set in the Terraform configuration on an imported resource, Terraform will show a difference on the first plan after import to update the state value. This change is safe to apply immediately so the state matches the desired configuration.
Certain resource arguments, like sourceDbClusterIdentifier
, do not have an API method for reading the information after creation. If the argument is set in the Terraform configuration on an imported resource, Terraform will always show a difference. To workaround this behavior, either omit the argument from the Terraform configuration or use ignoreChanges
to hide the difference, e.g.,
/*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 awsRdsGlobalClusterExample = new aws.rdsGlobalCluster.RdsGlobalCluster(
this,
"example",
{}
);
awsRdsGlobalClusterExample.addOverride("lifecycle", [
{
ignore_changes: ["${source_db_cluster_identifier}"],
},
]);