Working with cross-region replication

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.

Before you begin

  • The Google Cloud project you are using must have been enabled to access AlloyDB.
  • You must have one of these IAM roles in the Google Cloud project you are using:
    • roles/alloydb.admin (the AlloyDB Admin predefined IAM role)
    • roles/owner (the Owner basic IAM role)
    • roles/editor (the Editor basic IAM role)

    If you don't have any of these roles, contact your Organization Administrator to request access.

Create a secondary cluster

When you create a secondary cluster, AlloyDB copies and applies some of the primary cluster's configuration onto the secondary cluster. AlloyDB does not copy read pools, encryption configuration, point-in-time recovery (PITR), and backup configuration onto the secondary cluster.

If you update the primary cluster's configuration after you create the secondary cluster, the changes are not available on the secondary cluster. If you want the secondary cluster to have the latest updates, you must first delete the current secondary cluster and then create another secondary cluster.

To create an AlloyDB secondary cluster and secondary instance, follow these steps:

Console

  1. In the Google Cloud console, go to the Clusters page.

    Go to Clusters

  2. Click a cluster in the Resource Name column.

  3. On the Overview page, click Create secondary cluster.

  4. Configure your secondary cluster:

    1. In the Cluster ID field, enter a resource ID for your secondary cluster.
    2. Select a region for your secondary cluster that is different from the primary cluster region.
    3. Select the default Google-managed encryption or a customer-managed key (CMEK) as an encryption method to encrypt your secondary cluster.

    If you want to encrypt this cluster using CMEK key, follow these steps:

    1. Click Advanced encryption options.
    2. Select Customer-managed encryption key (CMEK).
    3. Select a customer-managed key from the menu that appears.

      The Google Cloud console limits this list to keys within the same Google Cloud project and region as the new cluster.

      To use a key that is not on this list, follow these steps:

      1. Click Don't see your key? Enter key resource name.
      2. Enter the resource name in the Key resource name field.
      3. Click Save.
      4. Click Continue.

    Using CMEK key with AlloyDB requires some additional setup. For more information, see Use CMEK.

    If the associated primary instance is encrypted with a CMEK key, you must also encrypt its secondary cluster with a CMEK key.

  5. Configure your secondary instance:

    1. In the Instance ID field, enter a resource ID for your secondary instance. The resource ID must be unique within a cluster.
  6. Click Create cluster.

gcloud

 gcloud beta alloydb clusters create-secondary SECONDARY_CLUSTER_ID \
 --region=REGION_ID \
 --primary-cluster=PRIMARY_CLUSTER_ID \
 gcloud beta alloydb instances create-secondary SECONDARY_INSTANCE_ID \
 --cluster=SECONDARY_CLUSTER_ID \
 --region=REGION_ID \

Replace the following:

  • SECONDARY_CLUSTER_ID: The ID of the secondary cluster that you want to create.
  • SECONDARY_INSTANCE_ID: The ID of the secondary instance that you want to create.
  • REGION_ID: The ID of the secondary cluster's region—for example, us-central1.
  • PROJECT_ID: The ID of the secondary cluster's project.
  • PRIMARY_CLUSTER_ID: The ID of the primary cluster that the secondary cluster is associated with.
  • SECONDARY_CLUSTER_ID: The ID of the secondary cluster that the secondary instance is associated with.

View a secondary cluster

To view detailed information about an AlloyDB secondary cluster, follow these steps:

  1. In the Google Cloud console, go to the Clusters page.

    Go to Clusters

  2. Click a secondary cluster in the Resource Name column.

  3. On the Overview page, view all details about your secondary cluster.

Promote a secondary cluster

Before you promote a secondary cluster, perform the following to verify that the secondary cluster has applied all transactions received from the primary cluster:

  1. Stop all writes to the primary cluster.
  2. Check the replication status of the secondary cluster by completing the following steps:

    1. In the Google Cloud console, go to the Clusters page.

      Go to Clusters

    2. Select the secondary cluster that you want to promote.

    3. From the left navigation pane, click Monitoring.

      The Monitoring page displays the Cross-region replication lag and replication state.

    Replication lag is the time taken in milliseconds for replication from the primary instance to secondary instance.

    Replication state indicates whether replication is actively streaming logs from the primary instance to secondary instance. The possible values include running, stopped, and error.

  3. Verify that the replication state for the secondary instance is Replication state = Running. To avoid data loss, you must wait until the replication lag reported by the replay_lag metric is 0.

To promote a secondary cluster to primary cluster, follow these steps:

Console

  1. In the Google Cloud console, go to the Clusters page.

    Go to Clusters

  2. In the Resource Name column, click a secondary cluster that you want to promote as the primary cluster.

  3. On the Overview page, click Promote cluster.

  4. In the dialog that appears, enter your secondary cluster ID to confirm that you want to promote the cluster.

  5. Click Promote.

    After the cluster is promoted, the Type: Secondary cluster (highly available) field on the Overview page is updated to Type: Highly available with read pools.

gcloud

 gcloud beta alloydb clusters promote SECONDARY_CLUSTER_ID \
 --region=REGION_ID \
 --project=PROJECT_ID \

Replace the following:

  • SECONDARY_CLUSTER_ID: The ID of the secondary cluster that you want to promote.
  • REGION_ID: The ID of the secondary cluster's region—for example, us-central1.
  • PROJECT_ID: The ID of the secondary cluster's project.

Add read pools in a promoted cluster

To add a read pool instance to a promoted cluster, follow these steps:

  1. In the Google Cloud console, go to the Clusters page.

    Go to Clusters

  2. In the Resource Name column, click a secondary cluster that you want to promote as the primary cluster.

  3. On the Overview page, go to the Instances in your cluster section, and click Add read pool.

  4. Configure your read pool instance:

    1. In the Read pool instance ID field, enter an ID for the read pool instance.
    2. In the Node count field, enter a node count. The number of nodes in a read pool instance determines the instance's overall computing capacity. You can have a maximum of 20 nodes across all the read pool instances in a cluster.
    3. Select a machine type.
    4. Optional: Set custom flags to your instance. For each flag, do the following:

      1. Click Add flag.
      2. Select a flag from the New database flag list.
      3. Provide a value for the flag.
      4. Click Done.
  5. Click Add read pool.

What's Next