global_replication_groups

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

Overview

Name	global_replication_groups
Type	Resource
Id	aws.elasticache.global_replication_groups

Fields

The following fields are returned by SELECT queries:

describe_global_replication_groups

Name	Datatype	Description
arn	string	The ARN (Amazon Resource Name) of the global replication group.
at_rest_encryption_enabled	boolean	A flag that enables encryption at rest when set to true. You cannot modify the value of AtRestEncryptionEnabled after the replication group is created. To enable encryption at rest on a replication group you must set AtRestEncryptionEnabled to true when you create the replication group. Required: Only available when creating a replication group in an Amazon VPC using Redis OSS version 3.2.6, 4.x or later.
auth_token_enabled	boolean	A flag that enables using an AuthToken (password) when issuing Valkey or Redis OSS commands. Default: false
cache_node_type	string	The cache node type of the Global datastore
cluster_enabled	boolean	A flag that indicates whether the Global datastore is cluster enabled.
engine	string	The ElastiCache engine. For Valkey or Redis OSS only.
engine_version	string	The ElastiCache engine version.
global_node_groups	string	Indicates the slot configuration and global identifier for each slice group.
global_replication_group_description	string	The optional description of the Global datastore
global_replication_group_id	string	The name of the Global datastore
members	string	The replication groups that comprise the Global datastore.
status	string	The status of the Global datastore
transit_encryption_enabled	boolean	A flag that enables in-transit encryption when set to true. Required: Only available when creating a replication group in an Amazon VPC using Redis OSS version 3.2.6, 4.x or later.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_global_replication_groups	select	region	GlobalReplicationGroupId, MaxRecords, Marker, ShowMemberInfo	Returns information about a particular global replication group. If no identifier is specified, returns information about all Global datastores.
create_global_replication_group	insert	GlobalReplicationGroupIdSuffix, PrimaryReplicationGroupId, region	GlobalReplicationGroupDescription	Global Datastore offers fully managed, fast, reliable and secure cross-region replication. Using Global Datastore with Valkey or Redis OSS, you can create cross-region read replica clusters for ElastiCache to enable low-latency reads and disaster recovery across regions. For more information, see Replication Across Regions Using Global Datastore. The GlobalReplicationGroupIdSuffix is the name of the Global datastore. The PrimaryReplicationGroupId represents the name of the primary cluster that accepts writes and will replicate updates to the secondary cluster.
disassociate_global_replication_group	update	GlobalReplicationGroupId, ReplicationGroupId, ReplicationGroupRegion, region		Remove a secondary cluster from the Global datastore using the Global datastore name. The secondary cluster will no longer receive updates from the primary cluster, but will remain as a standalone cluster in that Amazon region.
modify_global_replication_group	update	GlobalReplicationGroupId, ApplyImmediately, region	CacheNodeType, Engine, EngineVersion, CacheParameterGroupName, GlobalReplicationGroupDescription, AutomaticFailoverEnabled	Modifies the settings for a Global datastore.
delete_global_replication_group	delete	GlobalReplicationGroupId, RetainPrimaryReplicationGroup, region		Deleting a Global datastore is a two-step process: First, you must DisassociateGlobalReplicationGroup to remove the secondary clusters in the Global datastore. Once the Global datastore contains only the primary cluster, you can use the DeleteGlobalReplicationGroup API to delete the Global datastore while retainining the primary cluster using RetainPrimaryReplicationGroup=true. Since the Global Datastore has only a primary cluster, you can delete the Global Datastore while retaining the primary by setting RetainPrimaryReplicationGroup=true. The primary cluster is never deleted when deleting a Global Datastore. It can only be deleted when it no longer is associated with any Global Datastore. When you receive a successful response from this operation, Amazon ElastiCache immediately begins deleting the selected resources; you cannot cancel or revert this operation.
decrease_node_groups_in_global_replication_group	exec	GlobalReplicationGroupId, NodeGroupCount, ApplyImmediately, region	GlobalNodeGroupsToRemove, GlobalNodeGroupsToRetain	Decreases the number of node groups in a Global datastore
failover_global_replication_group	exec	GlobalReplicationGroupId, PrimaryRegion, PrimaryReplicationGroupId, region		Used to failover the primary region to a secondary region. The secondary region will become primary, and all other clusters will become secondary.
increase_node_groups_in_global_replication_group	exec	GlobalReplicationGroupId, NodeGroupCount, ApplyImmediately, region	RegionalConfigurations	Increase the number of node groups in the Global datastore
rebalance_slots_in_global_replication_group	exec	GlobalReplicationGroupId, ApplyImmediately, region		Redistribute slots to ensure uniform distribution across existing shards in the 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
ApplyImmediately	boolean	If True, redistribution is applied immediately.
GlobalReplicationGroupId	string	The name of the Global datastore
GlobalReplicationGroupIdSuffix	string	The suffix name of a Global datastore. Amazon ElastiCache automatically applies a prefix to the Global datastore ID when it is created. Each Amazon Region has its own prefix. For instance, a Global datastore ID created in the US-West-1 region will begin with "dsdfu" along with the suffix name you provide. The suffix, combined with the auto-generated prefix, guarantees uniqueness of the Global datastore name across multiple regions. For a full list of Amazon Regions and their respective Global datastore iD prefixes, see Using the Amazon CLI with Global datastores .
NodeGroupCount	integer	Total number of node groups you want
PrimaryRegion	string	The Amazon region of the primary cluster of the Global datastore
PrimaryReplicationGroupId	string	The name of the primary replication group
ReplicationGroupId	string	The name of the secondary cluster you wish to remove from the Global datastore
ReplicationGroupRegion	string	The Amazon region of secondary cluster you wish to remove from the Global datastore
RetainPrimaryReplicationGroup	boolean	The primary replication group is retained as a standalone replication group.
region	string	AWS region (default: us-east-1)
AutomaticFailoverEnabled	boolean	Determines whether a read replica is automatically promoted to read/write primary if the existing primary encounters a failure.
CacheNodeType	string	A valid cache node type that you want to scale this Global datastore to.
CacheParameterGroupName	string	The name of the cache parameter group to use with the Global datastore. It must be compatible with the major engine version used by the Global datastore.
Engine	string	Modifies the engine listed in a global replication group message. The options are valkey, memcached or redis.
EngineVersion	string	The upgraded version of the cache engine to be run on the clusters in the Global datastore.
GlobalNodeGroupsToRemove	array	If the value of NodeGroupCount is less than the current number of node groups (shards), then either NodeGroupsToRemove or NodeGroupsToRetain is required. GlobalNodeGroupsToRemove is a list of NodeGroupIds to remove from the cluster. ElastiCache will attempt to remove all node groups listed by GlobalNodeGroupsToRemove from the cluster.
GlobalNodeGroupsToRetain	array	If the value of NodeGroupCount is less than the current number of node groups (shards), then either NodeGroupsToRemove or NodeGroupsToRetain is required. GlobalNodeGroupsToRetain is a list of NodeGroupIds to retain from the cluster. ElastiCache will attempt to retain all node groups listed by GlobalNodeGroupsToRetain from the cluster.
GlobalReplicationGroupDescription	string	A description of the Global datastore
GlobalReplicationGroupId	string	The name of the Global datastore
Marker	string	An optional marker returned from a prior request. Use this marker for pagination of results from this operation. 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 marker is included in the response so that the remaining results can be retrieved.
RegionalConfigurations	array	Describes the replication group IDs, the Amazon regions where they are stored and the shard configuration for each that comprise the Global datastore
ShowMemberInfo	boolean	Returns the list of members that comprise the Global datastore.

