Provision and manage Azure Cosmos DB resources by using Azure Resource Manager templates (ARM templates)

What are Azure Resource Manager templates?

Azure Resource Manager (ARM) templates are declarative JSON files that allow you to define and deploy Azure resources consistently. By using ARM templates, you can define the infrastructure and configuration of your resources in a human-readable and versionable format. These templates can be stored in your source control system to manage the complete lifecycle of your infrastructure alongside your application code.

Why use ARM templates with Azure Cosmos DB?

When working with Azure Cosmos DB, using ARM templates has several advantages:

• Infrastructure as Code: ARM templates enable you to treat infrastructure as code, providing a single source of truth for your resource provisioning and management. You can version, review, and rollback your infrastructure changes just like your application code.
• Consistency: ARM templates ensure that your Azure Cosmos DB resources are deployed consistently across different environments, such as development, testing, and production. By defining the desired state of your resources, you eliminate any potential configuration drift or manual errors.
• Reusability: ARM templates offer reusability through parameterization. You can define template parameters that allow customization during deployment, making your templates adaptable to different scenarios without modification.

Provisioning an Azure Cosmos DB account using ARM templates

Let’s explore an example of provisioning an Azure Cosmos DB account using an ARM template. The following template shows the basic structure:

{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": { ... },
"resources": [ ... ],
"outputs": { ... }
}

In the parameters section, you define input values provided during deployment. For example, you can define parameters for the Cosmos DB account name, location, and throughput. Here’s an example of defining a parameter for the account name:

"parameters": {
"cosmosDbAccountName": {
"type": "string",
"metadata": { "description": "The name of the Azure Cosmos DB account." }
},
...
}

In the resources section, you define the Azure resources you want to deploy. For Azure Cosmos DB, you’ll specify a Microsoft.DocumentDB/databaseAccounts resource type. Here’s an example of defining a Cosmos DB account:

"resources": [
{
"type": "Microsoft.DocumentDB/databaseAccounts",
"apiVersion": "2021-03-01",
"name": "[parameters('cosmosDbAccountName')]",
"location": "[resourceGroup().location]",
"kind": "GlobalDocumentDB",
"properties": {
"consistencyPolicy": { ... },
"locations": [ ... ]
}
},
...
]

In the above example, we reference the cosmosDbAccountName parameter using parameters('cosmosDbAccountName'). The location is obtained from the resource group by using resourceGroup().location.

Finally, you can define the outputs section to retrieve useful information after the deployment. For example, you can output the connection string of the Cosmos DB account for your application’s consumption:

"outputs": {
"cosmosDbConnectionString": {
"type": "string",
"value": "[concat('AccountEndpoint=', reference(parameters('cosmosDbAccountName')).documentEndpoint, ';AccountKey=', listKeys(parameters('cosmosDbAccountName')).primaryMasterKey)]"
},
...
}

In this example, we concatenate the account endpoint and primary master key to form the connection string.

Deploying an ARM template for Cosmos DB account

To deploy the ARM template for the Cosmos DB account, you can use various methods such as Azure portal, Azure CLI, PowerShell, or Azure DevOps pipelines. Here we’ll use Azure CLI as an example.

1. Save the ARM template in a file, e.g., “cosmosdb-template.json.”
2. Open the command prompt or terminal and log in to Azure using Azure CLI:

az login

3. Set your Azure subscription:

az account set --subscription


4. Deploy the ARM template using the following command:

az deployment group create --resource-group --template-file cosmosdb-template.json --parameters cosmosDbAccountName=


Replace <resource_group_name> with the name of your resource group, cosmosdb-template.json with the path to your ARM template file, and <account_name> with the desired name for your Cosmos DB account.

Summary

In this article, we explored the concept of using ARM templates to provision and manage Azure Cosmos DB resources. We discussed the advantages of using ARM templates and provided an example of provisioning a Cosmos DB account using an ARM template. We also discussed deploying the ARM template using Azure CLI. By utilizing ARM templates, you can achieve consistency, reusability, and infrastructure-as-code practices in managing your Azure Cosmos DB resources effectively.