Azure Cosmos DB migration strategies

The design question

One Cosmos DB account bundles five things that a target has to cover separately.

1. 01

   The API and query dialect

   MongoDB wire protocol, or the NoSQL (Core/SQL) API. Only the first has a drop-in target on STACKIT.

2. 02

   Consistency

   Cosmos DB offers five levels: strong, bounded staleness, session, consistent prefix and eventual. The MongoDB Flex resource has no consistency policy setting, so the draft lists the policy as not carried.

3. 03

   Distribution

   Accounts replicate to several regions. The engine states that STACKIT has no managed multi-region database replication.

4. 04

   Throughput model

   Request units and autoscale do not carry over. You size a flavor and storage instead.

5. 05

   Partitioning and change feed

   Partition keys and the change feed are rethought for the NoSQL API.

The options

Trade-offs only, no benchmarks. The first row is what the run produced for the MongoDB API.

Single-region accounts only: a multi-region NoSQL account is a manual review, see below.

The MongoDB API account, converted

A small estate written for this page and assessed by StackToIT on 4 November 2026. Left: the Azure input. Right: the resource block of the STACKIT Terraform the engine wrote; the review comments above it are left out here.

resource "azurerm_cosmosdb_account" "mongo_api" {
  name                = "cosmos-sessions-mongo"
  location            = azurerm_resource_group.catalog.location
  resource_group_name = azurerm_resource_group.catalog.name
  offer_type          = "Standard"
  kind                = "MongoDB"
  mongo_server_version = "7.0"

  capabilities {
    name = "EnableMongo"
  }

  consistency_policy {
    consistency_level = "Session"
  }

  geo_location {
    location          = "germanywestcentral"
    failover_priority = 0
  }
}

resource "stackit_mongodbflex_instance" "mongo_api" {
  project_id = var.project_id
  name       = "cosmos-sessions-mongo"
  acl        = var.mongo_api_allowed_cidrs
  version    = "7.0"
  flavor = {
    cpu = var.mongo_api_cpu
    ram = var.mongo_api_ram
  }
  replicas = 1
  storage = {
    class = var.mongodbflex_storage_class
    size  = var.mongo_api_storage_gb
  }
  backup_schedule = "0 2 * * *"
  options = {
    type                       = "Single"
    point_in_time_window_hours = var.mongo_api_pitr_hours
  }
}

• A single node, as a starting point

  The draft sets type Single with one replica, a daily backup at 02:00 and variables for CPU, RAM, storage and the access list. The STACKIT documentation names a replica set as the better choice for most production cases, so revisit this.

• The version is carried

  The draft sets 7.0, the version of the source account. Cosmos DB implements a MongoDB wire-protocol level, not MongoDB itself, so a person checks driver compatibility.

• What is not carried

  Consistency policy, regions and failover priorities, capabilities and throughput are listed as not carried, next to the block.

The NoSQL API account, held back

This account replicates to two regions and holds a database and a container. The assessment records a critical finding and leaves the class to a person.

resource "azurerm_cosmosdb_account" "sql_api" {
  name                = "cosmos-catalog-sql"
  location            = azurerm_resource_group.catalog.location
  resource_group_name = azurerm_resource_group.catalog.name
  offer_type          = "Standard"
  kind                = "GlobalDocumentDB"

  consistency_policy {
    consistency_level = "Session"
  }

  geo_location {
    location          = "germanywestcentral"
    failover_priority = 0
  }

  geo_location {
    location          = "northeurope"
    failover_priority = 1
  }
}

resource "azurerm_cosmosdb_sql_database" "catalog" {
  name                = "catalog"
  resource_group_name = azurerm_resource_group.catalog.name
  account_name        = azurerm_cosmosdb_account.sql_api.name
}

