Azure Cosmos DB

Detailed information on the Azure CosmosDB state store component

Component format

To setup Azure CosmosDb state store create a component of type state.azure.cosmosdb. See this guide on how to create and apply a state store configuration.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: <NAME>
  5. namespace: <NAMESPACE>
  6. spec:
  7. type: state.azure.cosmosdb
  8. version: v1
  9. metadata:
  10. - name: url
  11. value: <REPLACE-WITH-URL>
  12. - name: masterKey
  13. value: <REPLACE-WITH-MASTER-KEY>
  14. - name: database
  15. value: <REPLACE-WITH-DATABASE>
  16. - name: collection
  17. value: <REPLACE-WITH-COLLECTION>

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

If you wish to use CosmosDb as an actor store, append the following to the yaml.

  1. - name: actorStateStore
  2. value: "true"

Spec metadata fields

FieldRequiredDetailsExample
urlYThe CosmosDB urlhttps://******.documents.azure.com:443/.
masterKeyYThe key to authenticate to the CosmosDB account“key”
databaseYThe name of the database“db”
collectionYThe name of the collection“collection”
actorStateStoreNConsider this state store for actors. Defaults to “false”“true”, “false”

Setup Azure Cosmos DB

Follow the instructions from the Azure documentation on how to create an Azure CosmosDB account. The database and collection must be created in CosmosDB before Dapr can use it.

Note : The partition key for the collection must be named “/partitionKey”. Note: this is case-sensitive.

In order to setup CosmosDB as a state store, you need the following properties:

Data format

To use the CosmosDB state store, your data must be sent to Dapr in JSON-serialized. Having it just JSON serializable will not work.

If you are using the Dapr SDKs (e.g. https://github.com/dapr/dotnet-sdk) the SDK will serialize your data to json.

For examples see the curl operations in the Partition keys section.

Partition keys

For non-actor state operations, the Azure Cosmos DB state store will use the key property provided in the requests to the Dapr API to determine the Cosmos DB partition key. This can be overridden by specifying a metadata field in the request with a key of partitionKey and a value of the desired partition.

The following operation will use nihilus as the partition key value sent to CosmosDB:

  1. curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  2. -H "Content-Type: application/json"
  3. -d '[
  4. {
  5. "key": "nihilus",
  6. "value": "darth"
  7. }
  8. ]'

For non-actor state operations, if you want to control the CosmosDB partition, you can specify it in metadata. Reusing the example above, here’s how to put it under the mypartition partition

  1. curl -X POST http://localhost:3500/v1.0/state/<store_name> \
  2. -H "Content-Type: application/json"
  3. -d '[
  4. {
  5. "key": "nihilus",
  6. "value": "darth",
  7. "metadata": {
  8. "partitionKey": "mypartition"
  9. }
  10. }
  11. ]'

For actor state operations, the partition key is generated by Dapr using the appId, the actor type, and the actor id, such that data for the same actor always ends up under the same partition (you do not need to specify it). This is because actor state operations must use transactions, and in CosmosDB the items in a transaction must be on the same partition.

Last modified September 17, 2021 : Merge pull request #1757 from georgestevens99/1440SecretKeyRefExplanation (620a5f8)