Skip to content

Resource: awsDocdbGlobalCluster

Manages an DocumentDB Global Cluster. A global cluster consists of one primary region and up to five read-only secondary regions. You issue write operations directly to the primary cluster in the primary region and Amazon DocumentDB automatically replicates the data to the secondary regions using dedicated infrastructure.

More information about DocumentDB Global Clusters can be found in the DocumentDB Developer Guide.

Example Usage

New DocumentDB 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 awsDocdbGlobalClusterExample =
  new aws.docdbGlobalCluster.DocdbGlobalCluster(this, "example", {
    engine: "docdb",
    engineVersion: "4.0.0",
    globalClusterIdentifier: "global-test",
  });
const awsDocdbClusterPrimary = new aws.docdbCluster.DocdbCluster(
  this,
  "primary",
  {
    clusterIdentifier: "test-primary-cluster",
    dbSubnetGroupName: "default",
    engine: awsDocdbGlobalClusterExample.engine,
    engineVersion: awsDocdbGlobalClusterExample.engineVersion,
    globalClusterIdentifier: awsDocdbGlobalClusterExample.id,
    masterPassword: "somepass123",
    masterUsername: "username",
    provider: `\${${awsPrimary.fqn}}`,
  }
);
const awsDocdbClusterSecondary = new aws.docdbCluster.DocdbCluster(
  this,
  "secondary",
  {
    clusterIdentifier: "test-secondary-cluster",
    dbSubnetGroupName: "default",
    engine: awsDocdbGlobalClusterExample.engine,
    engineVersion: awsDocdbGlobalClusterExample.engineVersion,
    globalClusterIdentifier: awsDocdbGlobalClusterExample.id,
    provider: `\${${awsSecondary.fqn}}`,
  }
);
const awsDocdbClusterInstancePrimary =
  new aws.docdbClusterInstance.DocdbClusterInstance(this, "primary_5", {
    clusterIdentifier: awsDocdbClusterPrimary.id,
    engine: awsDocdbGlobalClusterExample.engine,
    identifier: "test-primary-cluster-instance",
    instanceClass: "db.r5.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.*/
awsDocdbClusterInstancePrimary.overrideLogicalId("primary");
const awsDocdbClusterInstanceSecondary =
  new aws.docdbClusterInstance.DocdbClusterInstance(this, "secondary_6", {
    clusterIdentifier: awsDocdbClusterSecondary.id,
    depends_on: [`\${${awsDocdbClusterInstancePrimary.fqn}}`],
    engine: awsDocdbGlobalClusterExample.engine,
    identifier: "test-secondary-cluster-instance",
    instanceClass: "db.r5.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.*/
awsDocdbClusterInstanceSecondary.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 awsDocdbClusterExample = new aws.docdbCluster.DocdbCluster(
  this,
  "example",
  {}
);
awsDocdbClusterExample.addOverride("lifecycle", [
  {
    ignore_changes: ["${global_cluster_identifier}"],
  },
]);
const awsDocdbGlobalClusterExample =
  new aws.docdbGlobalCluster.DocdbGlobalCluster(this, "example_1", {
    globalClusterIdentifier: "example",
    sourceDbClusterIdentifier: awsDocdbClusterExample.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.*/
awsDocdbGlobalClusterExample.overrideLogicalId("example");

Argument Reference

The following arguments are supported:

  • globalClusterIdentifier - (Required, Forces new resources) The 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. Current Valid values: docdb. Defaults to docdb. Conflicts with sourceDbClusterIdentifier.
  • engineVersion - (Optional) Engine version of the global database. Upgrading the engine version will result in all cluster members being immediately updated and will.
  • NOTE: Upgrading major versions is not supported.
  • 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 - 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 - DocDB Global Cluster.

Timeouts

Configuration options:

  • create - (Default 5M)
  • update - (Default 5M)
  • delete - (Default 5M)

Import

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

$ terraform import aws_docdb_global_cluster.example example

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 awsDocdbGlobalClusterExample =
  new aws.docdbGlobalCluster.DocdbGlobalCluster(this, "example", {});
awsDocdbGlobalClusterExample.addOverride("lifecycle", [
  {
    ignore_changes: ["${source_db_cluster_identifier}"],
  },
]);