Working with cross-region replication

Note:

• If you've installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update. You need at least gcloud CLI version 488.0.0 to manage cross-region replication for Memorystore.
• In order to create a secondary cluster, you must have a service network policy in the region where you want the secondary to be located. For more information about service network policies, see Networking.

This page describes how to use cross-region replication by creating and working with secondary clusters.

For a conceptual overview of cross-region replication, see About cross-region replication.

Create a secondary cluster

When you create a secondary cluster, Memorystore for Redis Cluster copies and applies some of the primary cluster settings as secondary cluster settings. For more information, see Cluster settings.

To create a Memorystore for Redis Cluster secondary cluster, run the clusters create command:

gcloud

gcloud redis clusters create SECONDARY_CLUSTER_ID \
--project=PROJECT_ID \
--region=SECONDARY_CLUSTER_REGION \
--cross-cluster-replication-role=secondary \
--network=NETWORK \
--primary-cluster=PRIMARY_CLUSTER_RESOURCE_PATH

Replace the following:

• SECONDARY_CLUSTER_ID is the ID of the secondary cluster you're creating. The ID must be 1 to 63 characters and use only lowercase letters, numbers, or hyphens. It must start with a lowercase letter and end with a lowercase letter or number.
• PROJECT_ID is the ID of the project where you want to create the secondary cluster. This is the same project where your primary cluster is located.
• SECONDARY_CLUSTER_REGION is region where you want the secondary cluster placed.
• NETWORK is the network used to create your instance. It must use the format: projects/NETWORK_PROJECT_ID/global/networks/NETWORK_ID. The network ID used here must match the network ID used by the service connection policy. Otherwise, the create operation fails.
• PRIMARY_CLUSTER_RESOURCE_PATH is the path of your primary cluster. For example, projects/my-project/locations/us-central1/clusters/my-redis-cluster. You can choose any cluster in your project to be the primary, as long as it's not already a secondary cluster.

For example:

gcloud redis clusters create my-secondary-cluster \
--project=my-project \
--region=asia-east1 \
--cross-cluster-replication-role=secondary \
--network=projects/my-project/global/networks/default
--primary-cluster=projects/my-project/locations/us-central1/clusters/my-redis-cluster

View a secondary cluster

This section shows you how to view information about your secondary cluster, including a membership field that lists the primary and secondary clusters in the replication group.

To see information about a secondary cluster, run the clusters describe command:

gcloud

gcloud redis clusters describe SECONDARY_CLUSTER_ID \
--region=SECONDARY_CLUSTER_REGION \

Replace the following:

• SECONDARY_CLUSTER_ID is the ID of the primary cluster.
• SECONDARY_CLUSTER_REGION is the region where the secondary cluster is located.

Perform a switchover

A switchover lets you reverse the roles of your primary and secondary cluster.

Note: For the best outcomes in saving application writes, you should read and follow the instructions at Switchover best practices before performing a switchover.

To perform a switchover, run the clusters switchover command:

gcloud

gcloud redis clusters switchover SECONDARY_CLUSTER_ID \
--project=PROJECT_ID \
--region=SECONDARY_CLUSTER_REGION \

Replace the following:

• SECONDARY_CLUSTER_ID is the ID of the secondary cluster to switchover.
• PROJECT_ID is your project ID.
• SECONDARY_CLUSTER_REGION is the region where your secondary cluster is located.

Detach a secondary cluster

Detaching a secondary cluster from its primary cluster makes it a fully functional independent cluster that allows both reads and writes. For more information, see How to work with cross-region replication.

The two options shown in this section accomplish the same task of detaching secondary clusters from the primary. However, the instructions for Detaching secondary clusters (option 2) are helpful if a secondary cluster is unavailable, and you would like to detach it.

Detach secondary clusters (option 1)

The following command shows you how to detach a secondary cluster by specifying the secondary cluster that will be detached:

gcloud

gcloud redis clusters detach SECONDARY_CLUSTER_ID \
--project=PROJECT_ID \
--region=SECONDARY_CLUSTER_REGION

Replace the following:

• SECONDARY_CLUSTER_ID is the ID of the secondary cluster to detach.
• PROJECT_ID is your project ID.
• SECONDSARY_CLUSTER_REGION is the region where your secondary cluster is located.

Detach secondary clusters (option 2)

The following command shows you how to detach secondaries by providing the name of the primary cluster, and specifying which secondary clusters to detach:

gcloud

gcloud redis clusters detach-secondaries PRIMARY_CLUSTER_ID \
--clusters-to-detach=SECONDARY_CLUSTERS \
--project=PROJECT_ID \
--region=PRIMARY_CLUSTER_REGION

Replace the following:

• PRIMARY_CLUSTER_ID is the ID of the primary cluster.
• SECONDARY_CLUSTERS are the secondary clusters to detach. You can detach one or more clusters. Use a comma separated list if providing more than one secondary to detach. Specified secondary clusters must use the format projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID.
• PROJECT_ID is your project ID.
• PRIMARY_CLUSTER_REGION is the region where your primary cluster is located.

For example:

gcloud redis clusters detach-secondaries my-redis-cluster \
--clusters-to-detach=projects/my-project/locations/us-west4/clusters/my-secondary-cluster-1,projects/my-project/locations/asia-southeast2/clusters/my-secondary-cluster-2  \
--project=my-project \
--region=us-central1

Update cluster settings

This section provides links to updating cluster settings. The process for updating cluster settings is different depending on the settings you want to modify. For details about how settings can be changed, see Cluster settings.

Set on primary

The following settings must be changed on the primary, and the update is synced to the secondary:

• Scale instance capacity
• Redis engine configurations
• Deletion protection
• Persistence mode

Set locally

These settings can only be applied locally to your chosen cluster:

• Zone distribution configuration
• Scale replica count.
• Maintenance windows.

Delete clusters that use cross-region replication

This section explains how to delete primary and secondary clusters that use cross-region replication.

Delete primary clusters

To delete a primary cluster, first you must detach or delete all secondary clusters. Next, follow the instructions at Delete instances to delete the cluster. To protect against accidental deletion, you cannot delete primaries and secondaries in one command.

Delete secondary clusters

To delete secondary clusters, follow the instructions at Delete instances, replacing CLUSTER_ID with your secondary cluster ID.