Deploy Azure Cosmos DB

The azure-native:cosmosdb:Service resource, part of the Pulumi Azure Native provider, provisions add-on services for Cosmos DB accounts: integrated caches, data transfer capabilities, graph compute, and materialized view builders. This guide focuses on four capabilities: integrated cache with SQL Dedicated Gateway, data transfer between accounts, graph compute provisioning, and materialized view builders.

All services attach to existing Cosmos DB accounts. The examples are intentionally small. Combine them with your own Cosmos DB accounts and resource groups.

Add an integrated cache with dedicated gateway

Applications with read-heavy workloads often benefit from caching frequently accessed data to reduce latency and request unit consumption. The SQL Dedicated Gateway provides an integrated cache layer in front of your Cosmos DB account.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const service = new azure_native.cosmosdb.Service("service", {
    accountName: "ddb1",
    properties: {
        dedicatedGatewayType: azure_native.cosmosdb.DedicatedGatewayType.IntegratedCache,
        instanceCount: 1,
        instanceSize: azure_native.cosmosdb.ServiceSize.Cosmos_D4s,
        serviceType: "SqlDedicatedGateway",
    },
    resourceGroupName: "rg1",
    serviceName: "SqlDedicatedGateway",
});

import pulumi
import pulumi_azure_native as azure_native

service = azure_native.cosmosdb.Service("service",
    account_name="ddb1",
    properties={
        "dedicated_gateway_type": azure_native.cosmosdb.DedicatedGatewayType.INTEGRATED_CACHE,
        "instance_count": 1,
        "instance_size": azure_native.cosmosdb.ServiceSize.COSMOS_D4S,
        "service_type": "SqlDedicatedGateway",
    },
    resource_group_name="rg1",
    service_name="SqlDedicatedGateway")

package main

