global_clusters

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

Overview

Name	global_clusters
Type	Resource
Id	aws.rds.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 database cluster.
deletion_protection	boolean	The deletion protection setting for the new global database cluster.
endpoint	string	The writer endpoint for the new global database cluster. This endpoint always points to the writer DB instance in the current primary cluster.
engine	string	The Aurora database engine used by the global database cluster.
engine_lifecycle_support	string	The lifecycle type for the global cluster. For more information, see CreateGlobalCluster.
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 (Aurora global database). 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 database cluster.
global_cluster_identifier	string	Contains a user-supplied global database cluster identifier. This identifier is the unique key that identifies a global database cluster.
global_cluster_members	string	The list of primary and secondary clusters within the global database cluster.
global_cluster_resource_id	string	The Amazon Web Services partition-unique, immutable identifier for the global database cluster. This identifier is found in Amazon Web Services CloudTrail log entries whenever the Amazon Web Services KMS key for the DB cluster is accessed.
status	string	Specifies the current state of this global database cluster.
storage_encrypted	boolean	The storage encryption setting for the global database cluster.
storage_encryption_type	string	The type of encryption used to protect data at rest in the global database cluster. Possible values: none - The global database cluster is not encrypted. sse-rds - The global database cluster is encrypted using an Amazon Web Services owned KMS key. sse-kms - The global database cluster is encrypted using a customer managed KMS key or Amazon Web Services managed KMS key.
tag_list	string	A list of tags. For more information, see Tagging Amazon RDS resources in the Amazon RDS User Guide or Tagging Amazon Aurora and Amazon RDS resources in the Amazon Aurora User Guide.

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 Aurora global database clusters. This API supports pagination. For more information on Amazon Aurora, see What is Amazon Aurora? in the Amazon Aurora User Guide. This action only applies to Aurora DB clusters.
create_global_cluster	insert	GlobalClusterIdentifier, region	SourceDBClusterIdentifier, Engine, EngineVersion, EngineLifecycleSupport, DeletionProtection, DatabaseName, StorageEncrypted, Tags	Creates an Aurora global database spread across multiple Amazon Web Services 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. You can create a global database that is initially empty, and then create the primary and secondary DB clusters in the global database. Or you can specify an existing Aurora cluster during the create operation, and this cluster becomes the primary cluster of the global database. This operation applies only to Aurora DB clusters.
remove_from_global_cluster	update	GlobalClusterIdentifier, DbClusterIdentifier, region		Detaches an Aurora secondary cluster from an Aurora global database cluster. The cluster becomes a standalone cluster with read-write capability instead of being read-only and receiving data from a primary cluster in a different Region. This operation only applies to Aurora DB clusters.
modify_global_cluster	update	GlobalClusterIdentifier, region	NewGlobalClusterIdentifier, DeletionProtection, EngineVersion, AllowMajorVersionUpgrade	Modifies a setting for an Amazon Aurora global database cluster. You can change one or more database configuration parameters by specifying these parameters and the new values in the request. For more information on Amazon Aurora, see What is Amazon Aurora? in the Amazon Aurora User Guide. This operation only applies to Aurora global database clusters.
delete_global_cluster	delete	GlobalClusterIdentifier, region		Deletes a global database cluster. The primary and secondary clusters must already be detached or destroyed first. This action only applies to Aurora DB 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 database cluster to fail over or switch over a global database. Switchover operations were previously called "managed planned failovers." Although this operation can be used either to fail over or to switch over a global database cluster, its intended use is for global database failover. To switch over a global database cluster, we recommend that you use the SwitchoverGlobalCluster operation instead. How you use this operation depends on whether you are failing over or switching over your global database cluster: Failing over - Specify the AllowDataLoss parameter and don't specify the Switchover parameter. Switching over - Specify the Switchover parameter or omit it, but don't specify the AllowDataLoss parameter. About failing over and switching over While failing over and switching over a global database cluster both change the primary DB cluster, you use these operations for different reasons: Failing over - 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. For more information about failing over an Amazon Aurora global database, see Performing managed failovers for Aurora global databases in the Amazon Aurora User Guide. Switching over - Use this operation on a healthy global database cluster for planned events, such as Regional rotation or to fail back to the original primary DB cluster after a failover operation. With this operation, there is no data loss. For more information about switching over an Amazon Aurora global database, see Performing switchovers for Aurora global databases in the Amazon Aurora User Guide.
switchover_global_cluster	exec	GlobalClusterIdentifier, TargetDbClusterIdentifier, region		Switches over the specified secondary DB cluster to be the new primary DB cluster in the global database cluster. Switchover operations were previously called "managed planned failovers." Aurora promotes the specified secondary cluster to assume full read/write capabilities and demotes the current primary cluster to a secondary (read-only) cluster, maintaining the orginal replication topology. All secondary clusters are synchronized with the primary at the beginning of the process so the new primary continues operations for the Aurora global database without losing any data. Your database is unavailable for a short time while the primary and selected secondary clusters are assuming their new roles. For more information about switching over an Aurora global database, see Performing switchovers for Amazon Aurora global databases in the Amazon Aurora User Guide. This operation is intended for controlled environments, for operations such as "regional rotation" or to fall back to the original primary after a global database failover.

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 Aurora global database cluster.
GlobalClusterIdentifier	string	The identifier of the global database cluster to switch over. This parameter isn't case-sensitive. Constraints: Must match the identifier of an existing global database cluster (Aurora global database).
TargetDbClusterIdentifier	string	The identifier of the secondary Aurora DB cluster to promote to the new primary for the global database cluster. Use the Amazon Resource Name (ARN) for the identifier so that Aurora can locate the cluster in its Amazon Web Services Region.
region	string	AWS region (default: us-east-1)
AllowDataLoss	boolean	Specifies whether to allow data loss for this global database cluster operation. Allowing data loss triggers a global failover operation. If you don't specify AllowDataLoss, the global database cluster operation defaults to a switchover. Constraints: Can't be specified together with the Switchover parameter.
AllowMajorVersionUpgrade	boolean	Specifies whether to allow major version upgrades. Constraints: Must be enabled if you specify a value for the EngineVersion parameter that's a different major version than the global cluster's current version. If you upgrade the major version of a global database, the cluster and DB instance parameter groups are set to the default parameter groups for the new version. Apply any custom parameter groups after completing the upgrade.
DatabaseName	string	The name for your database of up to 64 alphanumeric characters. If you don't specify a name, Amazon Aurora doesn't create a database in the global database cluster. Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the database name from the source DB cluster.
DeletionProtection	boolean	Specifies whether to enable deletion protection for the global database cluster. The global database cluster can't be deleted when deletion protection is enabled.
Engine	string	The database engine to use for this global database cluster. Valid Values: aurora-mysql | aurora-postgresql Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the engine of the source DB cluster.
EngineLifecycleSupport	string	The lifecycle type for this global database cluster. By default, this value is set to open-source-rds-extended-support, which enrolls your global cluster into Amazon RDS Extended Support. At the end of standard support, you can avoid charges for Extended Support by setting the value to open-source-rds-extended-support-disabled. In this case, creating the global cluster will fail if the DB major version is past its end of standard support date. This setting only applies to Aurora PostgreSQL-based global databases. You can use this setting to enroll your global cluster into Amazon RDS Extended Support. With RDS Extended Support, you can run the selected major engine version on your global cluster past the end of standard support for that engine version. For more information, see Amazon RDS Extended Support with Amazon Aurora in the Amazon Aurora User Guide. Valid Values: open-source-rds-extended-support | open-source-rds-extended-support-disabled Default: open-source-rds-extended-support
EngineVersion	string	The version number of the database engine to which you want to upgrade. To list all of the available engine versions for aurora-mysql (for MySQL-based Aurora global databases), use the following command: aws rds describe-db-engine-versions --engine aurora-mysql --query '[]|[?SupportsGlobalDatabases == true].[EngineVersion]' To list all of the available engine versions for aurora-postgresql (for PostgreSQL-based Aurora global databases), use the following command: aws rds describe-db-engine-versions --engine aurora-postgresql --query '[]|[?SupportsGlobalDatabases == true].[EngineVersion]'
Filters	array	A filter that specifies one or more global database clusters to describe. This parameter is case-sensitive. Currently, the only supported filter is region. If used, the request returns information about any global cluster with at least one member (primary or secondary) in the specified Amazon Web Services Regions.
GlobalClusterIdentifier	string	The user-supplied DB cluster identifier. If this parameter is specified, information from only the specific DB cluster is returned. This parameter isn't case-sensitive. Constraints: If supplied, must match an existing DBClusterIdentifier.
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. Default: 100 Constraints: Minimum 20, maximum 100.
NewGlobalClusterIdentifier	string	The new cluster identifier for the global database cluster. This value is stored as a lowercase string. Constraints: 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 database. If you provide a value for this parameter, don't specify values for the following settings because Amazon Aurora uses the values from the specified source DB cluster: DatabaseName Engine EngineVersion StorageEncrypted
StorageEncrypted	boolean	Specifies whether to enable storage encryption for the new global database cluster. Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the setting from the source DB cluster.
Switchover	boolean	Specifies whether to switch over this global database cluster. Constraints: Can't be specified together with the AllowDataLoss parameter.
Tags	array	Tags to assign to the global cluster.

