Scaling read and write throughput automatically with Cosmos DB MongoCollection

Question

Pulumi · Accepted Answer

To set up automatic scaling of read and write throughput on a Cosmos DB MongoCollection, you'll be utilizing the Pulumi Azure provider to create a MongoCollection within a Cosmos DB account and database. In Pulumi, this requires setting up several resources in a particular order:

1. A resource group to contain all the Azure resources.
2. A Cosmos DB account configured to support MongoDB.
3. A MongoDB database within the Cosmos DB account.
4. A MongoCollection with autoscale settings enabled.

**Here's why each step is important:**

- The **resource group** provides a logical container for your Azure resources which helps with organization and access control.
- The **Cosmos DB account** sets up the service that will host your database and determines features like the API type (MongoDB in this case), and geographic presence.
- Within the account, you create a **MongoDB database** which is an organizational unit within Cosmos DB that you can think of like a namespace under which you can create collections.
- Finally, **MongoCollection** is an entity within the MongoDB database that holds your data. You’ll define autoscale settings on the MongoCollection which allows Azure to automatically scale the throughput (measured in Request Units or RU/s) in response to the load.

To achieve autoscaling, you specify `autoscaleSettings` with an `maxThroughput` property on the MongoCollection. This value is the maximum RU/s that the collection can automatically scale to.

**Here's a Pulumi TypeScript program that sets up these resources:**

```typescript
import * as pulumi from "@pulumi/pulumi";
import * as azure from "@pulumi/azure";

// Create an Azure Resource Group
const resourceGroup = new azure.core.ResourceGroup("myResourceGroup");

// Create an Azure Cosmos DB Account with MongoDB support
const cosmosDbAccount = new azure.cosmosdb.Account("myCosmosDbAccount", {
    resourceGroupName: resourceGroup.name,
    offerType: "Standard", // For production use, you might choose other types like "Business" or "Enterprise" depending on your needs.
    kind: "MongoDB",       // We specify MongoDB as this is a MongoCollection.
    geoLocations: [{
        location: resourceGroup.location,
        failoverPriority: 0,
    }],
    consistencyPolicy: {
        consistencyLevel: "Session",  // Session consistency is a good default. Other values include 'BoundedStaleness', 'Strong', or 'Eventual'.
    },
    enableAutomaticFailover: true, // We want the DB to be resilient to regional outages.
});

// Create a MongoDB Database
const mongoDatabase = new azure.cosmosdb.MongoDatabase("myMongoDatabase", {
    name: "myDatabase",
    resourceGroupName: resourceGroup.name,
    accountName: cosmosDbAccount.name,
});

// Create a MongoCollection with autoscaling enabled
const mongoCollection = new azure.cosmosdb.MongoCollection("myMongoCollection", {
    name: "myCollection",
    resourceGroupName: resourceGroup.name,
    accountName: cosmosDbAccount.name,
    databaseName: mongoDatabase.name,
    throughput: 400,  // Initial throughput,
    autoscaleSettings: {
        maxThroughput: 4000,  // Maximum throughput. The autoscaler won't go beyond this.
    },
});

// Export the connection strings for the Cosmos DB account to use them in your application
export const primaryConnectionString = cosmosDbAccount.primaryMasterKey.apply(
    key => `mongodb://@${cosmosDbAccount.endpoint}:443/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@pulumi&account-key=${key}`
);

```

This program will create a Cosmos DB account with a MongoDB-compatible database and a collection with autoscale enabled. The throughput settings in `autoscaleSettings` indicate the resources provisioned for this collection can scale up and down between the specified values depending on load automatically.

It's important to note that each resource creation (ResourceGroup, Account, MongoDatabase, MongoCollection) is a TypeScript class instantiation that requires a set of arguments. These arguments set properties like names, locations, types, settings, and dependencies on other resources.

Lastly, we export the primary connection string for the Cosmos DB account so that you can use it to connect to your database externally. Ensure that you handle this connection string securely as it provides access to your Cosmos DB account.