Work with cross-region replication

Console

1. In the Google Cloud console, go to the Memorystore for Valkey page.

   Memorystore for Valkey

2. Click a primary instance. The primary instance is the parent of the secondary instance that you're creating.

3. In the side panel, click the Secondary instances tab.

4. Click Add secondary instance.

5. In the Add secondary instances window, make the following changes:

   1. In the Instance ID field, enter 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, end with a lowercase letter or number, and be unique in its region.

   2. From the Region menu, select the region where you want the secondary instance to be located.

   3. In the Zonal availability section, select one of the following options:

      • If you want all of the shards and replicas of the instance to be distributed across three zones of the region where Memorystore for Valkey creates the instance, then select the Multi-zone option.

        For example, if the region you select is us-central1, and you select the Multi-zone option, then Memorystore for Valkey distributes the instance's shards and replicas across the us-central1-a, us-central1-b, and
        us-central1-c zones. In case of a zonal failure, the nodes in the instance failover to the replicas.

      • If you want all of the shards and replicas of the instance to be located in one zone of the region where Memorystore for Valkey creates the instance, select the Single zone option, and then select the zone from the Zone menu.

        By using a single zone, you reduce network costs. However, in case of a zonal failure, failover doesn't occur.

   4. From the Replicas menu, select the number of replicas (per shard) for the instance. You can have zero, one, or two replicas.

   5. From the Network menu, select a network for the instance. For more information about networking for Memorystore for Valkey, see Networking.

6. Click Add secondary instance.

gcloud

To create a secondary instance, use the gcloud memorystore instances create command.

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

Make the following replacements:

• 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, end with a lowercase letter or number, and be unique in its region.
• 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.
• REGION_ID: the ID of the region where you want the secondary instance to be located.
• NETWORK: the network used to create the 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, you can't create the secondary instance.
• PRIMARY_INSTANCE_PATH: the path of the 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

Console

1. In the Google Cloud console, go to the Memorystore for Valkey page.

   Memorystore for Valkey

2. Click the expander arrow next to a primary instance. This instance is the parent of the secondary instance about which you want to view information.

3. Click the secondary instance. Summary information about the instance appears.

gcloud

To view information about a secondary instance, including a membership field that lists the primary and secondary instances in the replication group, use the gcloud memorystore instances describe command.

gcloud memorystore instances describe INSTANCE_ID \
--project=PROJECT_ID \
--location=REGION_ID

Make the following replacements:

• INSTANCE_ID: the ID of the secondary instance
• PROJECT_ID: the ID of the project that contains the secondary instance
• REGION_ID: the ID of the region where the secondary instance is located

Console

1. In the Google Cloud console, go to the Memorystore for Valkey page.

   Memorystore for Valkey

2. Click the expander arrow next to a primary instance. This instance is the parent of the secondary instance that you want to switch over.

3. Click the secondary instance.

4. Click Promote to Primary.

5. In the Promote secondary instance to primary? dialog, enter the ID of the secondary instance, and then click Promote.

After the switchover is complete, you must reconnect your applications to the new primary instance.

gcloud

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

gcloud memorystore instances update INSTANCE_ID \
--project=PROJECT_ID \
--location=REGION_ID \
--clear-primary-instance \
--cross-instance-replication-config-role=primary \
--cross-instance-replication-config-secondary-instances=[instance=SECONDARY_INSTANCE_PATH]

Make the following replacements:

• 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.
• REGION_ID: the ID of the region where the secondary instance is located.

• SECONDARY_INSTANCE_PATH: the path of the 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]

After the switchover is complete, you must reconnect your applications to the new primary instance.

Console

1. In the Google Cloud console, go to the Memorystore for Valkey page.

   Memorystore for Valkey

2. Click a primary instance. This is the parent of the secondary instance that you're detaching from the primary instance.

3. In the side panel, click the Secondary instances tab.

4. Select the checkbox next to the ID of the secondary instance that you're detaching from the primary instance.

5. Click Detach from Primary.

6. In the Detach secondary instance? dialog, enter the ID of the secondary instance, and then click Detach.

gcloud

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

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

Replace the following:

• 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
• REGION_ID: the region where the secondary instance is located

Console

1. In the Google Cloud console, go to the Memorystore for Valkey page.

   Memorystore for Valkey

2. Click a primary instance. This is the parent of the secondary instances that you're detaching from the primary instance.

3. In the side panel, click the Secondary instances tab.

4. Select the checkboxes next to the IDs of the secondary instances that you're detaching from the primary instance.

5. Click Detach from Primary.

6. In the Detach secondary instances? dialog, do the following:

   1. Enter the IDs of the secondary instances. Use commas to separate the IDs.

   2. Click Detach.

gcloud

To detach multiple secondary instances, use the gcloud memorystore instances update command.

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

Make the following replacements:

• PRIMARY_INSTANCE_ID: the ID of the primary instance.
• PROJECT_ID: the ID of the project that contains the secondary instances.
• PRIMARY_INSTANCE_REGION_ID: the ID of the region where the primary instance is located.
• SECONDARY_INSTANCES: the secondary instances that you want to detach. Use commas to separate the instance IDs. Each secondary instance must have this format: projects/PROJECT_ID/locations/SECONDARY_INSTANCE_REGION_ID/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.