SELECT examples

describe_global_replication_groups

Returns information about a particular global replication group. If no identifier is specified, returns information about all Global datastores.

SELECT
arn,
at_rest_encryption_enabled,
auth_token_enabled,
cache_node_type,
cluster_enabled,
engine,
engine_version,
global_node_groups,
global_replication_group_description,
global_replication_group_id,
members,
status,
transit_encryption_enabled
FROM aws.elasticache.global_replication_groups
WHERE region = '{{ region }}' -- required
AND GlobalReplicationGroupId = '{{ GlobalReplicationGroupId }}'
AND MaxRecords = '{{ MaxRecords }}'
AND Marker = '{{ Marker }}'
AND ShowMemberInfo = '{{ ShowMemberInfo }}'
;

INSERT examples

create_global_replication_group

Global Datastore offers fully managed, fast, reliable and secure cross-region replication. Using Global Datastore with Valkey or Redis OSS, you can create cross-region read replica clusters for ElastiCache to enable low-latency reads and disaster recovery across regions. For more information, see Replication Across Regions Using Global Datastore. The GlobalReplicationGroupIdSuffix is the name of the Global datastore. The PrimaryReplicationGroupId represents the name of the primary cluster that accepts writes and will replicate updates to the secondary cluster.

INSERT INTO aws.elasticache.global_replication_groups (
GlobalReplicationGroupIdSuffix,
PrimaryReplicationGroupId,
region,
GlobalReplicationGroupDescription
)
SELECT 
'{{ GlobalReplicationGroupIdSuffix }}',
'{{ PrimaryReplicationGroupId }}',
'{{ region }}',
'{{ GlobalReplicationGroupDescription }}'
RETURNING
arn,
at_rest_encryption_enabled,
auth_token_enabled,
cache_node_type,
cluster_enabled,
engine,
engine_version,
global_node_groups,
global_replication_group_description,
global_replication_group_id,
members,
status,
transit_encryption_enabled
;

Manifest

# Description fields are for documentation purposes
- name: global_replication_groups
props:
  - name: GlobalReplicationGroupIdSuffix
    value: "{{ GlobalReplicationGroupIdSuffix }}"
    description: Required parameter for the global_replication_groups resource.
  - name: PrimaryReplicationGroupId
    value: "{{ PrimaryReplicationGroupId }}"
    description: Required parameter for the global_replication_groups resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the global_replication_groups resource.
  - name: GlobalReplicationGroupDescription
    value: "{{ GlobalReplicationGroupDescription }}"
    description: Provides details of the Global datastore
    description: Provides details of the Global datastore

