Cosmos Creation on Azure using Terraform

5 min readNov 9, 2022

This article talks about creating a cosmos DB on Azure using Terraform. Before proceeding let us understand why we even need to use terraform for resource creation.

Terraform is a powerful open-source tool that helps automate and manage the infrastructure. Since it is declarative (defining what result you want) in nature, we don't need to specify every step regarding how this should be done. With the help of Terraform, you can easily make changes to the existing infrastructure based on your needs. It is very easy to replicate your infrastructure across the environment. Most of the orgs have different environments for different purposes, with more or less the same set of resources differentiating in the number of instances or computing power. And this is easily achievable by using terraform.

Now coming back to creating a cosmos DB on Azure. So Cosmos is a NoSQL DB provided by azure with features such as high availability, throughput and low latency. We will now see how to provision a cosmos resource using terraform.

NOTE: This article assumes you already have terraform and AZ CLI installed on your machine.

The first file we are going to talk about is a main.tf file which will contain the definition of our resources.

terraform {
  required_version = ">= 0.12.6"
  required_providers {
    azurerm = {
      version = "~> 3.0.2"
    }
  }
}provider "azurerm" {
  features {}
}resource "azurerm_resource_group" rg {
  name     = var.resource_group_name
  location = var.resource_group_location
}resource "azurerm_cosmosdb_account" "acc" {name                      = var.cosmos_db_account_name
  location                  = azurerm_resource_group.rg.location
  resource_group_name       = azurerm_resource_group.rg.name
  offer_type                = "Standard"
  kind                      = "GlobalDocumentDB"
  enable_automatic_failover = trueconsistency_policy {
    consistency_level = "Session"
  }geo_location {
    location          = var.failover_location
    failover_priority = 1
  }geo_location {
    location          = azurerm_resource_group.rg.location
    failover_priority = 0
  }
}resource "azurerm_cosmosdb_sql_database" "db" {
  name                = "employeedb"
  resource_group_name = azurerm_cosmosdb_account.acc.resource_group_name
  account_name        = azurerm_cosmosdb_account.acc.name
}resource "azurerm_cosmosdb_sql_container" "coll" {
  name                = "employeedata"
  resource_group_name = azurerm_cosmosdb_account.acc.resource_group_name
  account_name        = azurerm_cosmosdb_account.acc.name
  database_name       = azurerm_cosmosdb_sql_database.db.name
  partition_key_path  = "/id"
}

Let us now understand each of these in detail:

terraform: contains the terraform settings along with the provider which will be used to provide the infrastructure. Azure in this case.
provider: a plugin which terraform used to create and manage the resources.
resource: this block is used to define the resources. It is followed by two attributes — the first is a resource type and the second is the resource name.

NOTE: This resource name is not what will be used to create resources on azure. This is internal to terraform and can be used to refer to other places.

azurerm_resource_group

The first resource that we have used is azurerm_resource_group. If you have worked with azure you might be aware of what a resource group is. If you are new, you can consider resource group as a logical grouping of resources on azure.

The name attribute here specifies the name that will be used to create a resource on azure. location specifies a geographical location where this resource group will be created. This definition remains the same for all the resources created on azure.

azurerm_cosmosdb_account

In order to create cosmos, we first need to create a cosmos DB account. Let us understand each of its attributes.

resource_group_name: the resource group where this resource would reside.

offer_type: specifies the Offer Type to use for this CosmosDB Account, currently only ‘Standard’ is supported.

kind specifies the kind of cosmos DB to be created, supported values: GlobalDocumentDB & MongoDB.

consistency_policy tells about the consistency level to use. We are using Session here, which is the default consistency offered and what it means is that whatever is written by a session will return the latest version for reads as well, from that same session.

You can read about different consistency levels from the official Microsoft documentation here.

geo_location: used to define where the data should be replicated. failover_priority 0 means the primary locations

azurerm_cosmosdb_sql_database

This resource type manages a SQL database within a cosmos DB account.

account_name: The cosmos DB account under which this SQL DB will be created.

azurerm_cosmosdb_sql_container

Manages a SQL Container within a database inside a Cosmos DB Account. This container is where our data is stored.

account_name: cosmos DB account under which this container will be created.

database_name: The database under which this container will be created.

partition_key_path: Defines a partition key. A partition key allows you to group a set of items or data in your collection. Partition key distributes your data efficiently so that the queries performed against the database are as quick as possible.

This was all about the resource file, now lets quickly take a look at the vars.tf file

variable "resource_group_name" {
  default = "shivam-rg"
}variable "resource_group_location" {
  default = "East US"
}variable "cosmos_db_account_name" {
  default = "shivam-cosmos"
}variable "failover_location" {
  default = "West US"
}

This file is used to provide the inputs to the main.tf file. As the name is self-intuitive, consider this file as initialising variables with some values which can be used while resource creation using the var keyword.

Once these files are ready, we need to run the terraform commands to provision the resource, which in our case would be a resource group and a cosmos db account with a db and collection.

terraform init

The terraform init command initialises a working directory containing Terraform configuration files. This is the first command to be run after writing a new configuration file.

terraform apply

This command creates or updates infrastructure based on the configuration files.

On running this you would be prompted to enter ‘yes’ in order to proceed with the changes. This command also shows you the plan that will be executed on running the config files (new resources added, resources changed, resources destroyed).

After entering yes, it would take a few minutes for the infrastructure changes. On successful completion, terraform would notify using a ‘Apply Complete’ message.