global_clusters

Creates, updates, deletes, gets or lists a global_clusters resource.

Overview

Name	global_clusters
Type	Resource
Id	aws.docdb.global_clusters

Fields

The following fields are returned by SELECT queries:

describe_global_clusters

Name	Datatype	Description
database_name	string	The default database name within the new global cluster.
deletion_protection	boolean	The deletion protection setting for the new global cluster.
engine	string	The Amazon DocumentDB database engine used by the global cluster.
engine_version	string	Indicates the database engine version.
failover_state	string	A data object containing all properties for the current state of an in-process or pending switchover or failover process for this global cluster. This object is empty unless the SwitchoverGlobalCluster or FailoverGlobalCluster operation was called on this global cluster.
global_cluster_arn	string	The Amazon Resource Name (ARN) for the global cluster.
global_cluster_identifier	string	Contains a user-supplied global cluster identifier. This identifier is the unique key that identifies a global cluster.
global_cluster_members	string	The list of cluster IDs for secondary clusters within the global cluster. Currently limited to one item.
global_cluster_resource_id	string	The Amazon Web Services RegionRegion-unique, immutable identifier for the global database cluster. This identifier is found in CloudTrail log entries whenever the KMS customer master key (CMK) for the cluster is accessed.
status	string	Specifies the current state of this global cluster.
storage_encrypted	boolean	The storage encryption setting for the global cluster.
tag_list	string	A list of global cluster tags.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_global_clusters	select	region	GlobalClusterIdentifier, Filters, MaxRecords, Marker	Returns information about Amazon DocumentDB global clusters. This API supports pagination. This action only applies to Amazon DocumentDB clusters.
create_global_cluster	insert	GlobalClusterIdentifier, region	SourceDBClusterIdentifier, Engine, EngineVersion, DeletionProtection, DatabaseName, StorageEncrypted	Creates an Amazon DocumentDB global cluster that can span multiple multiple Amazon Web Services Regions. The global cluster contains one primary cluster with read-write capability, and up-to 10 read-only secondary clusters. Global clusters uses storage-based fast replication across regions with latencies less than one second, using dedicated infrastructure with no impact to your workload’s performance. You can create a global cluster that is initially empty, and then add a primary and a secondary to it. Or you can specify an existing cluster during the create operation, and this cluster becomes the primary of the global cluster. This action only applies to Amazon DocumentDB clusters.
remove_from_global_cluster	update	GlobalClusterIdentifier, DbClusterIdentifier, region		Detaches an Amazon DocumentDB secondary cluster from a global cluster. The cluster becomes a standalone cluster with read-write capability instead of being read-only and receiving data from a primary in a different region. This action only applies to Amazon DocumentDB clusters.
modify_global_cluster	update	GlobalClusterIdentifier, region	NewGlobalClusterIdentifier, DeletionProtection	Modify a setting for an Amazon DocumentDB global cluster. You can change one or more configuration parameters (for example: deletion protection), or the global cluster identifier by specifying these parameters and the new values in the request. This action only applies to Amazon DocumentDB clusters.
delete_global_cluster	delete	GlobalClusterIdentifier, region		Deletes a global cluster. The primary and secondary clusters must already be detached or deleted before attempting to delete a global cluster. This action only applies to Amazon DocumentDB clusters.
failover_global_cluster	exec	GlobalClusterIdentifier, TargetDbClusterIdentifier, region	AllowDataLoss, Switchover	Promotes the specified secondary DB cluster to be the primary DB cluster in the global cluster when failing over a global cluster occurs. Use this operation to respond to an unplanned event, such as a regional disaster in the primary region. Failing over can result in a loss of write transaction data that wasn't replicated to the chosen secondary before the failover event occurred. However, the recovery process that promotes a DB instance on the chosen seconday DB cluster to be the primary writer DB instance guarantees that the data is in a transactionally consistent state.
switchover_global_cluster	exec	GlobalClusterIdentifier, TargetDbClusterIdentifier, region		Switches over the specified secondary Amazon DocumentDB cluster to be the new primary Amazon DocumentDB cluster in the global database cluster.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
DbClusterIdentifier	string	The Amazon Resource Name (ARN) identifying the cluster that was detached from the Amazon DocumentDB global cluster.
GlobalClusterIdentifier	string	The identifier of the Amazon DocumentDB global database cluster to switch over. The identifier is the unique key assigned by the user when the cluster is created. In other words, it's the name of the global cluster. This parameter isn’t case-sensitive. Constraints: Must match the identifier of an existing global cluster (Amazon DocumentDB global database). Minimum length of 1. Maximum length of 255. Pattern: [A-Za-z][0-9A-Za-z-:._]*
TargetDbClusterIdentifier	string	The identifier of the secondary Amazon DocumentDB cluster to promote to the new primary for the global database cluster. Use the Amazon Resource Name (ARN) for the identifier so that Amazon DocumentDB can locate the cluster in its Amazon Web Services region. Constraints: Must match the identifier of an existing secondary cluster. Minimum length of 1. Maximum length of 255. Pattern: [A-Za-z][0-9A-Za-z-:._]*
region	string	AWS region (default: us-east-1)
AllowDataLoss	boolean	Specifies whether to allow data loss for this global cluster operation. Allowing data loss triggers a global failover operation. If you don't specify AllowDataLoss, the global cluster operation defaults to a switchover. Constraints: Can't be specified together with the Switchover parameter.
DatabaseName	string	The name for your database of up to 64 alpha-numeric characters. If you do not provide a name, Amazon DocumentDB will not create a database in the global cluster you are creating.
DeletionProtection	boolean	Indicates if the global cluster has deletion protection enabled. The global cluster can't be deleted when deletion protection is enabled.
Engine	string	The name of the database engine to be used for this cluster.
EngineVersion	string	The engine version of the global cluster.
Filters	array	A filter that specifies one or more global DB clusters to describe. Supported filters: db-cluster-id accepts cluster identifiers and cluster Amazon Resource Names (ARNs). The results list will only include information about the clusters identified by these ARNs.
GlobalClusterIdentifier	string	The user-supplied cluster identifier. If this parameter is specified, information from only the specific cluster is returned. This parameter isn't case-sensitive.
Marker	string	An optional pagination token provided by a previous DescribeGlobalClusters request. If this parameter is specified, the response includes only records beyond the marker, up to the value specified by MaxRecords.
MaxRecords	integer	The maximum number of records to include in the response. If more records exist than the specified MaxRecords value, a pagination token called a marker is included in the response so that you can retrieve the remaining results.
NewGlobalClusterIdentifier	string	The new identifier for a global cluster when you modify a global cluster. This value is stored as a lowercase string. Must contain from 1 to 63 letters, numbers, or hyphens The first character must be a letter Can't end with a hyphen or contain two consecutive hyphens Example: my-cluster2
SourceDBClusterIdentifier	string	The Amazon Resource Name (ARN) to use as the primary cluster of the global cluster. This parameter is optional.
StorageEncrypted	boolean	The storage encryption setting for the new global cluster.
Switchover	boolean	Specifies whether to switch over this global database cluster. Constraints: Can't be specified together with the AllowDataLoss parameter.

