Deploy Azure Cosmos DB

The azure-native:cosmosdb:Service resource, part of the Pulumi Azure Native provider, provisions add-on services for Cosmos DB database accounts: integrated caching, data transfer, materialized views, and graph compute. This guide focuses on four capabilities: integrated cache with dedicated gateway, data transfer between accounts, materialized views for analytics, and graph API compute provisioning.

Services attach to existing Cosmos DB database accounts within a resource group. The examples are intentionally small. Combine them with your own Cosmos DB accounts and monitoring configuration.

Add an integrated cache with dedicated gateway

Applications with read-heavy workloads benefit from an integrated cache that reduces latency and request unit consumption by serving frequently accessed data from memory.

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 dedicated gateway service. The dedicatedGatewayType property sets the cache mode to “IntegratedCache”, which stores frequently accessed data in memory. The instanceSize and instanceCount properties control the compute resources allocated to the gateway.

Enable data transfer between Cosmos DB accounts

Teams migrating data or synchronizing across regions use the DataTransfer service to move data 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 specifies “DataTransfer” to enable the data transfer service. The instanceSize property determines the compute capacity allocated for transfer operations, while instanceCount controls how many instances run in parallel. This service handles data movement between Cosmos DB accounts within or across regions.

Build materialized views for query optimization

Analytics workloads that repeatedly query aggregated data benefit from materialized views that pre-compute and store query results for faster access.

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 specifies “MaterializedViewsBuilder” to enable the materialized views service. This service pre-computes and maintains aggregated query results, reducing the computational cost of repeated analytical queries. The instanceSize and instanceCount properties determine the resources available for building and updating views.

Provision compute for graph queries

Graph databases running complex traversal queries need dedicated compute resources to handle the processing demands of relationship-heavy workloads.

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 specifies “GraphAPICompute” to allocate dedicated compute for graph operations. Graph traversal and pattern matching queries benefit from dedicated resources that don’t compete with other database operations. The instanceSize and instanceCount properties control the compute capacity available for graph queries.

Beyond these examples

These snippets focus on specific service-level features: service provisioning (caching, data transfer, materialized views, graph compute) and instance sizing and scaling. They’re intentionally minimal rather than full database deployments.

The examples reference pre-existing infrastructure such as Cosmos DB database accounts and Azure 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-specific configuration beyond instance sizing
Monitoring and diagnostics setup
Cost optimization strategies
High availability and disaster recovery

These omissions are intentional: the goal is to illustrate how each service type is wired, not provide drop-in production 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 Types & Configuration

What types of Cosmos DB services can I create?

You can create four service types: DataTransfer, GraphAPICompute, MaterializedViewsBuilder, and SqlDedicatedGateway. Specify the type using the serviceType property in the service configuration.

What's the dedicatedGatewayType property used for?

The dedicatedGatewayType property configures the gateway type for SqlDedicatedGateway services. The examples show IntegratedCache as a valid value.

Resource Management

What properties can't be changed after creating the service?

Three properties are immutable: accountName, resourceGroupName, and serviceName. Changing any of these requires replacing the resource.

How do I use a different Azure API version for this resource?

Generate a local SDK package using the Pulumi CLI command: pulumi package add azure-native cosmosdb [ApiVersion]. Multiple API versions are available, from 2021-04-01-preview through 2025-05-01-preview.

Using a different cloud?

Explore database guides for other cloud providers:

AWS Guides GCP Guides