SELECT examples

describe_global_clusters

Returns information about Aurora global database clusters. This API supports pagination. For more information on Amazon Aurora, see What is Amazon Aurora? in the Amazon Aurora User Guide. This action only applies to Aurora DB clusters.

SELECT
database_name,
deletion_protection,
endpoint,
engine,
engine_lifecycle_support,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
storage_encryption_type,
tag_list
FROM aws.rds.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 Aurora global database spread across multiple Amazon Web Services 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. You can create a global database that is initially empty, and then create the primary and secondary DB clusters in the global database. Or you can specify an existing Aurora cluster during the create operation, and this cluster becomes the primary cluster of the global database. This operation applies only to Aurora DB clusters.

INSERT INTO aws.rds.global_clusters (
GlobalClusterIdentifier,
region,
SourceDBClusterIdentifier,
Engine,
EngineVersion,
EngineLifecycleSupport,
DeletionProtection,
DatabaseName,
StorageEncrypted,
Tags
)
SELECT 
'{{ GlobalClusterIdentifier }}',
'{{ region }}',
'{{ SourceDBClusterIdentifier }}',
'{{ Engine }}',
'{{ EngineVersion }}',
'{{ EngineLifecycleSupport }}',
'{{ DeletionProtection }}',
'{{ DatabaseName }}',
'{{ StorageEncrypted }}',
'{{ Tags }}'
RETURNING
database_name,
deletion_protection,
endpoint,
engine,
engine_lifecycle_support,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
storage_encryption_type,
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 database. If you provide a value for this parameter, don't specify values for the following settings because Amazon Aurora uses the values from the specified source DB cluster: DatabaseName Engine EngineVersion StorageEncrypted
    description: The Amazon Resource Name (ARN) to use as the primary cluster of the global database. If you provide a value for this parameter, don't specify values for the following settings because Amazon Aurora uses the values from the specified source DB cluster: DatabaseName Engine EngineVersion StorageEncrypted
  - name: Engine
    value: "{{ Engine }}"
    description: The database engine to use for this global database cluster. Valid Values: aurora-mysql | aurora-postgresql Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the engine of the source DB cluster.
    description: The database engine to use for this global database cluster. Valid Values: aurora-mysql | aurora-postgresql Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the engine of the source DB cluster.
  - name: EngineVersion
    value: "{{ EngineVersion }}"
    description: The engine version to use for this global database cluster. Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the engine version of the source DB cluster.
    description: The engine version to use for this global database cluster. Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the engine version of the source DB cluster.
  - name: EngineLifecycleSupport
    value: "{{ EngineLifecycleSupport }}"
    description: The lifecycle type for this global database cluster. By default, this value is set to open-source-rds-extended-support, which enrolls your global cluster into Amazon RDS Extended Support. At the end of standard support, you can avoid charges for Extended Support by setting the value to open-source-rds-extended-support-disabled. In this case, creating the global cluster will fail if the DB major version is past its end of standard support date. This setting only applies to Aurora PostgreSQL-based global databases. You can use this setting to enroll your global cluster into Amazon RDS Extended Support. With RDS Extended Support, you can run the selected major engine version on your global cluster past the end of standard support for that engine version. For more information, see Amazon RDS Extended Support with Amazon Aurora in the Amazon Aurora User Guide. Valid Values: open-source-rds-extended-support | open-source-rds-extended-support-disabled Default: open-source-rds-extended-support
    description: The lifecycle type for this global database cluster. By default, this value is set to open-source-rds-extended-support, which enrolls your global cluster into Amazon RDS Extended Support. At the end of standard support, you can avoid charges for Extended Support by setting the value to open-source-rds-extended-support-disabled. In this case, creating the global cluster will fail if the DB major version is past its end of standard support date. This setting only applies to Aurora PostgreSQL-based global databases. You can use this setting to enroll your global cluster into Amazon RDS Extended Support. With RDS Extended Support, you can run the selected major engine version on your global cluster past the end of standard support for that engine version. For more information, see Amazon RDS Extended Support with Amazon Aurora in the Amazon Aurora User Guide. Valid Values: open-source-rds-extended-support | open-source-rds-extended-support-disabled Default: open-source-rds-extended-support
  - name: DeletionProtection
    value: {{ DeletionProtection }}
    description: Specifies whether to enable deletion protection for the new global database cluster. The global database can't be deleted when deletion protection is enabled.
    description: Specifies whether to enable deletion protection for the new global database cluster. The global database can't be deleted when deletion protection is enabled.
  - name: DatabaseName
    value: "{{ DatabaseName }}"
    description: The name for your database of up to 64 alphanumeric characters. If you don't specify a name, Amazon Aurora doesn't create a database in the global database cluster. Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the database name from the source DB cluster.
    description: The name for your database of up to 64 alphanumeric characters. If you don't specify a name, Amazon Aurora doesn't create a database in the global database cluster. Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the database name from the source DB cluster.
  - name: StorageEncrypted
    value: {{ StorageEncrypted }}
    description: Specifies whether to enable storage encryption for the new global database cluster. Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the setting from the source DB cluster.
    description: Specifies whether to enable storage encryption for the new global database cluster. Constraints: Can't be specified if SourceDBClusterIdentifier is specified. In this case, Amazon Aurora uses the setting from the source DB cluster.
  - name: Tags
    value: "{{ Tags }}"
    description: Tags to assign to the global cluster.
    description: Tags to assign to the global cluster.