SELECT examples

describe_global_clusters

Returns information about Amazon DocumentDB global clusters. This API supports pagination. This action only applies to Amazon DocumentDB clusters.

SELECT
database_name,
deletion_protection,
engine,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
tag_list
FROM aws.docdb.global_clusters
WHERE region = '{{ region }}' -- required
AND GlobalClusterIdentifier = '{{ GlobalClusterIdentifier }}'
AND Filters = '{{ Filters }}'
AND MaxRecords = '{{ MaxRecords }}'
AND Marker = '{{ Marker }}'
;

INSERT examples

create_global_cluster

Creates an Amazon DocumentDB global cluster that can span multiple multiple Amazon Web Services Regions. The global cluster contains one primary cluster with read-write capability, and up-to 10 read-only secondary clusters. Global clusters uses storage-based fast replication across regions with latencies less than one second, using dedicated infrastructure with no impact to your workload’s performance. You can create a global cluster that is initially empty, and then add a primary and a secondary to it. Or you can specify an existing cluster during the create operation, and this cluster becomes the primary of the global cluster. This action only applies to Amazon DocumentDB clusters.

INSERT INTO aws.docdb.global_clusters (
GlobalClusterIdentifier,
region,
SourceDBClusterIdentifier,
Engine,
EngineVersion,
DeletionProtection,
DatabaseName,
StorageEncrypted
)
SELECT 
'{{ GlobalClusterIdentifier }}',
'{{ region }}',
'{{ SourceDBClusterIdentifier }}',
'{{ Engine }}',
'{{ EngineVersion }}',
'{{ DeletionProtection }}',
'{{ DatabaseName }}',
'{{ StorageEncrypted }}'
RETURNING
database_name,
deletion_protection,
engine,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
tag_list
;

Manifest

