Quickstart: Deploy an Azure DocumentDB cluster using Bicep

In this quickstart, you deploy a new Azure DocumentDB cluster using Bicep. This quickstart provides step-by-step instructions to help you get started quickly. This cluster contains all your MongoDB resources: databases, collections, and documents. It provides a unique endpoint for tools and software development kits (SDKs) to connect to Azure DocumentDB and perform operations.

Prerequisites

• An Azure subscription

  • If you don't have an Azure subscription, create a free account

• Use the Bash environment in Azure Cloud Shell. For more information, see Get started with Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Authenticate to Azure using Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Configure environment

Set up your Azure CLI environment to manage Azure DocumentDB resources in your subscription.

1. Start in an empty directory.

2. Sign in to Azure CLI.

   az login
   

3. Check your target Azure subscription.

   az account show
   

   Note

   If you aren't connected to the subscription you expected, use this command to change your subscription:

   az account set --subscription "<subscription-name>"
   

   For more information, see manage Azure subscriptions with the Azure CLI.

Prepare the Bicep template

Create and configure a Bicep file to define the resources required for deploying an Azure DocumentDB cluster.

1. Create a new main.bicep file in your project directory.

2. Add this template to the file's content.

   @description('Cluster name')
   @minLength(8)
   @maxLength(40)
   param clusterName string = 'msdocs-${uniqueString(resourceGroup().id)}'
   
   @description('Location for the cluster.')
   param location string = resourceGroup().location
   
   @description('Username for admin user')
   param adminUsername string
   
   @secure()
   @description('Password for admin user')
   @minLength(8)
   @maxLength(128)
   param adminPassword string
   
   resource cluster 'Microsoft.DocumentDB/mongoClusters@2025-09-01' = {
     name: clusterName
     location: location
     properties: {
       administrator: {
         userName: adminUsername
         password: adminPassword
       }
       serverVersion: '8.0'
       sharding: {
         shardCount: 1
       }
       storage: {
         sizeGb: 32
       }
       highAvailability: {
         targetMode: 'Disabled'
       }
       compute: {
         tier: 'M10'
       }
     }
   }
   
   resource firewallRules 'Microsoft.DocumentDB/mongoClusters/firewallRules@2025-09-01' = {
     parent: cluster
     name: 'AllowAllAzureServices'
     properties: {
       startIpAddress: '0.0.0.0'
       endIpAddress: '0.0.0.0'
     }
   }
   

   Tip

   For more information on options using the Microsoft.DocumentDB/mongoclusters resource, see Microsoft.DocumentDB/mongoclusters documentation.

Deploy the template

Deploy the template created in the previous step using an Azure Resource Manager deployment.

1. Use the az group create command to create a new resource group in your subscription.

   az group create \
       --name "<resource-group-name>" \
       --location "<location>"
   

2. Use az deployment group create to deploy the bicep template. You're then prompted to enter a value for the adminUsername and adminPassword parameters.

   az deployment group create \
       --resource-group "<resource-group-name>" \
       --template-file 'main.bicep'
   

   Tip

   Alternatively, use the --parameters option to pass in a parameters file with predefined values.

   az deployment group create \
       --resource-group "<resource-group-name>" \
       --template-file 'main.bicep' \
       --parameters @main.parameters.json
   

   This example JSON file injects clusteradmin and P@ssw.rd values for the adminUsername and adminPassword parameters respectively.

   {
     "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "adminUsername": {
         "value": "clusteradmin"
       },
       "adminPassword": {
         "value": "P@ssw.rd"
       }
     }
   }
   

3. Wait for the deployment operation to complete before moving on.

Review deployed resources

List the Azure DocumentDB resources deployed to your resource group.

1. Use az resource list to get a list of resources in your resource group.

   az resource list \
       --resource-group "<resource-group-name>" \
       --namespace "Microsoft.DocumentDB" \
       --resource-type "mongoClusters" \
       --query "[].name" \
       --output json
   

2. In the example output, look for resources that have a type of Microsoft.DocumentDB/mongoClusters. Here's an example of the type of output to expect:

   [
     "msdocs-documentdb-example-cluster"
   ]
   

Clean up resources

When you're done with your Azure DocumentDB cluster, you can delete the Azure resources you created so you don't incur more charges.

1. Use az group delete to remove the resource group from your subscription.

   az group delete \
       --name "<resource-group-name>" \
       --yes \
       --no-wait
   

   Important

   Ensure you no longer need the resources before running this command, as it permanently deletes them.

Related content

• Connect from MongoDB Shell
• Connect from Azure Cloud Shell
• Migrate data to Azure DocumentDB