Azure Cosmos DB is a powerful, fully managed, NoSQL, globally distributed multi-model database service offered by Microsoft Azure. Azure Cosmos DB enables you to quickly create and query document databases, key/value databases, and graph databases. In this short article, we’ll take a look at the necessary HashiCorp Terraform code to provision an Azure Cosmos DB Account with a Database and Container. Basically, the minimum to get set up with being able to use Azure Cosmos DB.

Let’s dig into how to do this!

Create Azure Cosmos DB Account using Terraform

The root Azure resource required for using Azure Cosmos DB is an Account. Within this Azure Cosmos DB Account is where the Databases and Containers for your Cosmos DB database will be created.

The following Terraform code can be used to create / manage an Azure Cosmos DB Account:

# Terraform version requirements and AzureRM resource provider
terraform {
  required_version = ">= 1.0"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.0, < 4.0"
    }
  }
}

provider "azurerm" {
  features = {}
}

# Azure Resource Group where to create Cosmos DB Account
data azurerm_resource_group "primary" {
  name     = "b59-cosmos-rg"
}

# Terraform to create Azure Cosmos DB Account
resource azurerm_cosmosdb_account "primary" {
  name                      = "b59-cosmosdb"
  resource_group_name       = azurerm_resource_group.primary.name
  
  # use same location as Resource Group
  location                  = azurerm_resource_group.primary.location
  
  offer_type                = "Standard"
  kind                      = "GlobalDocumentDB"

  enable_automatic_failover = false

  geo_location {
    location          = azurerm_resource_group.primary.location
    failover_priority = 0
  }
  consistency_policy {
    consistency_level       = "BoundedStaleness"
    max_interval_in_seconds = 300
    max_staleness_prefix    = 100000
  }
}

Create Database in Azure Cosmos DB Account

Now that you have an Azure Cosmos DB Account created, you can move to the next step which is to create / manage a Database within the Account. The Database requires a “name” that it will be referred to when accessed, as well as the “throughput” that will define the performance of the Cosmos DB Database that’s supported, and basically result in how much cost will be incurred to using it.

# Terraform to configure Database in Azure Cosmos DB Account
resource azurerm_cosmosdb_sql_database "main" {
  name                = "main"
  resource_group_name = azurerm_resource_group.primary.name
  account_name        = azurerm_cosmosdb_account.primary.name
  throughput          = 400
}

There’s more information about Throughput and cost of Azure Cosmos DB available from Microsoft in the official docs; sorry that is out of the scope of this article.

Create Container within Azure Cosmos DB Database

Now that the Database has been created within the Azure Cosmos DB Account, you can create / manage one or more Containers within the Database. The Containers are essentially where data will be stored within Azure Cosmos DB. There are some required configurations for the Container, such as partitioning configuration and throughput for defining the performance of the Container itself. These will be configured on the Container level.

# Terraform to set up Container within Azure Cosmos DB Database
resource azurerm_cosmosdb_sql_container "main" {
  name                  = "main-container"
  resource_group_name   = azurerm_resource_group.primary.name
  account_name          = azurerm_cosmosdb_account.primary.name
  database_name         = azurerm_cosmosdb_sql_database.main.name
  partition_key_path    = "/definition/id"
  partition_key_version = 1
  throughput            = 400

  indexing_policy {
    indexing_mode = "consistent"

    included_path {
      path = "/*"
    }

    included_path {
      path = "/included/?"
    }

    excluded_path {
      path = "/excluded/?"
    }
  }

  unique_key {
    paths = ["/definition/idlong", "/definition/idshort"]
  }
}

Conclusion

While deploying and managing Azure Cosmos DB using HashiCorp Terraform is not all that complicated, it does require 3 different types of resources. The Azure Cosmos DB Account is the main resource you will see listed within the Azure Portal when these are created, and the Databases and Containers you create are resources that are configured within the Azure Cosmos DB Account itself.