Create and manage cross-region replication

This page describes how to use cross-region replication by creating and managing secondary instances.

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

Before you begin

Before you begin using cross-region replication for Memorystore for Valkey, verify the following:

  • You installed gcloud CLI, version 488.0.0 and later. To determine the latest version of your gcloud CLI, use the gcloud components update command.

  • You have a service network policy in the region where you want your secondary instances to be located. For more information about service network policies, see Networking.

Create a secondary instance

When you create a secondary instance, Memorystore for Valkey copies and applies some settings of the primary instance as secondary instance settings. For more information, see Instance settings.

To create a secondary Memorystore for Valkey instance, use the gcloud memorystore instances create command:

gcloud

gcloud memorystore instances create SECONDARY_INSTANCE_ID \
--project=PROJECT_ID \
--location=SECONDARY_REGION_NAME \
--cross-instance-replication-config-role=secondary \
--psc-auto-connections=network=NETWORK,projectId=PROJECT_ID \
--primary-instance=PRIMARY_INSTANCE_RESOURCE_PATH

Replace the following:

  • SECONDARY_INSTANCE_ID: the ID of the secondary instance that 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: the ID of the project where you want to create the secondary instance. This is the same project where your primary instance is located.
  • SECONDARY_REGION_NAME: the region where you want the secondary instance to be located.
  • NETWORK: the Virtual Private Cloud network that's used to create your instance. It must use this format: projects/NETWORK_PROJECT_ID/global/networks/NETWORK_ID. The network ID must match the network ID that the service connection policy uses. Otherwise, the create operation fails.
  • PRIMARY_INSTANCE_RESOURCE_PATH: the path of your primary instance. For example: projects/my-project/locations/us-central1/instances/my-primary-instance. You can choose any instance in your project to be the primary instance as long as it's not a secondary instance.

For example:

gcloud memorystore instances create my-secondary-instance \
--project=my-project \
--location=us-central1 \
--cross-instance-replication-config-role=secondary \
--psc-auto-connections=network=projects/my-project/global/networks/default,projectId=my-project \
--primary-instance=projects/my-project/locations/us-central1/instances/my-primary-instance

View a secondary instance

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

To see information about a secondary instance, use the gcloud memorystore instances describe command.

gcloud

gcloud memorystore instances describe SECONDARY_INSTANCE_ID \
--project=PROJECT_ID \
--location=SECONDARY_REGION_NAME

Replace the following:

  • SECONDARY_INSTANCE_ID: the ID of the secondary instance
  • PROJECT_ID: the ID of the project that contains the secondary instance
  • SECONDARY_REGION_NAME: the region where the secondary instance is located

Perform a switchover

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

To perform a switchover, use the gcloud memorystore instances update command.

gcloud

gcloud memorystore instances update SECONDARY_INSTANCE_ID \
--project=PROJECT_ID \
--location=SECONDARY_REGION_NAME \
--clear-primary-instance \
--cross-instance-replication-config-role=primary \
--cross-instance-replication-config-secondary-instances=[instance=SECONDARY_INSTANCE_RESOURCE_PATH]

Replace the following:

  • SECONDARY_INSTANCE_ID: the ID of the secondary instance that you want to promote to a primary instance by performing the switchover.
  • PROJECT_ID: the ID of the project that contains the secondary instance.
  • SECONDARY_REGION_NAME: the region where the secondary instance is located.

  • SECONDARY_INSTANCE_RESOURCE_PATH: the path of your secondary instance. For example: projects/my-project/locations/us-central1/instances/my-secondary-instance.

    If you have multiple secondary instances, then separate each instance by commas. For example: [instance=projects/my-project/locations/us-central1/instances/my-first-secondary-instance,instance=projects/my-project/locations/europe-west1/instances/my-second-secondary-instance].

Suppose you have the following instances that are contained in the my-project project:

  • instance-1: this primary instance is located in the us-east1 region.
  • instance-2: this secondary instance resides in the asia-east1 region.
  • instance-3: this secondary instance resides in the southamerica-east1 region.

You want to reverse the roles of instance-1 and instance-2 so that instance-2 is the new primary instance and instance-1 is a secondary instance.

To do this, use the following code:

gcloud memorystore instances update instance-2 \
--project=my-project \
--location=asia-east1 \
--clear-primary-instance \
--cross-instance-replication-config-role=primary \
--cross-instance-replication-config-secondary-instances=[instance=projects/my-project/locations/us-east1/instances/instance-1,instance=projects/my-project/locations/southamerica-east1/instances/instance-3]

Detach secondary instances

Detaching secondary instances from the primary instance makes them fully functional, independent instances that allow both reads and writes. For more information, see How to manage cross-region-replication.

The two options in this section accomplish the same task of detaching secondary instances from the primary instance. For guidance on which option to use, keep the following in mind:

  • To detach a single secondary instance from the primary instance, use option 1.
  • To detach multiple secondary instances from the primary instance, or to detach secondary instances that are unavailable, use option 2.

Detach a secondary instance (option 1)

To detach a secondary instance from the primary instance, use the gcloud memorystore instances update command.

gcloud

gcloud memorystore instances update SECONDARY_INSTANCE_ID \
--project=PROJECT_ID \
--location=SECONDARY_REGION_NAME \
--cross-instance-replication-config-role=none \
--clear-primary-instance

Replace the following:

  • SECONDARY_INSTANCE_ID: the ID of the secondary instance that you want to detach
  • PROJECT_ID: the ID of the project that contains the secondary instance
  • SECONDARY_REGION_NAME: the region where the secondary instance is located

Detach secondary instances (option 2)

You can also use the gcloud memorystore instances update command to either detach multiple secondary instances from the primary instance, or to detach secondary instances that are unavailable.

gcloud

gcloud memorystore instances update PRIMARY_INSTANCE_ID \
--project=PROJECT_ID \
--location=PRIMARY_REGION_NAME \
--remove-cross-instance-replication-config-secondary-instances=[instance=SECONDARY_INSTANCES] \
--cross-instance-replication-config-role=none

Replace the following:

  • PRIMARY_INSTANCE_ID: the ID of the primary instance.
  • PROJECT_ID: the ID of the project that contains the secondary instances.
  • PRIMARY_REGION_NAME: the region where the primary instance is located.
  • SECONDARY_INSTANCES: the secondary instances to detach. You can detach one or more instances. To detach multiple instances, use a comma-separated list. Any secondary instances that you specify must use the following format: projects/PROJECT_ID/locations/SECONDARY_REGION_NAME/instances/INSTANCE_ID.

For example:

gcloud memorystore instances update my-primary-instance \
--project=my-project \
--location=us-central1 \
--remove-cross-instance-replication-config-secondary-instances=[instance=projects/my-project/locations/us-west4/instances/my-secondary-instance-1,instance=projects/my-project/locations/asia-southeast2/instances/my-secondary-instance-2] \
--cross-instance-replication-config-role=none

You can also detach secondary instances from the primary instance by specifying a list of instances that you don't want to detach. Memorystore for Valkey detaches any instances that you don't include in this list.

Suppose you have the following secondary instances:

  • instance-1: this instance is located in the us-east1 region.
  • instance-2: this instance resides in the asia-east1 region.

You want to detach both secondary instances from my-primary-instance. This primary instance is located in the us-central1 region and is contained in the my-project project.

To detach the secondary instances, use the following code:

gcloud memorystore instances update my-primary-instance \
--project=my-project \
--location=us-central1 \
--cross-instance-replication-config-secondary-instances=[]
--cross-instance-replication-config-role=none

For this example, because the null [] value is assigned to the --cross-instance-replication-config-secondary-instances parameter, Memorystore for Valkey detaches all secondary instances from the primary instance.

Update instance settings

When you update the settings for your Memorystore for Valkey instance, you can change some settings only on the primary instance. Memorystore for Valkey syncs these changes to the secondary instance automatically.

You can change other settings on the primary and secondary instances independently. Memorystore for Valkey applies these changes locally, and doesn't sync them with the other instances.

Delete instances that use cross-region-replication

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

Delete primary instances

Before you can delete a primary instance, you must detach or delete all secondary instances. Then, delete the primary instance.

To protect against accidental deletion, you can't use a single command to delete both primary and secondary instances.

Delete secondary instances

To delete secondary instances, follow the instructions at Delete instances, replacing INSTANCE with the ID of your secondary instance.