Quickstart: Create an Azure Cosmos DB for MongoDB vCore cluster by using a Bicep template

APPLIES TO: MongoDB vCore

In this quickstart, you create a new Azure Cosmos DB for MongoDB vCore cluster. This cluster contains all of your MongoDB resources: databases, collections, and documents. The cluster provides a unique endpoint for various tools and SDKs to connect to Azure Cosmos DB and perform everyday operations.

Prerequisites

• An Azure account with an active subscription. Create an account for free.

Review the Bicep file

The Bicep file used in this quickstart is from Azure Quickstart Templates.

@description('Azure Cosmos DB MongoDB vCore cluster name')
@maxLength(44)
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@2022-10-15-preview' = {
  name: clusterName
  location: location
  properties: {
    administratorLogin: adminUsername
    administratorLoginPassword: adminPassword
    nodeGroupSpecs: [
        {
            kind: 'Shard'
            shardCount: 1
            sku: 'M40'
            diskSizeGB: 128
            enableHa: false
        }
    ]
  }
}

resource firewallRules 'Microsoft.DocumentDB/mongoClusters/firewallRules@2022-10-15-preview' = {
  parent: cluster
  name: 'AllowAllAzureServices'
  properties: {
    startIpAddress: '0.0.0.0'
    endIpAddress: '0.0.0.0'
  }
}

Note

Kindly note that in the above code, shardGroupSpecs is called nodeGroupSpecs.

Two Azure resources are defined in the Bicep file:

• Microsoft.DocumentDB/mongoclusters: Creates an Azure Cosmos DB for MongoDB vCore cluster.
  • Microsoft.DocumentDB/mongoClusters/firewallRules: Creates firewall rules for the Azure Cosmos DB for MongoDB vCore cluster.

Deploy the Bicep file

Create an Azure Cosmos DB for MongoDB vCore cluster by using the Bicep template.

Azure CLI

1. Create shell variables for resourceGroupName, and location

   # Variable for resource group name and location
   resourceGroupName="msdocs-cosmos-quickstart-rg"
   location="eastus"
   

2. If you haven't already, sign in to the Azure CLI using the az login command.

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

   az group create \
       --name $resourceGroupName \
       --location $location
   

4. 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 $resourceGroupName \
       --template-file 'main.bicep'
   

   Tip

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

   az deployment group create \
       --resource-group $resourceGroupName \
       --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"
       }
     }
   }
   

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

Azure PowerShell

1. Create shell variables for RESOURCE_GROUP_NAME, and LOCATION

   # Variable for resource group name and location
   $RESOURCE_GROUP_NAME = "msdocs-cosmos-quickstart-rg"
   $LOCATION = "East US"
   

2. If you haven't already, sign in to Azure PowerShell using the Connect-AzAccount cmdlet.

3. Use the New-AzResourceGroup cmdlet to create a new resource group in your subscription.

   $parameters = @{
       Name = $RESOURCE_GROUP_NAME
       Location = $LOCATION
   }
   New-AzResourceGroup @parameters
   

4. Use New-AzResourceGroupDeployment to deploy the bicep template. You're then prompted to enter a value for the adminUsername and adminPassword parameters.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       TemplateFile = "main.bicep"
   }
   New-AzResourceGroupDeployment @parameters
   

   Tip

   Alternatively, use the -TemplateParameterFile option to pass in a parameters file with pre-defined values.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       TemplateFile = "main.bicep"
       TemplateParameterFile = "main.parameters.json"
   }
   New-AzResourceGroupDeployment @parameters
   

   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"
       }
     }
   }
   

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

Review deployed resources

List the resources deployed by the Bicep template to your target resource group.

Azure CLI

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

   az resource list \
       --resource-group $resourceGroupName \
       --location $location \
       --output tsv
   

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:

   Name                  ResourceGroup                Location    Type                                Status
   --------------------  ---------------------------  ----------  ----------------------------------  --------
   msdocs-sz2dac3xtwzzu  msdocs-cosmos-quickstart-rg  eastus      Microsoft.DocumentDB/mongoClusters
   

Azure PowerShell

1. Use Get-AzResource to get a list of resources in your resource group.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   Get-AzResource @parameters
   

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:

   Name              : msdocs-sz2dac3xtwzzu
   ResourceGroupName : msdocs-cosmos-quickstart-rg
   ResourceType      : Microsoft.DocumentDB/mongoClusters
   Location          : eastus
   ResourceId        : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-cosmos-quickstart-rg/providers/Microsoft.DocumentDB/mongoClusters/msdocs-sz2dac3xtwzzu
   Tags              : 
   

Clean up resources

When you're done with your Azure Cosmos DB for MongoDB vCore cluster, you can delete the Azure resources you created so you don't incur more charges.

Azure CLI

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

   az group delete \
       --name $resourceGroupName
   

Azure PowerShell

1. Use Remove-AzResourceGroup to remove the resource group from your subscription.

   $parameters = @{
       Name = $RESOURCE_GROUP_NAME
   }
   Remove-AzResourceGroup @parameters
   

Next step

In this guide, you learned how to create an Azure Cosmos DB for MongoDB vCore cluster. You can now migrate data to your cluster.

Migrate data to Azure Cosmos DB for MongoDB vCore