Scaling and configuring Azure Cosmos DB for MongoDB vCore cluster

2025-08-29
Applies to: ✅ MongoDB (vCore)

Azure Cosmos DB for MongoDB vCore provides seamless scalability and in-region high availability (HA). This document serves as a quick guide for developers who want to learn how to scale and configure their clusters.

Prerequisites

An existing Azure Cosmos DB for MongoDB (vCore) cluster.
- If you don't have an Azure subscription, create an account for free.
- If you have an existing Azure subscription, create a new Azure Cosmos DB for MongoDB vCore cluster.

The latest version of the Azure CLI in Azure Cloud Shell.
- If you prefer to run CLI reference commands locally, sign in to the Azure CLI by using the az login command.

Scale cluster compute

The cluster tier allows you to configure number of vCores and amount of RAM on your cluster's physical shards. You can change the cluster tier to suit your needs at any time without interruption. For example, you can increase from M50 to M60 or decrease M50 to M40.

On the cluster sidebar, under Settings, select Scale.
To change the cluster tier, select the new tier from the drop-down menu.
Select Save to persist your change.

To scale cluster compute tier up or down, update the existing cluster with an update operation by changing the MXXX value in the compute.tier property.

az resource update \
  --resource-type "Microsoft.DocumentDB/mongoClusters" \
  --name "<cluster-name>" \
  --resource-group "<resource-group>" \
  --set properties.compute.tier="<compute-tier>"

You can use the Azure REST API directly or wrapped into az rest from Azure CLI environment.

Use this command to change cluster compute tier:

