Perform manual failovers to move single master write regions

To perform manual failovers and move single master write regions in Microsoft Azure Cosmos DB, you can follow a few steps. Manual failovers are useful when you need to switch the write region in case of a region-wide outage or during planned maintenance. This article will guide you through the process of performing manual failovers in Azure Cosmos DB.

Step 1: Understand Azure Cosmos DB Regions and Regions Pairing

Azure Cosmos DB is a globally distributed database service, allowing you to replicate your data to multiple regions across the world. Each region in Azure Cosmos DB represents a separate geographical location where your data is stored. Regions are grouped into region pairs, where each pair consists of a primary and secondary region.

The primary region is responsible for handling write operations, while the secondary region serves as a backup and supports read operations. By default, the primary region is the region closest to your application, providing low latency for write operations.

Step 2: Determine the Current Write Region

Before performing a manual failover, you need to determine the current write region for your Azure Cosmos DB account. To do this, you can use the Azure portal or Azure CLI.

Using Azure Portal:

1. Navigate to the Azure portal (portal.azure.com) and login with your Azure account.
2. Search for and select your Azure Cosmos DB account.
3. In the account overview page, click on the Keys blade.
4. Note down the value of the PRIMARY CONNECTION STRING field.

Using Azure CLI:

1. Open Azure CLI or Azure Cloud Shell.
2. Run the following command to get the connection string for your Azure Cosmos DB account:

az cosmosdb show --name --resource-group --query 'documentEndpoint'

Note: Replace with the name of your Azure Cosmos DB account and with the name of your resource group.

Note down the output of this command, as it provides the endpoint URL of the current write region.

Step 3: Perform the Manual Failover

Once you have identified the primary region, you can initiate the failover process to promote the secondary region as the new write region. Follow the steps below to perform the manual failover.

Using Azure Portal:

1. In the Azure portal, navigate to your Azure Cosmos DB account.
2. In the account overview page, click on the Failover blade.
3. Select the secondary region that you want to promote as the new write region and click on the Failover button.

Using Azure CLI:

1. Open Azure CLI or Azure Cloud Shell.
2. Run the following command to failover to the secondary region:

az cosmosdb failover-priority-change --name --resource-group --failover-policies ''

Note: Replace with the name of your Azure Cosmos DB account, with the name of your resource group, and with the failover policy JSON array.

The failover policy JSON array specifies the order of failover regions. Include all the regions in the failover order, separating them with commas. The first region in the list will be promoted as the new write region.

Step 4: Verify the Failover

After initiating the failover, you should verify if the write region has been successfully switched to the new region. Make the following checks:

1. If you retrieved the connection string in Step 2, update your application or service with the new primary connection string.
2. If you’re using Azure CLI, you can run the same command as Step 2 to get the new write region’s endpoint URL.

Step 5: Revert or Repeat Failover

Once the failed-over region is back online and operational, you have the option to revert the failover. Reverting the failover reinstates the original primary region as the write region.

To revert a failover, follow the same steps mentioned in Step 3 but select the original primary region instead of the secondary region.

Remember, manual failover requires careful consideration of the failover timing, network latencies, and application dependencies. It’s recommended to thoroughly test failover scenarios before implementing them in a production environment.

That concludes the process of performing manual failovers to move single master write regions in Azure Cosmos DB. By following these steps, you can ensure high availability and resilience for your applications using Azure Cosmos DB.