UPDATE examples

remove_from_global_cluster

Detaches an Aurora secondary cluster from an Aurora global database cluster. The cluster becomes a standalone cluster with read-write capability instead of being read-only and receiving data from a primary cluster in a different Region. This operation only applies to Aurora DB clusters.

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

modify_global_cluster

Modifies a setting for an Amazon Aurora global database cluster. You can change one or more database configuration parameters by specifying these parameters and the new values in the request. For more information on Amazon Aurora, see What is Amazon Aurora? in the Amazon Aurora User Guide. This operation only applies to Aurora global database clusters.

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

DELETE examples

delete_global_cluster

Deletes a global database cluster. The primary and secondary clusters must already be detached or destroyed first. This action only applies to Aurora DB clusters.

DELETE FROM aws.rds.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 database cluster to fail over or switch over a global database. Switchover operations were previously called "managed planned failovers." Although this operation can be used either to fail over or to switch over a global database cluster, its intended use is for global database failover. To switch over a global database cluster, we recommend that you use the SwitchoverGlobalCluster operation instead. How you use this operation depends on whether you are failing over or switching over your global database cluster: Failing over - Specify the AllowDataLoss parameter and don't specify the Switchover parameter. Switching over - Specify the Switchover parameter or omit it, but don't specify the AllowDataLoss parameter. About failing over and switching over While failing over and switching over a global database cluster both change the primary DB cluster, you use these operations for different reasons: Failing over - 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. For more information about failing over an Amazon Aurora global database, see Performing managed failovers for Aurora global databases in the Amazon Aurora User Guide. Switching over - Use this operation on a healthy global database cluster for planned events, such as Regional rotation or to fail back to the original primary DB cluster after a failover operation. With this operation, there is no data loss. For more information about switching over an Amazon Aurora global database, see Performing switchovers for Aurora global databases in the Amazon Aurora User Guide.

EXEC aws.rds.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 DB cluster to be the new primary DB cluster in the global database cluster. Switchover operations were previously called "managed planned failovers." Aurora promotes the specified secondary cluster to assume full read/write capabilities and demotes the current primary cluster to a secondary (read-only) cluster, maintaining the orginal replication topology. All secondary clusters are synchronized with the primary at the beginning of the process so the new primary continues operations for the Aurora global database without losing any data. Your database is unavailable for a short time while the primary and selected secondary clusters are assuming their new roles. For more information about switching over an Aurora global database, see Performing switchovers for Amazon Aurora global databases in the Amazon Aurora User Guide. This operation is intended for controlled environments, for operations such as "regional rotation" or to fall back to the original primary after a global database failover.

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