Update regions for an Azure Cosmos DB account by using PowerShell

APPLIES TO: NoSQL MongoDB Cassandra Gremlin Table

This PowerShell script updates the Azure regions that an Azure Cosmos DB account uses. You can use this script to add an Azure region or change region failover order.

Prerequisites

• You need an existing Azure Cosmos DB account in an Azure resource group.

• The script requires Azure PowerShell Az 5.4.0 or later. Run Get-Module -ListAvailable Az to list your installed versions. If you need to install PowerShell, see Install Azure PowerShell module.

• Run Connect-AzAccount -Environment AzureChinaCloud to sign in to Azure.

Sample script

The Update-AzCosmosDBAccountRegion command updates Azure regions for an Azure Cosmos DB account. The command requires a resource group name, an Azure Cosmos DB account name, and a list of Azure regions in desired failover order.

In this script, the Get-AzCosmosDBAccount command gets the Azure Cosmos DB account you specify. New-AzCosmosDBLocationObject creates an object of type PSLocation. Update-AzCosmosDBAccountRegion uses the PSLocation parameter to update the account regions.

• If you add a region, don't change the first failover region in the same operation. Change failover priority order in a separate operation.
• You can't modify regions in the same operation as changing other Azure Cosmos DB account properties. Do these operations separately.

This sample uses a API for NoSQL account. To use this sample for other APIs, copy the related properties and apply them to your API-specific script.

# Reference: Az.CosmosDB | https://learn.microsoft.com/powershell/module/az.cosmosdb
# --------------------------------------------------
# Purpose
# Update Cosmos DB account: Add an Azure region (location)
# NOTE: if adding a region to a single master account, do not change the first 
# region in the same operation. Change failover priority order in a
# separate operation.
# NOTE: this operation will return, but account updates may still be
# occurring. Check the account or Resource Group's activity log for status.
# --------------------------------------------------
# Variables - ***** SUBSTITUTE YOUR VALUES *****
$resourceGroupName = "myResourceGroup" # Resource Group must already exist
$accountName = "myaccount" # Must be all lower case

# Regions ordered by failover priority, with each indicating whether AZ-enabled
# Region AZ status can be checked at https://azure.microsoft.com/global-infrastructure/regions/
$locations = @(
    @{name = "China East"; azEnabled = $true};
    @{name = "China North"; azEnabled = $false};
)
# --------------------------------------------------

Write-Host "Get Cosmos DB account"
$account = Get-AzCosmosDBAccount -ResourceGroupName $resourceGroupName -Name $accountName

$i = 0
$locationObjects = @()

ForEach ($location in $locations) {
    $locationObjects += New-AzCosmosDBLocationObject -LocationName $location.name -IsZoneRedundant $location.azEnabled -FailoverPriority ($i++)
}

Write-Host "Update Cosmos DB account region(s)"
Update-AzCosmosDBAccountRegion -InputObject $account -LocationObject $locationObjects

Although the script returns a result, the update operation might not be finished. Check the status of the operation in the Azure portal by using the Azure Cosmos DB account Activity log.

Delete Azure resource group

If you want to delete your Azure Cosmos DB account, you can use the Remove-AzResourceGroup PowerShell command to remove its resource group. This command removes the Azure resource group and all the resources in it, including Azure Cosmos DB accounts and their containers and databases.

Remove-AzResourceGroup -ResourceGroupName "myResourceGroup"

Next steps

• Azure PowerShell documentation