az rest \
   --method "PATCH" \
   --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>?api-version=2025-07-01-preview" \
   --body "{\"location\":\"<cluster-region>\",\"properties\":{\"compute\":{\"tier\":\"<compute-tier>\"}}}"

Tip

If you're using the Azure Cloud Shell, you can upload/download files directly to the shell. For more information, see managed files in Azure Cloud Shell.

Note

Downgrade from regular compute tier to a burstable tier isn't supported.

Increase storage size

You can increase the storage size to give your database more room to grow. For example, you can increase the storage from 128 GiB to 256 GiB.

To increase the storage size, select the new size from the drop-down menu.
Select Save to persist your change.

To increase cluster storage size, update the existing cluster with an update operation by increasing the value in the storage.sizeGb property. Supported storage sizes are listed on the supported storage page.
```
az resource update \
  --resource-type "Microsoft.DocumentDB/mongoClusters" \
  --name "<cluster-name>" \
  --resource-group "<resource-group>" \
  --set properties.storage.sizeGb="<new-size-in-GiB>"
```

You can use the Azure REST API directly or wrapped into az rest from Azure CLI environment.

Use this command to change cluster compute tier:

az rest \
   --method "PATCH" \
   --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>?api-version=2025-07-01-preview" \
   --body "{\"location\":\"<cluster-region>\",\"properties\":{\"storage\":{\"sizeGb\":\"<new-size-in-GiB>\"}}}"

Tip

If you're using the Azure Cloud Shell, you can upload/download files directly to the shell. For more information, see managed files in Azure Cloud Shell.

Important

Storage size can only be increased, not decreased.

Enable or disable high availability

You can enable or disable in-region high availability (HA) to suit your needs. In-region HA avoids database downtime by maintaining replica shards of every primary shard in a cluster. If a primary shard goes down, incoming connections are automatically redirected to its replica shard, ensuring that there's minimal downtime.

To enable or disable in-region HA, toggle the checkbox option.
Select Save to persist your change.

To enable in-region high availability on the cluster, update the existing cluster with an update operation by setting the value in the highAvailability.targetMode property to ZoneRedundantPreferred.

az resource update \
  --resource-type "Microsoft.DocumentDB/mongoClusters" \
  --name "<cluster-name>" \
  --resource-group "<resource-group>" \
  --set properties.highAvailability.targetMode="ZoneRedundantPreferred"

To disable in-region high availability on the cluster, update the existing cluster with an update operation by setting the value in the highAvailability.targetMode property to Disabled.

az resource update \
  --resource-type "Microsoft.DocumentDB/mongoClusters" \
  --name "<cluster-name>" \
  --resource-group "<resource-group>" \
  --set properties.highAvailability.targetMode="Disabled"

You can use the Azure REST API directly or wrapped into az rest from Azure CLI environment.

Use this command to enable in-region high availability on the cluster:

az rest \
   --method "PATCH" \
   --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>?api-version=2025-07-01-preview" \
   --body "{\"location\":\"<cluster-region>\",\"properties\":{\"highAvailability\":{\"targetMode\":\"ZoneRedundantPreferred\"}}}"

Use this command to disable in-region high availability on the cluster:

az rest \
   --method "PATCH" \
   --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>?api-version=2025-07-01-preview" \
   --body "{\"location\":\"<cluster-region>\",\"properties\":{\"highAvailability\":{\"targetMode\":\"Disabled\"}}}"

Increase the number of physical shards

Important

Add physical shard and data rebalancing in Azure Cosmos DB for MongoDB vCore is currently in preview. This preview version is provided without a service level agreement, and it isn't recommended for production workloads. Some features are unsupported or have limited capabilities.

When a database grows beyond the capacity of a single physical shard cluster, you can either increase the storage size or add more physical shards. After a new physical shard is added to the cluster, you must perform a cluster rebalancing operation to redistribute data across the shards. Each physical shard in a cluster always has the same compute and storage configuration.

To add physical shards, select new shard count from the list.
Select Save to persist your change.
Select Continue in the pop-up window to persist your change.

To add a physical shard to the cluster, update the existing cluster with an update operation by increasing the value for the sharding.shardCount property by one.
```
az resource update \
  --resource-type "Microsoft.DocumentDB/mongoClusters" \
  --name "<cluster-name>" \
  --resource-group "<resource-group>" \
  --set properties.sharding.shardCount="<current-shard-count-plus-one>"
```
Note

You can add only one physical shard at a time. If you need to add more than one physical shard to the cluster, you need to do it sequentially.

You can use the Azure REST API directly or wrapped into az rest from Azure CLI environment.

Use this command to add a physical shard to the cluster:

az rest \
   --method "PATCH" \
   --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>?api-version=2025-07-01-preview" \
   --body "{\"location\":\"<cluster-region>\",\"properties\":{\"sharding\":{\"shardCount\":\"<current-shard-count-plus-one>\"}}}"

Note

You can add only one physical shard at a time. If you need to add more than one physical shard to the cluster, you need to do it sequentially.

If you need more than 10 physical shards on your cluster, open an Azure support request.

Rebalance data

After a physical shard is added to a cluster, or if multishard cluster has uneven storage usage across its physical shards, data rebalancing redistributes data between shards without any downtime.

In preview, data rebalancing needs to be enabled on cluster:

In the Azure portal, open cluster properties.
Under Settings on the Features page, select Rebalancer for multishard clusters.
In the Rebalancer for multishard clusters panel, select Enable.

To initiate data rebalancing, connect to the cluster using a management tool such as the Mongo shell.

Start the rebalancer with the sh.startBalancer() command.
Check the rebalancer status using sh.isBalancerRunning().
Stop the rebalancer with the sh.stopBalancer() command.

Note

The duration of the rebalancing process depends on the volume of data being moved between physical shards. The operation is performed online and doesn't impact cluster availability or functionality.

Next steps

In this guide, we showed that scaling and configuring your Cosmos DB for MongoDB vCore cluster in the Azure portal is a straightforward process. The Azure portal includes the ability to adjust the cluster tier, increase storage size, enable or disable high availability, and add physical shards without any downtime.

Restore an Azure Cosmos DB for MongoDB vCore cluster

Share via

Scaling and configuring Azure Cosmos DB for MongoDB vCore cluster

Prerequisites

Scale cluster compute

Increase storage size

Enable or disable high availability

Increase the number of physical shards

Rebalance data

Next steps

Feedback

Additional resources