UPDATE examples

disassociate_global_replication_group

Remove a secondary cluster from the Global datastore using the Global datastore name. The secondary cluster will no longer receive updates from the primary cluster, but will remain as a standalone cluster in that Amazon region.

UPDATE aws.elasticache.global_replication_groups
SET 
-- No updatable properties
WHERE 
GlobalReplicationGroupId = '{{ GlobalReplicationGroupId }}' --required
AND ReplicationGroupId = '{{ ReplicationGroupId }}' --required
AND ReplicationGroupRegion = '{{ ReplicationGroupRegion }}' --required
AND region = '{{ region }}' --required
RETURNING
arn,
at_rest_encryption_enabled,
auth_token_enabled,
cache_node_type,
cluster_enabled,
engine,
engine_version,
global_node_groups,
global_replication_group_description,
global_replication_group_id,
members,
status,
transit_encryption_enabled;

modify_global_replication_group

Modifies the settings for a Global datastore.

UPDATE aws.elasticache.global_replication_groups
SET 
-- No updatable properties
WHERE 
GlobalReplicationGroupId = '{{ GlobalReplicationGroupId }}' --required
AND ApplyImmediately = '{{ ApplyImmediately }}' --required
AND region = '{{ region }}' --required
AND CacheNodeType = '{{ CacheNodeType}}'
AND Engine = '{{ Engine}}'
AND EngineVersion = '{{ EngineVersion}}'
AND CacheParameterGroupName = '{{ CacheParameterGroupName}}'
AND GlobalReplicationGroupDescription = '{{ GlobalReplicationGroupDescription}}'
AND AutomaticFailoverEnabled = {{ AutomaticFailoverEnabled}}
RETURNING
arn,
at_rest_encryption_enabled,
auth_token_enabled,
cache_node_type,
cluster_enabled,
engine,
engine_version,
global_node_groups,
global_replication_group_description,
global_replication_group_id,
members,
status,
transit_encryption_enabled;

DELETE examples

delete_global_replication_group

Deleting a Global datastore is a two-step process: First, you must DisassociateGlobalReplicationGroup to remove the secondary clusters in the Global datastore. Once the Global datastore contains only the primary cluster, you can use the DeleteGlobalReplicationGroup API to delete the Global datastore while retainining the primary cluster using RetainPrimaryReplicationGroup=true. Since the Global Datastore has only a primary cluster, you can delete the Global Datastore while retaining the primary by setting RetainPrimaryReplicationGroup=true. The primary cluster is never deleted when deleting a Global Datastore. It can only be deleted when it no longer is associated with any Global Datastore. When you receive a successful response from this operation, Amazon ElastiCache immediately begins deleting the selected resources; you cannot cancel or revert this operation.

DELETE FROM aws.elasticache.global_replication_groups
WHERE GlobalReplicationGroupId = '{{ GlobalReplicationGroupId }}' --required
AND RetainPrimaryReplicationGroup = '{{ RetainPrimaryReplicationGroup }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

decrease_node_groups_in_global_replication_group

Decreases the number of node groups in a Global datastore

EXEC aws.elasticache.global_replication_groups.decrease_node_groups_in_global_replication_group 
@GlobalReplicationGroupId='{{ GlobalReplicationGroupId }}' --required, 
@NodeGroupCount='{{ NodeGroupCount }}' --required, 
@ApplyImmediately='{{ ApplyImmediately }}' --required, 
@region='{{ region }}' --required, 
@GlobalNodeGroupsToRemove='{{ GlobalNodeGroupsToRemove }}', 
@GlobalNodeGroupsToRetain='{{ GlobalNodeGroupsToRetain }}'
;

failover_global_replication_group

Used to failover the primary region to a secondary region. The secondary region will become primary, and all other clusters will become secondary.

EXEC aws.elasticache.global_replication_groups.failover_global_replication_group 
@GlobalReplicationGroupId='{{ GlobalReplicationGroupId }}' --required, 
@PrimaryRegion='{{ PrimaryRegion }}' --required, 
@PrimaryReplicationGroupId='{{ PrimaryReplicationGroupId }}' --required, 
@region='{{ region }}' --required
;

increase_node_groups_in_global_replication_group

Increase the number of node groups in the Global datastore

EXEC aws.elasticache.global_replication_groups.increase_node_groups_in_global_replication_group 
@GlobalReplicationGroupId='{{ GlobalReplicationGroupId }}' --required, 
@NodeGroupCount='{{ NodeGroupCount }}' --required, 
@ApplyImmediately='{{ ApplyImmediately }}' --required, 
@region='{{ region }}' --required, 
@RegionalConfigurations='{{ RegionalConfigurations }}'
;

rebalance_slots_in_global_replication_group

Redistribute slots to ensure uniform distribution across existing shards in the cluster.

EXEC aws.elasticache.global_replication_groups.rebalance_slots_in_global_replication_group 
@GlobalReplicationGroupId='{{ GlobalReplicationGroupId }}' --required, 
@ApplyImmediately='{{ ApplyImmediately }}' --required, 
@region='{{ region }}' --required
;