resource "azurerm_cosmosdb_sql_container" "products" {
  name                = "products"
  resource_group_name = azurerm_resource_group.catalog.name
  account_name        = azurerm_cosmosdb_account.sql_api.name
  database_name       = azurerm_cosmosdb_sql_database.catalog.name
  partition_key_paths = ["/categoryId"]
  throughput          = 800
}

{
  "id": "azurerm_cosmosdb_account.sql_api",
  "result": {
    "class": "MANUAL_REVIEW",
    "confidence": "MEDIUM",
    "target": {
      "service": "STACKIT MongoDB Flex or PostgreSQL Flex (JSONB) — data-model redesign",
      "resources": [
        "stackit_mongodbflex_instance"
      ]
    },
    "reason": "The NoSQL (Core/SQL) API is Cosmos DB's own protocol and query dialect; nothing else speaks it. The access layer is rewritten for MongoDB Flex or PostgreSQL JSONB, and partition-key design, consistency levels and change feed are re-thought.",
    "findings": [
      {
        "severity": "critical",
        "message": "Replicated to several regions (geo_location); STACKIT has no managed multi-region database replication."
      }
    ]
  }
}

• Two regions, a critical finding

  In the service-mapping run, a NoSQL account with one region was REDESIGN. This account adds a second region, a database and a container; the run records a critical multi-region finding and the class is MANUAL_REVIEW. The run does not say which difference decides the class. Both classes mean an architect owns the next step.

• No Terraform is written

  The mongodbflex target is named as a candidate, but nothing is drafted for the account until the data model and the availability design are decided.

A resource the build does not know

The MongoDB collection with its shard key and index is a separate resource type. This build has no catalogue entry for it, so it appears as a manual unit with LOW confidence and as a warning on the account. The excerpt shows the fields as the run wrote them.

resource "azurerm_cosmosdb_mongo_collection" "carts" {
  name                = "carts"
  resource_group_name = azurerm_resource_group.catalog.name
  account_name        = azurerm_cosmosdb_account.mongo_api.name
  database_name       = azurerm_cosmosdb_mongo_database.sessions.name
  shard_key           = "userId"
  throughput          = 400

  index {
    keys   = ["_id"]
    unique = true
  }
}

{
  "id": "azurerm_cosmosdb_mongo_collection.carts",
  "result": {
    "class": "MANUAL_REVIEW",
    "confidence": "LOW",
    "reason": "azurerm_cosmosdb_mongo_collection is not in the knowledge base catalogue; an architect has to decide the target. Nothing of this resource is assessed or drafted (unknown source type).",
    "coverage": "UNKNOWN_SOURCE_TYPE"
  }
}

• Move the collection design yourself

  Shard key userId and the unique _id index are not assessed. On MongoDB Flex, STACKIT describes sharding as a last resort after replica sets, indexing and vertical scaling.

How to decide

• Start with the API

  List every account and its API. MongoDB accounts follow the straight path, NoSQL accounts need a design decision.

• Decide the region story

  If the account spans regions, write down why. Then choose a single region, an application-level approach or staying on Azure for that workload.

• Check consistency needs

  Find which reads depend on session or bounded staleness guarantees. Test the application against a MongoDB Flex instance of the type you plan, single or replica set.

• Size from the data

  The STACKIT planning guidance suggests a factor of 2 to 2.5 for data growth over two years and notes that BSON can be 10 to 15 percent larger than JSON. Storage can be enlarged without downtime but not reduced, and the instance type cannot be changed later.

• Name an owner and a date

  For both accounts the data-movement file leaves the mechanism UNKNOWN and the data class, RPO and downtime tolerance NOT_PROVIDED. Fill them in before you choose a tool.

Questions about Cosmos DB migrations

Sources

• Microsoft Learn: Azure Cosmos DB for MongoDB
• Microsoft Learn: Cosmos DB consistency levels
• STACKIT documentation: MongoDB Flex
• STACKIT documentation: plan your MongoDB Flex instance
• STACKIT documentation: PostgreSQL Flex