Add regions, change failover priority, trigger failover for an Azure Cosmos account using Azure CLI

APPLIES TO: SQL API Cassandra API Gremlin API Table API Azure Cosmos DB API for MongoDB

Prerequisites

  • This article requires version 2.9.1 or later of the Azure CLI. If using Azure Cloud Shell, the latest version is already installed.

Sample script

This script demonstrates three operations.

  • Add a region to an existing Azure Cosmos account.
  • Change regional failover priority (applies to accounts using automatic failover)
  • Trigger a manual failover from primary to secondary regions (applies to accounts with manual failover)

Note

Add and remove region operations on a Cosmos account cannot be done while changing other properties.

Note

This sample demonstrates using a SQL (Core) API account but these operations are identical across all database APIs in Cosmos DB.

#!/bin/bash
# Reference: az cosmosdb | https://docs.microsoft.com/cli/azure/cosmosdb
# --------------------------------------------------
#
# Region replica operations for an Azure Cosmos account
#
# Operations:
#   Add regions to an existing Cosmos account
#   Change regional failover priority (applies to accounts using automatic failover)
#   Trigger a manual failover from primary to secondary region (applies to accounts with manual failover)

# Note: Azure Comos accounts cannot include updates to regions with changes to other properties in the same operation

# Resource group and Cosmos account variables
uniqueId=$RANDOM
resourceGroupName="Group-$uniqueId"
location='westus2'
accountName="cosmos-$uniqueId" #needs to be lower case

# Create a resource group
az group create -n $resourceGroupName -l $location

# Create a Cosmos DB account with default values
# Use appropriate values for --kind or --capabilities for other APIs
az cosmosdb create -n $accountName -g $resourceGroupName

read -p "Press any key to add additional regions to this account"
az cosmosdb update \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='West US 2' failoverPriority=0 isZoneRedundant=False \
    --locations regionName='East US 2' failoverPriority=1 isZoneRedundant=False \
    --locations regionName='South Central US' failoverPriority=2 isZoneRedundant=False

read -p "Press any key to change the failover priority"
# Make South Central US the next region to fail over to instea of East US 2
az cosmosdb failover-priority-change \
    -n $accountName \
    -g $resourceGroupName \
    --failover-policies 'West US 2=0' 'South Central US=1' 'East US 2=2' 


read -p "Press any key to trigger a manual failover by changing region 0"
# Initiate a manual failover and promote East US 2 as primary write region
az cosmosdb failover-priority-change \
    -n $accountName \
    -g $resourceGroupName \
    --failover-policies 'East US 2=0' 'West US 2=1' 'South Central US=2'

Clean up deployment

After the script sample has been run, the following command can be used to remove the resource group and all resources associated with it.

az group delete --name $resourceGroupName

Script explanation

This script uses the following commands. Each command in the table links to command specific documentation.

Command Notes
az group create Creates a resource group in which all resources are stored.
az cosmosdb create Creates an Azure Cosmos DB account.
az cosmosdb update Updates an Azure Cosmos DB account (add or remove region).
az cosmosdb failover-priority-change Update failover priority or trigger failover on an Azure Cosmos DB account.
az group delete Deletes a resource group including all nested resources.

Next steps

For more information on the Azure Cosmos DB CLI, see Azure Cosmos DB CLI documentation.

All Azure Cosmos DB CLI script samples can be found in the Azure Cosmos DB CLI GitHub Repository.