Edit

Share via

Manage cross-region replication on your Azure Cosmos DB for MongoDB vCore cluster

  • Article

APPLIES TO: MongoDB vCore

Azure Cosmos DB for MongoDB vCore allows continuous data streaming to a replica cluster in another Azure region. That capability provides cross-region disaster recovery (DR) protection and read scalability across the regions. This document serves as a quick guide for developers who want to learn how to manage cross-region replication for their clusters.

Prerequisites

Enable cross-region replication

To enable cross-region replication on a new cluster during cluster creation, follow these steps:

  1. Follow the steps to start cluster creation and complete the Basics tab for a new Azure Cosmos DB for MongoDB vCore cluster.
  2. On the Global distribution tab, select Enable for the Read replica in another region.
  3. Provide a replica cluster name in the Read replica name field.
  4. Select a region in the Read replica region. The replica cluster is hosted in the selected Azure region.
  5. (optionally) Select desired network access settings for the cluster on the Networking tab.
  6. On the Review + create tab, review cluster configuration details, and then select Create.

Note

The replica cluster is created in the same Azure subscirption and resource group as its primary cluster.

To enable cross-region replication on a new cluster at any time after cluster creation, follow these steps:

  1. Follow the steps to create a new Azure Cosmos DB for MongoDB vCore cluster.
  2. Skip Global distribution tab. This tab is used to create a cluster replica during primary cluster provisioning.
  3. Once cluster is created, on the cluster sidebar, under Settings, select Global distribution.
  4. Select Add new read replica.
  5. Provide a replica cluster name in the Read replica name field.
  6. Select a region in the Read replica region. The replica cluster is hosted in the selected Azure region.
  7. Verify your selection and select the Save button to confirm replica creation.

To make the replica cluster accessible for read operations, adjust its networking settings by configuring firewall rules for public access or by adding private endpoints for secure, private access.

Promote a replica

To promote a cluster replica to a read-write cluster, follow these steps:

  1. Select the cluster replica you would like to promote in the portal.
  2. On the cluster sidebar, under Settings, select Global distribution.
  3. On the Global distribution page, select Promote.
  4. On the Promote <cluster name> screen, double check the cluster replica's name, read the warning text, and select Promote.

After the cluster replica is promoted, it becomes a readable and writable cluster. If high availability (HA) is enabled on the primary (read-write) cluster, it needs to be re-enabled on the replica cluster after promotion.

Check cluster replication role and replication region

To check replication role of a cluster, follow these steps:

  1. Select an existing Azure Cosmos DB for MongoDB vCore cluster.
  2. Select Overview page.
  3. Check Read region (on the primary cluster) or Write region (on the replica cluster) value.

If Read region value is Not enabled, this cluster has cross-region replication disabled.

Disable cross-region replication

To disable cross-region replication, follow these steps:

  1. Select the Azure Cosmos DB for MongoDB vCore replica cluster.
  2. Select Overview.
  3. Confirm that it's a replica cluster.
  4. In the Azure portal, on the Overview page for the replica cluster, select Delete.
  5. On the Delete <replica name> screen, read the warning text, and enter cluster's name in the Confirm the account name field.
  6. Select Delete to confirm deletion of the replica.

If you need to delete the primary and replica clusters, you would need to delete the replica cluster first.

Use connection strings

You can connect to the cluster replica as you would to a regular read-write cluster. Follow these steps to get the connection strings for different cases:

  1. Select the primary cluster or its cluster replica in the portal.
  2. On the cluster sidebar, under Settings, select Connection strings.
  3. Copy the self connection string for currently selected cluster to connect to that cluster.
  4. (optionally, on the primary cluster only) Copy the global read-write connection string that always points to the cluster available for writes.

Screenshot of the cluster connection strings an Azure Cosmos DB for MongoDB (vCore) cluster including global read-write connection string and self connection string.

Self connection strings are preserved after the cluster replica promotion. You can continue to use either string or global read-write connection string for read operations. If you use self connection string for write operations, you need to update connection string in your application to point to the promoted replica cluster to continue writes to the database after promotion is completed.

Related content