# Description fields are for documentation purposes
- name: global_clusters
props:
  - name: GlobalClusterIdentifier
    value: "{{ GlobalClusterIdentifier }}"
    description: Required parameter for the global_clusters resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the global_clusters resource.
  - name: SourceDBClusterIdentifier
    value: "{{ SourceDBClusterIdentifier }}"
    description: The Amazon Resource Name (ARN) to use as the primary cluster of the global cluster. This parameter is optional.
    description: The Amazon Resource Name (ARN) to use as the primary cluster of the global cluster. This parameter is optional.
  - name: Engine
    value: "{{ Engine }}"
    description: The name of the database engine to be used for this cluster.
    description: The name of the database engine to be used for this cluster.
  - name: EngineVersion
    value: "{{ EngineVersion }}"
    description: The engine version of the global cluster.
    description: The engine version of the global cluster.
  - name: DeletionProtection
    value: {{ DeletionProtection }}
    description: The deletion protection setting for the new global cluster. The global cluster can't be deleted when deletion protection is enabled.
    description: The deletion protection setting for the new global cluster. The global cluster can't be deleted when deletion protection is enabled.
  - name: DatabaseName
    value: "{{ DatabaseName }}"
    description: The name for your database of up to 64 alpha-numeric characters. If you do not provide a name, Amazon DocumentDB will not create a database in the global cluster you are creating.
    description: The name for your database of up to 64 alpha-numeric characters. If you do not provide a name, Amazon DocumentDB will not create a database in the global cluster you are creating.
  - name: StorageEncrypted
    value: {{ StorageEncrypted }}
    description: The storage encryption setting for the new global cluster.
    description: The storage encryption setting for the new global cluster.

UPDATE examples

remove_from_global_cluster

Detaches an Amazon DocumentDB secondary cluster from a global cluster. The cluster becomes a standalone cluster with read-write capability instead of being read-only and receiving data from a primary in a different region. This action only applies to Amazon DocumentDB clusters.

UPDATE aws.docdb.global_clusters
SET 
-- No updatable properties
WHERE 
GlobalClusterIdentifier = '{{ GlobalClusterIdentifier }}' --required
AND DbClusterIdentifier = '{{ DbClusterIdentifier }}' --required
AND region = '{{ region }}' --required
RETURNING
database_name,
deletion_protection,
engine,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
tag_list;

modify_global_cluster

Modify a setting for an Amazon DocumentDB global cluster. You can change one or more configuration parameters (for example: deletion protection), or the global cluster identifier by specifying these parameters and the new values in the request. This action only applies to Amazon DocumentDB clusters.

UPDATE aws.docdb.global_clusters
SET 
-- No updatable properties
WHERE 
GlobalClusterIdentifier = '{{ GlobalClusterIdentifier }}' --required
AND region = '{{ region }}' --required
AND NewGlobalClusterIdentifier = '{{ NewGlobalClusterIdentifier}}'
AND DeletionProtection = {{ DeletionProtection}}
RETURNING
database_name,
deletion_protection,
engine,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
tag_list;

DELETE examples

delete_global_cluster

Deletes a global cluster. The primary and secondary clusters must already be detached or deleted before attempting to delete a global cluster. This action only applies to Amazon DocumentDB clusters.

DELETE FROM aws.docdb.global_clusters
WHERE GlobalClusterIdentifier = '{{ GlobalClusterIdentifier }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

failover_global_cluster

Promotes the specified secondary DB cluster to be the primary DB cluster in the global cluster when failing over a global cluster occurs. Use this operation to respond to an unplanned event, such as a regional disaster in the primary region. Failing over can result in a loss of write transaction data that wasn't replicated to the chosen secondary before the failover event occurred. However, the recovery process that promotes a DB instance on the chosen seconday DB cluster to be the primary writer DB instance guarantees that the data is in a transactionally consistent state.

EXEC aws.docdb.global_clusters.failover_global_cluster 
@GlobalClusterIdentifier='{{ GlobalClusterIdentifier }}' --required, 
@TargetDbClusterIdentifier='{{ TargetDbClusterIdentifier }}' --required, 
@region='{{ region }}' --required, 
@AllowDataLoss={{ AllowDataLoss }}, 
@Switchover={{ Switchover }}
;

switchover_global_cluster

Switches over the specified secondary Amazon DocumentDB cluster to be the new primary Amazon DocumentDB cluster in the global database cluster.

EXEC aws.docdb.global_clusters.switchover_global_cluster 
@GlobalClusterIdentifier='{{ GlobalClusterIdentifier }}' --required, 
@TargetDbClusterIdentifier='{{ TargetDbClusterIdentifier }}' --required, 
@region='{{ region }}' --required
;