Migrate Azure Cosmos DB for NoSQL to availability zone support

This guide describes how to migrate Azure Cosmos DB for NoSQL from non-availability zone support to availability support.

Using availability zones in Azure Cosmos DB has no discernible impact on performance or latency. It doesn't require any adjustments to the selected consistency mode, and also doesn't require any modification to application code.

When availability zones are enabled, Azure Cosmos DB intelligently distributes the four replicas of your data across all available zones. This ensures that, in the event of an outage in one availability zone, the account remains fully operational. In contrast, without availability zones, all replicas would be located in a single availability zone (we do not expose which), leading to potential downtime if that specific zone experiences an issue.

Enabling availability zones is a great way to increase resilience of your Cosmos DB database without introducing additional application complexities, affecting performance, or even incurring additional costs, if autoscale is also used.

Prerequisites

  • Serverless accounts can use availability zones, but this choice is only available during account creation. Existing accounts without availability zones cannot be converted to an availability zone configuration. For mission critical workloads, provisioned throughput is the recommended choice.

  • Understand that enabling availability zones is not an account-wide choice. A single Cosmos DB account can span an arbitrary number of Azure regions, each of which can independently be configured to leverage availability zones and some regional pairs may not have availability zone support. This is important, as some regions do not yet support availability zones, but adding them to a Cosmos DB account will not prevent enabling availability zones in other regions configured for that account. The billing model also reflects this possibility. For more information on SLA for Cosmos DB, see Reliability in Cosmos DB for NoSQL. To see which regions support availability zones, see Azure regions with availability zone support

Downtime requirements

When you migrate to availability zone support, a small amount of write unavailability (a few seconds) occurs when adding and removing the secondary region, as the system deliberately stops writes in order to check consistency between regions.

Migration

Because you can't enable availability zones in a region that has already been added to your account, you'll need to remove that region and add it again with availability zones enabled. To avoid any service disruption, you'll add and failover to a temporary region until the availability zone configuration is complete.

Follow the steps below to enable availability zones for your account in select regions.

  1. Add a temporary region to your database account by following steps in Add region to your database account.

  2. If your Azure Cosmos DB account is configured with multi-region writes, skip to the next step. Otherwise, perform manual failover to the temporary region by following the steps in Perform manual failover on an Azure Cosmos DB account.

  3. Remove the region for which you would like to enable availability zones by following steps in Remove region to your database account.

  4. Add back the region to be enabled with availability zones:

    1. Add region to your database account.
    2. Find the newly added region in the Write region column, and enable Availability Zone for that region.
    3. Select Save.
  5. Perform failback to the availability zone-enabled region by following the steps in Perform manual failover on an Azure Cosmos DB account.

  6. Remove the temporary region by following steps in Remove region to your database account.