Provisioning a Cosmos DB Account

1. Start Locally

Firstly, we need to launch Locally which we can do from a terminal by running:

Once Locally has started, the Locally Dashboard will open automatically:

2. Create a Resource Group

Next we can create the Resource Group to hold the account:

There's two things to note here:

1. The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with locally run.
2. Locally intentionally uses a different set of locations to Azure as a safety precaution, so that you can be confident you're deploying against Locally rather than regular Azure. You can also configure Locally to use the Azure locations too, but you'll want to be extra sure that you're prefixing commands with locally run when you do.

3. Create the Cosmos DB Account

With the Resource Group in place, we can create the Cosmos DB Account. Unlike most resources, the location is given as a --locations entry rather than --location, because a Cosmos DB Account can span several regions:

The interesting part of the response is the documentEndpoint, which is where the data plane lives:

{
  "note": "some fields skipped for brevity",

  "documentEndpoint": "https://samplecosmos1.cosmonaut.locally:5665/",
  "kind": "GlobalDocumentDB",
  "location": "berlin",
  "name": "samplecosmos1",
  "provisioningState": "Succeeded",
  "resourceGroup": "sample-resources",
  "type": "Microsoft.DocumentDB/databaseAccounts"
}

That cosmonaut.locally hostname is served by Locally's own DNS server and points at the Cosmos DB Emulator running on your machine. Tools run through locally run reach it as they would Azure, and apps built on the Azure SDKs need a few lines of setup.

We can retrieve the account again at any point with:

4. Create a database and container

An account on its own doesn't hold anything, so next we'll create a database within it:

{
  "name": "appdb",
  "type": "Microsoft.DocumentDB/databaseAccounts/sqlDatabases"
}

Then a container inside that database. A container needs a partition key, which Cosmos uses to distribute documents - here we'll partition orders by the customer they belong to:

{
  "name": "orders",
  "pk": [
    "/customerId"
  ]
}

We can confirm both exist:

Name
------
appdb

Name    PartitionKey
------  --------------
orders  /customerId

5. Get the endpoint and key

To read and write documents, an application needs the account's endpoint and key. The endpoint is the documentEndpoint above, and the keys come from:

Hand that pair to the Azure Cosmos DB SDKs and your application reads and writes against Locally.

We can see the Cosmos DB Account in the Locally Dashboard too:

6. Tidy up

Finally, we can tidy up. To remove the Resource Group and everything within it:

There's nothing billable to clean up, since everything ran on your machine, but it's still worth checking your teardown scripts work here before you run them against Azure.

Doing this with other tooling

Whilst this guide used the Azure CLI, Cosmos DB works the same way through any of the tooling that Locally supports - Microsoft.DocumentDB/databaseAccounts and its child resources in HashiCorp Terraform or OpenTofu, Pulumi, Bicep or an ARM Template all provision against Locally in the same way, with only the location changed.

Next steps

The Cosmos DB Emulator covers what the data plane supports. To keep the account key out of your app's settings, store it in a Key Vault.

Should you encounter any issues, please take a look at the troubleshooting section.