Manage an Azure Cosmos account using the Azure portal

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

This article describes how to manage various tasks on an Azure Cosmos account using the Azure portal.

Tip

Azure Cosmos DB can also be managed with other Azure management clients including Azure PowerShell, Azure CLI, Azure Resource Manager templates, and Bicep.

Create an account

  1. From the Azure portal menu or the Home page, select Create a resource.

  2. On the New page, search for and select Azure Cosmos DB.

  3. On the Azure Cosmos DB page, select Create.

  4. In the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    Setting Value Description
    Subscription Subscription name Select the Azure subscription that you want to use for this Azure Cosmos account.
    Resource Group Resource group name Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Account Name A unique name Enter a name to identify your Azure Cosmos account. Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    The name can only contain lowercase letters, numbers, and the hyphen (-) character. It must be between 3-44 characters in length.
    API The type of account to create Select Core (SQL) to create a document database and query by using SQL syntax.

    The API determines the type of account to create. Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Currently, you must create a separate account for each API.

    Learn more about the SQL API.
    Location The region closest to your users Select a geographic location to host your Azure Cosmos DB account. Use the location that is closest to your users to give them the fastest access to the data.
    Capacity mode Provisioned throughput or Serverless Select Provisioned throughput to create an account in provisioned throughput mode. Select Serverless to create an account in serverless mode.
    Apply Azure Cosmos DB free tier discount Apply or Do not apply With Azure Cosmos DB free tier, you will get the first 1000 RU/s and 25 GB of storage for free in an account. Learn more about free tier.

    Note

    You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.

    The new account page for Azure Cosmos DB

  5. In the Global Distribution tab, configure the following details. You can leave the default values for the purpose of this quickstart:

    Setting Value Description
    Geo-Redundancy Disable Enable or disable global distribution on your account by pairing your region with a pair region. You can add more regions to your account later.
    Multi-region Writes Disable Multi-region writes capability allows you to take advantage of the provisioned throughput for your databases and containers across the globe.

    Note

    The following options are not available if you select Serverless as the Capacity mode:

    • Apply Free Tier Discount
    • Geo-redundancy
    • Multi-region Writes
  6. Optionally you can configure additional details in the following tabs:

    • Networking - Configure access from a virtual network.
    • Backup Policy - Configure either periodic or continuous backup policy.
    • Encryption - Use either service-managed key or a customer-managed key.
    • Tags - Tags are name/value pairs that enable you to categorize resources and view consolidated billing by applying the same tag to multiple resources and resource groups.
  7. Select Review + create.

  8. Review the account settings, and then select Create. It takes a few minutes to create the account. Wait for the portal page to display Your deployment is complete.

    The Azure portal Notifications pane

  9. Select Go to resource to go to the Azure Cosmos DB account page.

    The Azure Cosmos DB account page

Add/remove regions from your database account

Tip

When a new region is added, all data must be fully replicated and committed into the new region before the region is marked as available. The amount of time this operation takes will depend upon how much data is stored within the account. If an asynchronous throughput scaling operation is in progress, the throughput scale-up operation will be paused and will resume automatically when the add/remove region operation is complete.

  1. Sign in to Azure portal.

  2. Go to your Azure Cosmos account, and open the Replicate data globally menu.

  3. To add regions, select the hexagons on the map with the + label that corresponds to your desired region(s). Alternatively, to add a region, select the + Add region option and choose a region from the drop-down menu.

  4. To remove regions, clear one or more regions from the map by selecting the blue hexagons with check marks. Or select the "wastebasket" (🗑) icon next to the region on the right side.

  5. To save your changes, select OK.

    Add or remove regions menu

In a single-region write mode, you cannot remove the write region. You must fail over to a different region before you can delete the current write region.

In a multi-region write mode, you can add or remove any region, if you have at least one region.

Configure multiple write-regions

Open the Replicate Data Globally tab and select Enable to enable multi-region writes. After you enable multi-region writes, all the read regions that you currently have on the account will become read and write regions.

Azure Cosmos account configures multi-region writes screenshot

Enable automatic failover for your Azure Cosmos account

The Automatic failover option allows Azure Cosmos DB to failover to the region with the highest failover priority with no user action should a region become unavailable. When automatic failover is enabled, region priority can be modified. Account must have two or more regions to enable automatic failover.

  1. From your Azure Cosmos account, open the Replicate data globally pane.

  2. At the top of the pane, select Automatic Failover.

    Replicate data globally menu

  3. On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. Select Save.

    Automatic failover portal menu

Set failover priorities for your Azure Cosmos account

After a Cosmos account is configured for automatic failover, the failover priority for regions can be changed.

Important

You cannot modify the write region (failover priority of zero) when the account is configured for automatic failover. To change the write region, you must disable automatic failover and do a manual failover.

  1. From your Azure Cosmos account, open the Replicate data globally pane.

  2. At the top of the pane, select Automatic Failover.

    Replicate data globally menu

  3. On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. To modify the failover priority, drag the read regions via the three dots on the left side of the row that appear when you hover over them.

  5. Select Save.

    Automatic failover portal menu

Perform manual failover on an Azure Cosmos account

Important

The Azure Cosmos account must be configured for manual failover for this operation to succeed.

Note

If you perform a manual failover operation while an asynchronous throughput scaling operation is in progress, the throughput scale-up operation will be paused. It will resume automatically when the failover operation is complete.

  1. Go to your Azure Cosmos account, and open the Replicate data globally menu.

  2. At the top of the menu, select Manual Failover.

    Replicate data globally menu

  3. On the Manual Failover menu, select your new write region. Select the check box to indicate that you understand this option changes your write region.

  4. To trigger the failover, select OK.

    Manual failover portal menu

Next steps

For more information and examples on how to manage the Azure Cosmos account as well as database and containers, read the following articles: