Create an Azure Cosmos DB fleet (preview)

  • Applies to: ✅ NoSQL

Important

This feature is currently in preview and is provided without a service-level agreement. At this time, previews aren't recommended for production workloads. Certain features of this preview aren't supported or might have capability constraints. For more information, see supplemental terms of use for Azure previews.

This article provides step-by-step instructions for creating and managing fleets, fleetspaces, and fleetspace accounts. Follow the guidance here to set up and configure your Azure Cosmos DB fleet resources one-by-one. At the end of this guide, you have a fully configured fleet with a single fleetspace, throughput pooling, and a registered Azure Cosmos DB account as a fleetspace account.

For more information about fleets, see fleets overview.

Prerequisites

  • An Azure subscription

    • If you don't have an Azure subscription, create a Trial before you begin.

  • Registration in the Azure Cosmos DB fleet preview feature for your subscription.

  • Azure CLI
  • Bicep

Create a fleet

Set up your fleet by creating the fleet that eventually contains your fleetspace, and fleetspace account resources. A fleet is a high-level entity that organizes and manages multiple database accounts across different subscriptions and/or resource groups within fleetspaces. One fleet corresponds to one multitenant application. Specify a region and unique name for the fleet.

Note

The region selected for your fleet resources doesn't affect or determine the locations/regions of any database accounts in the fleet.

  1. Sign in to the Azure portal (https://portal.azure.cn).

  2. Enter Cosmos DB fleet in the global search bar.

  3. Within Services, select Azure Cosmos DB Fleets.

  4. On the Azure Cosmos DB Fleets page, select + Create.

  5. Within the Basics pane, configure the following options, and then select Review + create:

    Value
    Subscription Select your Azure subscription
    Resource group Create a new resource group or select an existing resource group
    Fleet Name Provide a multiple-regionally unique name
    Region Select a supported Azure region for your subscription

    Screenshot of the fleet creation overview page in the Azure portal.

  6. On the Review + create pane, wait for validation of your fleet to finish successfully, and then select Create.

  1. Create a fleet using az resource create and an empty ({}) JSON properties object:

    az resource create \
    --resource-group "<resource-group-name>" \
    --name "<fleet-name>" \
    --resource-type "Microsoft.DocumentDB/fleets" \
    --location "<azure-region>" \
    --latest-include-preview \
    --properties "{}"

  2. Optionally, perform common fleet management operations including:

    • Retrieving a specific fleet.

      az resource show \
    --resource-group "<resource-group-name>" \
    --name "<fleet-name>" \
    --resource-type "Microsoft.DocumentDB/fleets" \
    --latest-include-preview

    • Listing all fleets within a resource group.

      az resource list \
    --resource-group "<resource-group-name>" \
    --resource-type "Microsoft.DocumentDB/fleets"

    • Deleting a specific fleet.

      az resource delete \
    --resource-group "<resource-group-name>" \
    --name "<fleet-name>" \
    --resource-type "Microsoft.DocumentDB/fleets" \
    --latest-include-preview

resource fleet 'Microsoft.DocumentDB/fleets@2025-05-01-preview' = {
  name: '<fleet-name>'
  location: '<azure-region>'
  properties: {}
}

Create a fleetspace

Before adding accounts to the fleet, you must create a fleetspace. A fleetspace is a logical grouping of database accounts within the fleet, where RU/s can optionally be shared among all resources in database accounts within the fleetspace​. Each database account within a fleet must be a part of a fleetspace.

Note

In this guide, throughput pooling is configured for the fleetspace. You can opt to not use throughput pooling. Throughput pooling is an optional configuration that allows account resources to share RU/s. This shared RU/s is on top of the dedicated RU/s that are already available for the resource.
The pool minimum and maximum RU/s can be changed at any time. The service tier and data regions cannot be changed after fleetpsace creation.

To configure throughput pooling for a fleetspace, specify the regions and the service tier that apply to all accounts within the fleetspace. If throughput pooling is configured, all accounts within the fleetspace must share the same regional and service tier configuration.

For more information, see fleet pools.

  1. Navigate to your existing fleet resource within the Azure portal.

  2. Select the Fleetspaces option within the Fleet resources section of the resource menu.

  3. Within the dialog, configure the following options, and then select Ok:

    Value
    Fleetspace name Provide a unique name within your fleet
    Enable throughput pooling Select the checkbox
    Select regions for accounts in throughput pool Select and Add a list of regions for accounts in the throughput pool
    Select write-region type for accounts in throughput pool Select either Single-write region (General purpose) or Multi-write region (Business critical)
    Throughput pool minimum RU/s A whole number, not less than 100,000, and must be a multiple of 1,000
    Throughput pool maximum RU/s A whole number, not less than 100,000, or less than throughputPoolConfiguration.minThroughput and must be a multiple of 1,000

    Screenshot of the fleetspace creation dialog in the Azure portal.

  1. Create a fleetspace within your fleet using the following properties:

    Value
    fleetspaceAPIKind NoSQL
    throughputPoolConfiguration.minThroughput A whole number, not less than 100,000, and must be a multiple of 1,000
    throughputPoolConfiguration.maxThroughput A whole number, not less than 100,000, or less than throughputPoolConfiguration.minThroughput and must be a multiple of 1,000
    throughputPoolConfiguration.serviceTier Either GeneralPurpose or BusinessCritical
    throughputPoolConfiguration.dataRegions List of regions for accounts in the throughput pool 
    json=$(jq \
    --arg "locationName" "<azure-region>" \
    --arg "api" "NoSQL" \
    --arg "minRUs" 100000 \
    --arg "maxRUs" 100000 \
    --arg "tier" "GeneralPurpose" \
    --null-input \
    --compact-output \
    '{fleetspaceAPIKind:$api,throughputPoolConfiguration:{minThroughput:$minRUs,maxThroughput:$maxRUs,serviceTier:$tier,dataRegions:[$locationName]}}' \
)

az resource create \
    --resource-group "<resource-group-name>" \
    --name "<fleet-name>/fleetspaces/<fleetspace-name>" \
    --resource-type "Microsoft.DocumentDB/fleets/fleetspaces/" \
    --location "<azure-region>" \
    --latest-include-preview \
    --properties $json

    Tip

    You can configure the minThroughput, maxThroughput, writeRegionType, and dataRegions properties to whatever is appropriate for your scenario.

  2. Optionally, perform common fleetspace management operations including:

    • Retrieving a specific fleetspace within a fleet.

      az resource show \
    --resource-group "<resource-group-name>" \
    --name "<fleet-name>/fleetspaces/<fleetspace-name>" \
    --resource-type "Microsoft.DocumentDB/fleets/fleetspaces/" \
    --latest-include-preview

    • Listing all fleetspaces within a fleet.

      az resource list \
    --resource-group "<resource-group-name>" \
    --resource-type "Microsoft.DocumentDB/fleets/fleetspaces/"

    • Deleting a specific fleetspace within a fleet.

      az resource delete \
    --resource-group "<resource-group-name>" \
    --name "<fleet-name>/fleetspaces/<fleetspace-name>" \
    --resource-type "Microsoft.DocumentDB/fleets/fleetspaces/" \
    --latest-include-preview
Value
fleetspaceAPIKind NoSQL
throughputPoolConfiguration.minThroughput A whole number, not less than 100,000, and must be a multiple of 1,000
throughputPoolConfiguration.maxThroughput A whole number, not less than 100,000, or less than throughputPoolConfiguration.minThroughput and must be a multiple of 1,000
throughputPoolConfiguration.serviceTier Either GeneralPurpose or BusinessCritical
throughputPoolConfiguration.dataRegions List of regions for accounts in the throughput pool 
resource fleetspace 'Microsoft.DocumentDB/fleets/fleetspaces@2025-05-01-preview' = {
  name: '<fleetspace-name>'
  parent: fleet
  location: '<azure-region>'
  properties: {
    fleetspaceAPIKind: 'NoSQL'
    throughputPoolConfiguration: {
      minThroughput: 100000
      maxThroughput: 100000
      serviceTier: 'SingleRegionWrite'
      dataRegions: [
        '<azure-region>'
      ]
    }
  }
}

Tip

You can configure the minThroughput, maxThroughput, writeRegionType, and dataRegions properties to whatever is appropriate for your scenario.

Add accounts to a fleetspace

Once the fleetspace is created, add accounts either to the fleetspace itself. Accounts from any subscription/resource group can be added to the fleet. When pooling is configured for the fleetspace, these resources consume RU/s from the pool.

Important

You can't add accounts to your fleetspace that are already associated with an existing fleetspace.

  1. Select the Database accounts option within the Fleet resources section of the resource menu.

  2. In the Fleetspace section, select an existing fleetspace.

    Screenshot of the option to select a fleetspace with the fleetspace account registration page in the Azure portal.

  3. Then, enable the Browse accounts to add to this fleetspace option.

  4. Select an existing Azure Cosmos DB for NoSQL account and then select + Add to fleetspace.

    Screenshot of the page to register Azure Cosmos DB accounts with a fleetspace in the Azure portal.

  1. Create a fleetspace account within your fleetspace using the following properties:

    Value
    accountLocation Location for the Azure Cosmos DB account.
    accountResourceIdentifier Fully qualified resource identifier for the target Azure Cosmos DB account. 
    databaseResourceId=$(az resource show \
    --resource-group "<resource-group-name>" \
    --name "<azure-cosmos-db-resource-name>" \
    --resource-type "Microsoft.DocumentDB/databaseAccounts" \
    --query "id" \
    --output tsv \
)

json=$(jq \
    --arg "locationName" "<azure-region>" \
    --arg "accountResourceId" "$databaseResourceId" \
    --null-input \
    --compact-output \
    '{accountLocation:$locationName,accountResourceIdentifier:$accountResourceId}' \
)

az resource create \
    --resource-group "<resource-group-name>" \
    --name "<fleet-name>/fleetspaces/<fleetspace-name>/fleetspaceAccounts/<fleetspace-account-name>" \
    --resource-type "Microsoft.DocumentDB/fleets/fleetspaces/fleetspaceAccounts/" \
    --location "<azure-region>" \
    --latest-include-preview \
    --properties $json

  2. Optionally, perform common fleetspace management operations including:

    • Retrieving a specific fleetspace account within a fleetspace.

      az resource show \
    --resource-group "<resource-group-name>" \
    --name "<fleet-name>/fleetspaces/<fleetspace-name>/fleetspaceAccounts/<fleetspace-account-name>" \
    --resource-type "Microsoft.DocumentDB/fleets/fleetspaces/fleetspaceAccounts/" \
    --latest-include-preview

    • Listing fleetspace accounts within a fleetspace.

      az resource list \
    --resource-group "<resource-group-name>" \
    --resource-type "Microsoft.DocumentDB/fleets/fleetspaces/fleetspaceAccounts/"

    • Deleting a specific fleetspace account.

      az resource delete \
    --resource-group "<resource-group-name>" \
    --name "<fleet-name>/fleetspaces/<fleetspace-name>/fleetspaceAccounts/<fleetspace-account-name>" \
    --resource-type "Microsoft.DocumentDB/fleets/fleetspaces/fleetspaceAccounts/" \
    --latest-include-preview
Value
accountLocation Location for the Azure Cosmos DB account.
accountResourceIdentifier Fully qualified resource identifier for the target Azure Cosmos DB account. 
resource account 'Microsoft.DocumentDB/databaseAccounts@2024-12-01-preview' existing = {
  name: '<azure-cosmos-db-resource-name>'
}

resource fleetspaceAccount 'Microsoft.DocumentDB/fleets/fleetspaces/fleetspaceAccounts@2025-05-01-preview' = {
  name: '<fleetspace-account-name>'
  parent: fleetspace
  location: '<azure-region>'
  properties: {
    accountLocation: '<azure-region>'
    accountResourceIdentifier: account.id
  }
}

Related content