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

Article
09/14/2024

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 a trial subscription.

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
Azure PowerShell

Create shell variables for resourceGroupName, and location

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

If you haven't already, sign in to the Azure CLI using the az login command.
Use the az group create command to create a new resource group in your subscription.
```
az group create \
    --name $resourceGroupName \
    --location $location
```

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

Wait for the deployment operation to complete before moving on.

Create shell variables for RESOURCE_GROUP_NAME, and LOCATION

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

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

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

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

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

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
Azure PowerShell

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

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

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  chinaeast      Microsoft.DocumentDB/mongoClusters

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

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

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          : chinaeast
ResourceId        : /subscriptions/abcdef01-2345-6789-0abc-def012345678/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
Azure PowerShell

Use az group delete to remove the resource group from your subscription.
```
az group delete \
    --name $resourceGroupName
```

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