Subscription spec

The basic spec for a Dapr subscription

The Subscription Dapr resource allows you to subscribe declaratively to a topic using an external component YAML file. This guide demonstrates two subscription API versions:

  • v2alpha (default spec)
  • v1alpha1 (deprecated)

v2alpha1 format

The following is the basic v2alpha1 spec for a Subscription resource. v2alpha1 is the default spec for the subscription API.

  1. apiVersion: dapr.io/v2alpha1
  2. kind: Subscription
  3. metadata:
  4.   name: <REPLACE-WITH-NAME>
  5. spec:
  6.   version: v2alpha1
  7.   topic: <REPLACE-WITH-TOPIC-NAME> # Required
  8.   routes: # Required
  9.   - rules:
  10.     - match: <REPLACE-WITH-EVENT-TYPE>
  11.       path: <REPLACE-WITH-PATH>
  12.   pubsubname: <REPLACE-WITH-PUBSUB-NAME> # Required
  13.   deadlettertopic: <REPLACE-WITH-TOPIC-NAME> # Optional
  14.   bulksubscribe: # Optional
  15.   - enabled: <REPLACE-WITH-TOPIC-NAME> 
  16.   - maxmessages: <REPLACE-WITH-TOPIC-NAME>
  17.   - maxawaitduration: <REPLACE-WITH-TOPIC-NAME>
  18. scopes:
  19. - <REPLACE-WITH-SCOPED-APPIDS>

Spec fields

FieldRequiredDetailsExample
topicYThe name of the topic to which your component subscribes.orders
routesYThe routes configuration for this topic, including specifying the condition for sending a message to a specific path. Includes the following fields:
  • match: Optional. The CEL expression used to match the event. If not specified, the route is considered the default.
  • path: The path for events that match this rule.
The endpoint to which all topic messages are sent.		match: event.type == “widget”
path: /widgets
pubsubnameNThe name of your pub/sub component.pubsub
deadlettertopicNThe name of the dead letter topic that forwards undeliverable messages.poisonMessages
bulksubscribeNEnable bulk subscribe properties.true, false

v1alpha1 format

The following is the basic version v1alpha1 spec for a Subscription resource. v1alpha1 is now deprecated.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Subscription
  3. metadata:
  4.   name: <REPLACE-WITH-RESOURCE-NAME>
  5. spec:
  6.   version: v1alpha1
  7.   topic: <REPLACE-WITH-TOPIC-NAME> # Required
  8.   route: <REPLACE-WITH-ROUTE-NAME> # Required
  9.   pubsubname: <REPLACE-WITH-PUBSUB-NAME> # Required
  10.   deadLetterTopic: <REPLACE-WITH-DEAD-LETTER-TOPIC-NAME> # Optional
  11.   bulkSubscribe: # Optional
  12.   - enabled: <REPLACE-WITH-BOOLEAN-VALUE>
  13.   - maxmessages: <REPLACE-WITH-VALUE>
  14.   - maxawaitduration: <REPLACE-WITH-VALUE>
  15. scopes:
  16. - <REPLACE-WITH-SCOPED-APPIDS>

Spec fields

FieldRequiredDetailsExample
topicYThe name of the topic to which your component subscribes.orders
routeYThe endpoint to which all topic messages are sent./checkout
pubsubnameNThe name of your pub/sub component.pubsub
deadlettertopicNThe name of the dead letter topic that forwards undeliverable messages.poisonMessages
bulksubscribeNEnable bulk subscribe properties.true, false

Last modified October 12, 2023: Update config.toml (#3826) (0ffc2e7)