During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in
Provisioning a Cosmos DB Account
This guide shows you how to provision a Cosmos DB Account, a database and a container against Locally. As with the other guides we're going to use the Azure CLI, but the same resources can be provisioned with HashiCorp Terraform, Pulumi or Bicep too.
Before you start
- The Azure CLI (
az) installed. - Locally installed, with Locally Setup completed.
1. Start Locally
Firstly, we need to launch Locally which we can do from a terminal by running:
$
locally build
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:
$
locally run az group create -n sample-resources -l berlin
There's two things to note here:
- The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with
locally run. - 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 runwhen 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:
$
locally run az cosmosdb create --name samplecosmos1 --resource-group sample-resources --locations regionName=berlin
Note
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:
$
locally run az cosmosdb show --name samplecosmos1 --resource-group sample-resources --query "{name:name, kind:kind, documentEndpoint:documentEndpoint, provisioningState:provisioningState}"
4. Create a database and container
An account on its own doesn't hold anything, so next we'll create a database within it:
$
locally run az cosmosdb sql database create --account-name samplecosmos1 --resource-group sample-resources --name appdb
{
"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:
$
locally run az cosmosdb sql container create --account-name samplecosmos1 --resource-group sample-resources --database-name appdb --name orders --partition-key-path /customerId
{
"name": "orders",
"pk": [
"/customerId"
]
}
We can confirm both exist:
$
locally run az cosmosdb sql database list --account-name samplecosmos1 --resource-group sample-resources --query "[].{Name:name}" -o table
Name
------
appdb
$
locally run az cosmosdb sql container list --account-name samplecosmos1 --resource-group sample-resources --database-name appdb --query "[].{Name:name, PartitionKey:resource.partitionKey.paths[0]}" -o table
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:
$
locally run az cosmosdb keys list --name samplecosmos1 --resource-group sample-resources --query primaryMasterKey -o tsv
Hand that pair to the Azure Cosmos DB SDKs and your application reads and writes against Locally.
Note
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:
$
locally run az group delete -n sample-resources --yes
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, reach out in our Discord or open an issue and we'll take a look.
Resource types this guide uses
These are the Azure resource types this guide creates in Locally:
- Microsoft.DocumentDB/databaseAccounts
- Microsoft.DocumentDB/databaseAccounts/sqlDatabases
- Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers
During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in