New Azure Cosmos DB PowerShell features for greater enterprise manageability

Patrick El-Azem

Enterprise Manageability

Azure Cosmos DB enterprise manageability and readiness continues to mature, with multiple management libraries available. The Az.CosmosDB PowerShell package lets you directly manage Azure Cosmos DB accounts, databases, containers, throughput, and more across all Azure Cosmos DB APIs. Az.CosmosDB is in public preview with General Availability (GA) expected later this year.

In my previous post about Az.CosmosDB, I introduced it and discussed how to start working with it. In this post, I’ll show some examples for how to work directly with Azure Cosmos DB resources using the PowerShell cmdlets, and I’ll also note several Az.CosmosDB additions to let customers manage new Azure Cosmos DB capabilities including autoscale, analytical storage, free tier, and MongoDB API Server version.

NOTE: you will need Az.CosmosDB 0.1.6 or newer to use the new capabilities discussed below.

Manage Azure Cosmos DB Resources using Cmdlets

The Az.CosmosDB cmdlets enable detailed management of Azure Cosmos DB resources. Below I show you a complete PowerShell script that completes several steps, starting with creation of a new Azure Resource Group with New-AzResourceGroup.

Then I use New-AzCosmosDBAccount to deploy a new Azure Cosmos DB account configured for Azure Cosmos DB’s API for MongoDB with compatibility level 3.6 and enabled for analytical store (more on that later in this post). After that, I use New-AzCosmosDBMongoDBDatabase to deploy a new database into my new account.

Next, I use New-AzCosmosDBMongoDBIndex to create a new unique index definition with the partition keys. This is one of many cmdlets provided in the Az.CosmosDB package for very granular management of Azure Cosmos DB resources and configurations.

Last, I use New-AzCosmosDBMongoDBCollection to create a new container in the database with the index I created above and configured to enable analytical store and autoscale (more on that later in this post) to a maximum of 4,000 RU/s.

Autoscale

Autoscale provisioned throughput is described in this post and the Azure Cosmos DB documentation. Both databases and containers can be configured with autoscale.

The Az.CosmosDB cmdlets for database and container management accept a new parameter, -AutoscaleMaxThroughput. For example, to configure a container to autoscale instantly up to a maximum of 4,000 RU/s:

New-AzCosmosDbSqlContainer [...] -AutoscaleMaxThroughput 4000

You can update the configured autoscale max throughput. For example, to increase the autoscale max throughput from 4,000 to 6,000 RU/s:

Update-AzCosmosDbSqlContainer [...] -AutoscaleMaxThroughput 6000

NOTE: Use either -AutoscaleMaxThroughput(for autoscale throughput) or -Throughput (for standard throughput) – do not use both together.

Analytical store

Azure Cosmos DB analytical store is a component of Azure Synapse Link, described in this post and the Azure Cosmos DB documentation.

To use Azure Cosmos DB analytical store with Azure Synapse Link, first enable analytical store on a new account using New-AzCosmosDBAccount [...] -EnableAnalyticalStorage $true, or on an existing account using Update-AzCosmosDBAccount [...] -EnableAnalyticalStorage $true.

Then create new containers with analytical store enabled by using the -AnalyticalStoreTtl parameter. Currently, API for MongoDB collections and Cassandra API tables can be enabled for Analytical Store using New-AzCosmosDBMongoDBCollection or New-AzCosmosDBCassandraTable, and additional Azure Cosmos DB APIs will be supported by GA.

MongoDB API – Set Server Version

New-AzCosmosDBAccount now accepts a -ServerVersion parameter to specify the MongoDB compatibility level for the new  API for MongoDB account. For example: New-AzCosmosDBAccount [...] -ApiKind "MongoDB" -ServerVersion "3.6"

Enable free tier

Free tier was introduced on a previous post. With free tier, you receive 400 RU/s throughput and 5 GB storage each month for free for the life of the Azure Cosmos DB account on which it is configured.

Free tier is available for one Azure Cosmos DB account per Azure subscription and must be configured when the Azure Cosmos DB account is created:

New-AzCosmosDBAccount [...] -EnableFreeTier $true

More Information

PowerShell management samples are available for each of the Azure Cosmos DB APIs:

• Core (SQL) API samples
• API for MongoDB samples
• Cassandra API samples
• Gremlin API samples
• Table API samples

References, source code, and issues:

• Manage Azure Cosmos DB Core (SQL) API resources using PowerShell
• Az.CosmosDB cmdlet reference
• Az.CosmosDB source code on GitHub
• Bugs or feature requests on GitHub

Wrapping Up

We are excited that Azure Cosmos DB continues to add enterprise manageability capabilities. We hope the ongoing improvements to the Az.CosmosDB management library are helpful as you manage your Azure Cosmos DB resources.

Patrick El-Azem Cloud Solution Architect, Customer Architecture Team

Follow