Skip to content

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 to true. The default is false.
  • 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 to aurora. Conflicts with sourceDbClusterIdentifier.
  • engineVersion - (Optional) Engine version of the Aurora global database. The engine, engineVersion, and instanceClass (on the awsRdsClusterInstance) 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 an inconsistentFinalPlan error while upgrading, use the lifecycle ignoreChanges for engineVersion meta argument on the associated awsRdsCluster resource as shown above in Upgrading Engine Versions example.
  • forceDestroy - (Optional) Enable to remove DB Cluster members from Global Cluster on destroy. Required with sourceDbClusterIdentifier.
  • 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 is false unless sourceDbClusterIdentifier 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 Cluster
  • isWriter - Whether the member is the primary DB Cluster
  • globalClusterResourceId - 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 accessed
  • id - RDS Global Cluster identifier

Timeouts

Configuration options:

  • create - (Default 30M)
  • update - (Default 90M)
  • delete - (Default 30M)

Import

awsRdsGlobalCluster can be imported by using the RDS Global Cluster identifier, e.g.,

$ terraform import aws_rds_global_cluster.example example

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}"],
  },
]);