The documentation you are viewing is for Dapr v1.12 which is an older version of Dapr. For up-to-date documentation, see the latest version.

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.

apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
  name: <REPLACE-WITH-NAME>
spec:
  topic: <REPLACE-WITH-TOPIC-NAME> # Required
  routes: # Required
  - rules:
    - match: <REPLACE-WITH-CEL-FILTER>
      path: <REPLACE-WITH-PATH>
  pubsubname: <REPLACE-WITH-PUBSUB-NAME> # Required
  deadLetterTopic: <REPLACE-WITH-DEADLETTERTOPIC-NAME> # Optional
  bulkSubscribe: # Optional
  - enabled: <REPLACE-WITH-BOOLEAN-VALUE>
  - maxMessagesCount: <REPLACE-WITH-VALUE>
  - maxAwaitDurationMs: <REPLACE-WITH-VALUE>
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>

Spec fields

Field Required Details Example
topic Y The name of the topic to which your component subscribes. orders
routes Y The routes configuration for this topic, including specifying the condition for sending a message to a specific path. Includes the following fields:
  • match: 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
pubsubname N The name of your pub/sub component. pubsub
deadLetterTopic N The name of the dead letter topic that forwards undeliverable messages. poisonMessages
bulkSubscribe N Enable bulk subscribe properties. true, false

v1alpha1 format

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

apiVersion: dapr.io/v1alpha1
kind: Subscription
metadata:
  name: <REPLACE-WITH-RESOURCE-NAME>
spec:
  topic: <REPLACE-WITH-TOPIC-NAME> # Required
  route: <REPLACE-WITH-ROUTE-NAME> # Required
  pubsubname: <REPLACE-WITH-PUBSUB-NAME> # Required
  deadLetterTopic: <REPLACE-WITH-DEAD-LETTER-TOPIC-NAME> # Optional
  bulkSubscribe: # Optional
  - enabled: <REPLACE-WITH-BOOLEAN-VALUE>
  - maxMessagesCount: <REPLACE-WITH-VALUE>
  - maxAwaitDurationMs: <REPLACE-WITH-VALUE>
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>

Spec fields

Field Required Details Example
topic Y The name of the topic to which your component subscribes. orders
route Y The endpoint to which all topic messages are sent. /checkout
pubsubname N The name of your pub/sub component. pubsub
deadlettertopic N The name of the dead letter topic that forwards undeliverable messages. poisonMessages
bulksubscribe N Enable bulk subscribe properties. true, false

Last modified December 2, 2023: Fix Subscription docs to match Kubernetes CRDs (#3888) (64601692)