Skip to main content

Azure Cosmos DB (SQL API)

Type: state.azure.cosmosdb

Status: stable

Reference: https://docs.dapr.io/reference/components-reference/supported-state-stores/setup-azure-cosmosdb/

Warnings

Partition Key Warning

Important: The partition key for the CosmosDB collection must be set to "/partitionKey" or the default "/id". https://docs.dapr.io/reference/components-reference/supported-state-stores/setup-azure-cosmosdb/#setup-azure-cosmosdb

Example

apiVersion: cra.diagrid.io/v1beta1
kind: Component
metadata:
name: <name>
spec:
type: state.azure.cosmosdb
version: v1
metadata:
# The key to authenticate to the Cosmos DB account.
- name: masterKey
value: "my-secret-key"
# The name of the collection (container).
- name: collection
value: "collection"
# The name of the database.
- name: database
value: "db"
# The Cosmos DB url.
- name: url
value: "https://******.documents.azure.com:443/"
# The default content type of the data. (Optional)
#- name: contenttype
# value: "application/json"
# Use this state store as the Workflows Store, it will enable the Workflows API. Defaults to `false`. (Optional)
#- name: enableWorkflow
# value: "false"
# Prefix added to keys in the state store. (Optional)
#- name: keyPrefix
# value: "appid"
# By setting outboxDiscardWhenMissingState to true, Dapr discards the transaction if it cannot find the state in the database and does not retry. This setting can be useful if the state store data has been deleted for any reason before Dapr was able to deliver the message and you would like Dapr to drop the items from the pub/sub and stop retrying to fetch the state (Optional)
#- name: outboxDiscardWhenMissingState
# value: "false"
# For outbox. Sets the name of the pub/sub component to deliver the notifications when publishing state changes (Optional)
#- name: outboxPublishPubsub
# value: ""
# For outbox. Sets the topic that receives the state changes on the pub/sub configured with "outboxPublishPubsub". The message body will be a state transaction item for an insert or update operation (Optional)
#- name: outboxPublishTopic
# value: ""
# For outbox. Sets the pub/sub component used by Dapr to coordinate the state and pub/sub transactions. If not set, the pub/sub component configured with "outboxPublishPubsub" is used. This is useful if you want to separate the pub/sub component used to send the notification state changes from the one used to coordinate the transaction (Optional)
#- name: outboxPubsub
# value: "outboxPublishPubsub"

Authentication profiles

Available authentication profiles:

  • Master key

  • Azure AD: Client credentials

  • Azure AD: Client certificate

Master key

Authenticate using a pre-shared "master key".

masterKey

Required - The key to authenticate to the Cosmos DB account.

Example value: my-secret-key

Azure AD: Client credentials

Authenticate using Azure AD with client credentials, also known as "service principals".

azureClientId

Required - Client ID (application ID)

Example value: c7dd251f-811f-4ba2-a905-acd4d3f8f08b

azureClientSecret

Required - Client secret (application password)

Example value: Ecy3XG7zVZK3/vl/a2NSB+a1zXLa8RnMum/IgD0E

azureTenantId

Required - ID of the Azure AD tenant

Example value: cd4b2887-304c-47e1-b4d5-65447fdd542a

azureEnvironment

Optional name for the Azure environment if using a different Azure cloud

Default value: AzurePublicCloud

Example value: AzurePublicCloud

Allowed values:

  • AzurePublicCloud

  • AzureChinaCloud

  • AzureUSGovernmentCloud

Azure AD: Client certificate

Authenticate using Azure AD with a client certificate. "azureCertificate" is required.

azureClientId

Required - Client ID (application ID)

Example value: c7dd251f-811f-4ba2-a905-acd4d3f8f08b

azureTenantId

Required - ID of the Azure AD tenant

Example value: cd4b2887-304c-47e1-b4d5-65447fdd542a

azureCertificate

Certificate and private key (in either a PEM file containing both the certificate and key, or in PFX/PKCS#12 format)

Example value:

-----BEGIN PRIVATE KEY-----\n MIIEvgI... \n -----END PRIVATE KEY-----
\n -----BEGIN CERTIFICATE----- \n MIICoTC... \n -----END CERTIFICATE----- \n

azureCertificatePassword

Password for the certificate if encrypted.

Example value: password

azureEnvironment

Optional name for the Azure environment if using a different Azure cloud

Default value: AzurePublicCloud

Example value: AzurePublicCloud

Allowed values:

  • AzurePublicCloud

  • AzureChinaCloud

  • AzureUSGovernmentCloud

Metadata

collection (string)

Required - The name of the collection (container).

Example value: collection

database (string)

Required - The name of the database.

Example value: db

url (string)

Required - The Cosmos DB url.

Example value: https://******.documents.azure.com:443/

contenttype (string)

The default content type of the data.

Default value: application/json

Example value: application/json

enableWorkflow (bool)

Use this state store as the Workflows Store, it will enable the Workflows API. Defaults to false.

Example value: false

keyPrefix (string)

Prefix added to keys in the state store.

Default value: appid

Example value: appid

Allowed values:

  • appid

  • name

  • none

Documentation: https://docs.dapr.io/developing-applications/building-blocks/state-management/howto-share-state/

outboxDiscardWhenMissingState (bool)

By setting outboxDiscardWhenMissingState to true, Dapr discards the transaction if it cannot find the state in the database and does not retry. This setting can be useful if the state store data has been deleted for any reason before Dapr was able to deliver the message and you would like Dapr to drop the items from the pub/sub and stop retrying to fetch the state

Default value: false

outboxPublishPubsub (string)

For outbox. Sets the name of the pub/sub component to deliver the notifications when publishing state changes

outboxPublishTopic (string)

For outbox. Sets the topic that receives the state changes on the pub/sub configured with "outboxPublishPubsub". The message body will be a state transaction item for an insert or update operation

outboxPubsub (string)

For outbox. Sets the pub/sub component used by Dapr to coordinate the state and pub/sub transactions. If not set, the pub/sub component configured with "outboxPublishPubsub" is used. This is useful if you want to separate the pub/sub component used to send the notification state changes from the one used to coordinate the transaction

Default value: outboxPublishPubsub