import (
	cosmosdb "github.com/pulumi/pulumi-azure-native-sdk/cosmosdb/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := cosmosdb.NewService(ctx, "service", &cosmosdb.ServiceArgs{
			AccountName: pulumi.String("ddb1"),
			Properties: &cosmosdb.SqlDedicatedGatewayServiceResourceCreateUpdatePropertiesArgs{
				DedicatedGatewayType: pulumi.String(cosmosdb.DedicatedGatewayTypeIntegratedCache),
				InstanceCount:        pulumi.Int(1),
				InstanceSize:         pulumi.String(cosmosdb.ServiceSize_Cosmos_D4s),
				ServiceType:          pulumi.String("SqlDedicatedGateway"),
			},
			ResourceGroupName: pulumi.String("rg1"),
			ServiceName:       pulumi.String("SqlDedicatedGateway"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var service = new AzureNative.CosmosDB.Service("service", new()
    {
        AccountName = "ddb1",
        Properties = new AzureNative.CosmosDB.Inputs.SqlDedicatedGatewayServiceResourceCreateUpdatePropertiesArgs
        {
            DedicatedGatewayType = AzureNative.CosmosDB.DedicatedGatewayType.IntegratedCache,
            InstanceCount = 1,
            InstanceSize = AzureNative.CosmosDB.ServiceSize.Cosmos_D4s,
            ServiceType = "SqlDedicatedGateway",
        },
        ResourceGroupName = "rg1",
        ServiceName = "SqlDedicatedGateway",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.cosmosdb.Service;
import com.pulumi.azurenative.cosmosdb.ServiceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var service = new Service("service", ServiceArgs.builder()
            .accountName("ddb1")
            .properties(SqlDedicatedGatewayServiceResourceCreateUpdatePropertiesArgs.builder()
                .dedicatedGatewayType("IntegratedCache")
                .instanceCount(1)
                .instanceSize("Cosmos.D4s")
                .serviceType("SqlDedicatedGateway")
                .build())
            .resourceGroupName("rg1")
            .serviceName("SqlDedicatedGateway")
            .build());

    }
}

resources:
  service:
    type: azure-native:cosmosdb:Service
    properties:
      accountName: ddb1
      properties:
        dedicatedGatewayType: IntegratedCache
        instanceCount: 1
        instanceSize: Cosmos.D4s
        serviceType: SqlDedicatedGateway
      resourceGroupName: rg1
      serviceName: SqlDedicatedGateway

The serviceType property specifies “SqlDedicatedGateway” to enable the cache layer. The dedicatedGatewayType property sets the cache mode to “IntegratedCache”, which stores frequently accessed items in memory. The instanceCount and instanceSize properties control capacity: more instances or larger sizes increase cache memory and throughput.

Enable data transfer between Cosmos DB accounts

Teams migrating data or synchronizing across regions use the Data Transfer service to move documents between Cosmos DB accounts without writing custom migration code.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const service = new azure_native.cosmosdb.Service("service", {
    accountName: "ddb1",
    properties: {
        instanceCount: 1,
        instanceSize: azure_native.cosmosdb.ServiceSize.Cosmos_D4s,
        serviceType: "DataTransfer",
    },
    resourceGroupName: "rg1",
    serviceName: "DataTransfer",
});

import pulumi
import pulumi_azure_native as azure_native

service = azure_native.cosmosdb.Service("service",
    account_name="ddb1",
    properties={
        "instance_count": 1,
        "instance_size": azure_native.cosmosdb.ServiceSize.COSMOS_D4S,
        "service_type": "DataTransfer",
    },
    resource_group_name="rg1",
    service_name="DataTransfer")

package main

import (
	cosmosdb "github.com/pulumi/pulumi-azure-native-sdk/cosmosdb/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := cosmosdb.NewService(ctx, "service", &cosmosdb.ServiceArgs{
			AccountName: pulumi.String("ddb1"),
			Properties: &cosmosdb.DataTransferServiceResourceCreateUpdatePropertiesArgs{
				InstanceCount: pulumi.Int(1),
				InstanceSize:  pulumi.String(cosmosdb.ServiceSize_Cosmos_D4s),
				ServiceType:   pulumi.String("DataTransfer"),
			},
			ResourceGroupName: pulumi.String("rg1"),
			ServiceName:       pulumi.String("DataTransfer"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var service = new AzureNative.CosmosDB.Service("service", new()
    {
        AccountName = "ddb1",
        Properties = new AzureNative.CosmosDB.Inputs.DataTransferServiceResourceCreateUpdatePropertiesArgs
        {
            InstanceCount = 1,
            InstanceSize = AzureNative.CosmosDB.ServiceSize.Cosmos_D4s,
            ServiceType = "DataTransfer",
        },
        ResourceGroupName = "rg1",
        ServiceName = "DataTransfer",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.cosmosdb.Service;
import com.pulumi.azurenative.cosmosdb.ServiceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var service = new Service("service", ServiceArgs.builder()
            .accountName("ddb1")
            .properties(DataTransferServiceResourceCreateUpdatePropertiesArgs.builder()
                .instanceCount(1)
                .instanceSize("Cosmos.D4s")
                .serviceType("DataTransfer")
                .build())
            .resourceGroupName("rg1")
            .serviceName("DataTransfer")
            .build());

    }
}

resources:
  service:
    type: azure-native:cosmosdb:Service
    properties:
      accountName: ddb1
      properties:
        instanceCount: 1
        instanceSize: Cosmos.D4s
        serviceType: DataTransfer
      resourceGroupName: rg1
      serviceName: DataTransfer

The serviceType property set to “DataTransfer” provisions the migration service. The instanceCount and instanceSize properties determine how many parallel transfers can run and how much throughput each instance provides. This service handles schema mapping and retry logic automatically.

Provision compute for graph queries

Graph workloads running complex traversals benefit from dedicated compute resources that isolate query processing from transactional operations.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const service = new azure_native.cosmosdb.Service("service", {
    accountName: "ddb1",
    properties: {
        instanceCount: 1,
        instanceSize: azure_native.cosmosdb.ServiceSize.Cosmos_D4s,
        serviceType: "GraphAPICompute",
    },
    resourceGroupName: "rg1",
    serviceName: "GraphAPICompute",
});

import pulumi
import pulumi_azure_native as azure_native

service = azure_native.cosmosdb.Service("service",
    account_name="ddb1",
    properties={
        "instance_count": 1,
        "instance_size": azure_native.cosmosdb.ServiceSize.COSMOS_D4S,
        "service_type": "GraphAPICompute",
    },
    resource_group_name="rg1",
    service_name="GraphAPICompute")

package main

import (
	cosmosdb "github.com/pulumi/pulumi-azure-native-sdk/cosmosdb/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := cosmosdb.NewService(ctx, "service", &cosmosdb.ServiceArgs{
			AccountName: pulumi.String("ddb1"),
			Properties: &cosmosdb.GraphAPIComputeServiceResourceCreateUpdatePropertiesArgs{
				InstanceCount: pulumi.Int(1),
				InstanceSize:  pulumi.String(cosmosdb.ServiceSize_Cosmos_D4s),
				ServiceType:   pulumi.String("GraphAPICompute"),
			},
			ResourceGroupName: pulumi.String("rg1"),
			ServiceName:       pulumi.String("GraphAPICompute"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var service = new AzureNative.CosmosDB.Service("service", new()
    {
        AccountName = "ddb1",
        Properties = new AzureNative.CosmosDB.Inputs.GraphAPIComputeServiceResourceCreateUpdatePropertiesArgs
        {
            InstanceCount = 1,
            InstanceSize = AzureNative.CosmosDB.ServiceSize.Cosmos_D4s,
            ServiceType = "GraphAPICompute",
        },
        ResourceGroupName = "rg1",
        ServiceName = "GraphAPICompute",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.cosmosdb.Service;
import com.pulumi.azurenative.cosmosdb.ServiceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var service = new Service("service", ServiceArgs.builder()
            .accountName("ddb1")
            .properties(GraphAPIComputeServiceResourceCreateUpdatePropertiesArgs.builder()
                .instanceCount(1)
                .instanceSize("Cosmos.D4s")
                .serviceType("GraphAPICompute")
                .build())
            .resourceGroupName("rg1")
            .serviceName("GraphAPICompute")
            .build());

    }
}

resources:
  service:
    type: azure-native:cosmosdb:Service
    properties:
      accountName: ddb1
      properties:
        instanceCount: 1
        instanceSize: Cosmos.D4s
        serviceType: GraphAPICompute
      resourceGroupName: rg1
      serviceName: GraphAPICompute

The serviceType property set to “GraphAPICompute” provisions dedicated compute for Gremlin queries. The instanceCount and instanceSize properties control query throughput and concurrency. This separation prevents graph traversals from competing with transactional workloads for resources.

Build materialized views for analytics

Analytics workloads that aggregate or transform operational data use materialized views to pre-compute results and serve queries faster.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const service = new azure_native.cosmosdb.Service("service", {
    accountName: "ddb1",
    properties: {
        instanceCount: 1,
        instanceSize: azure_native.cosmosdb.ServiceSize.Cosmos_D4s,
        serviceType: "MaterializedViewsBuilder",
    },
    resourceGroupName: "rg1",
    serviceName: "MaterializedViewsBuilder",
});

import pulumi
import pulumi_azure_native as azure_native

service = azure_native.cosmosdb.Service("service",
    account_name="ddb1",
    properties={
        "instance_count": 1,
        "instance_size": azure_native.cosmosdb.ServiceSize.COSMOS_D4S,
        "service_type": "MaterializedViewsBuilder",
    },
    resource_group_name="rg1",
    service_name="MaterializedViewsBuilder")

package main

import (
	cosmosdb "github.com/pulumi/pulumi-azure-native-sdk/cosmosdb/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := cosmosdb.NewService(ctx, "service", &cosmosdb.ServiceArgs{
			AccountName: pulumi.String("ddb1"),
			Properties: &cosmosdb.MaterializedViewsBuilderServiceResourceCreateUpdatePropertiesArgs{
				InstanceCount: pulumi.Int(1),
				InstanceSize:  pulumi.String(cosmosdb.ServiceSize_Cosmos_D4s),
				ServiceType:   pulumi.String("MaterializedViewsBuilder"),
			},
			ResourceGroupName: pulumi.String("rg1"),
			ServiceName:       pulumi.String("MaterializedViewsBuilder"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var service = new AzureNative.CosmosDB.Service("service", new()
    {
        AccountName = "ddb1",
        Properties = new AzureNative.CosmosDB.Inputs.MaterializedViewsBuilderServiceResourceCreateUpdatePropertiesArgs
        {
            InstanceCount = 1,
            InstanceSize = AzureNative.CosmosDB.ServiceSize.Cosmos_D4s,
            ServiceType = "MaterializedViewsBuilder",
        },
        ResourceGroupName = "rg1",
        ServiceName = "MaterializedViewsBuilder",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.cosmosdb.Service;
import com.pulumi.azurenative.cosmosdb.ServiceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var service = new Service("service", ServiceArgs.builder()
            .accountName("ddb1")
            .properties(MaterializedViewsBuilderServiceResourceCreateUpdatePropertiesArgs.builder()
                .instanceCount(1)
                .instanceSize("Cosmos.D4s")
                .serviceType("MaterializedViewsBuilder")
                .build())
            .resourceGroupName("rg1")
            .serviceName("MaterializedViewsBuilder")
            .build());

    }
}

resources:
  service:
    type: azure-native:cosmosdb:Service
    properties:
      accountName: ddb1
      properties:
        instanceCount: 1
        instanceSize: Cosmos.D4s
        serviceType: MaterializedViewsBuilder
      resourceGroupName: rg1
      serviceName: MaterializedViewsBuilder

The serviceType property set to “MaterializedViewsBuilder” provisions the aggregation service. The instanceCount and instanceSize properties determine how quickly views refresh and how many concurrent view builds can run. The service monitors source containers and updates views automatically.

Beyond these examples

These snippets focus on specific service-level features: integrated caching and dedicated gateways, data transfer and migration, and graph compute and materialized views. They’re intentionally minimal rather than full database deployments.

The examples reference pre-existing infrastructure such as Cosmos DB database accounts and resource groups. They focus on configuring the service rather than provisioning the underlying database account.

To keep things focused, common service patterns are omitted, including:

Service scaling and instance size tuning
Service monitoring and diagnostics
Cost optimization strategies
Service lifecycle management (updates, deletions)

These omissions are intentional: the goal is to illustrate how each service type is wired, not provide drop-in database modules. See the Cosmos DB Service resource reference for all available configuration options.

Let's deploy Azure Cosmos DB

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

Service Configuration

What service types can I create with this resource?

You can create four types of Cosmos DB services: DataTransfer, GraphAPICompute, MaterializedViewsBuilder, and SqlDedicatedGateway. Each is configured by setting the serviceType property in the service properties.

What properties can't I change after creating the service?

The accountName, resourceGroupName, and serviceName properties are immutable. To change any of these, you must delete and recreate the service.

API Versions & Management

How do I use a different Azure API version?

Generate a local SDK package using the CLI command pulumi package add azure-native cosmosdb [ApiVersion] with your desired version (e.g., 2024-11-15, 2023-09-15).

How do I import an existing Cosmos DB service?

Use

pulumi import azure-native:cosmosdb:Service <name> /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/services/{serviceName}

with your actual resource identifiers.

Using a different cloud?

Explore database guides for other cloud providers:

AWS Guides GCP Guides