NATS Streaming

Detailed documentation on the NATS Streaming pubsub component

⚠️ Deprecation notice

Warning

This component is deprecated because the NATS Streaming Server was deprecated in June 2023 and no longer receives updates. Users are encouraged to switch to using [JetStream](https://docs.dapr.io/reference/components-reference/supported-pubsub/setup-jetstream/ as an alternative.

This component will be **removed in the Dapr v1.13 release.

Component format

To set up NATS Streaming pub/sub, create a component of type pubsub.natsstreaming. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: natsstreaming-pubsub
  5. spec:
  6.   type: pubsub.natsstreaming
  7.   version: v1
  8.   metadata:
  9.   - name: natsURL
  10.     value: "nats://localhost:4222"
  11.   - name: natsStreamingClusterID
  12.     value: "clusterId"
  13.   - name: concurrencyMode
  14.     value: parallel
  15.   - name: consumerID # Optional. If not supplied, runtime will create one.
  16.     value: "channel1" 
  17.     # below are subscription configuration.
  18.   - name: subscriptionType
  19.     value: <REPLACE-WITH-SUBSCRIPTION-TYPE> # Required. Allowed values: topic, queue.
  20.   - name: ackWaitTime
  21.     value: "" # Optional.
  22.   - name: maxInFlight
  23.     value: "" # Optional.
  24.   - name: durableSubscriptionName
  25.     value: "" # Optional.
  26.   # following subscription options - only one can be used
  27.   - name: deliverNew
  28.     value: <bool>
  29.   - name: startAtSequence
  30.     value: 1
  31.   - name: startWithLastReceived
  32.     value: false
  33.   - name: deliverAll
  34.     value: false
  35.   - name: startAtTimeDelta
  36.     value: ""
  37.   - name: startAtTime
  38.     value: ""
  39.   - name: startAtTimeFormat
  40.     value: ""

Warning

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

Spec metadata fields

FieldRequiredDetailsExample
natsURLYNATS server address URL“nats://localhost:4222”
natsStreamingClusterIDYNATS cluster ID“clusterId”
subscriptionTypeYSubscription type. Allowed values “topic”, “queue”“topic”
consumerIDNConsumer ID (consumer tag) organizes one or more consumers into a group. Consumers with the same consumer ID work as one virtual consumer; for example, a message is processed only once by one of the consumers in the group. If the consumerID is not provided, the Dapr runtime set it to the Dapr application ID (appID) value.“channel1”
ackWaitTimeNSee here“300ms”
maxInFlightNSee here“25”
durableSubscriptionNameNDurable subscriptions identification name.“my-durable”
deliverNewNSubscription Options. Only one can be used. Deliver new messages only“true”, “false”
startAtSequenceNSubscription Options. Only one can be used. Sets the desired start sequence position and state“100000”, “230420”
startWithLastReceivedNSubscription Options. Only one can be used. Sets the start position to last received.“true”, “false”
deliverAllNSubscription Options. Only one can be used. Deliver all available messages“true”, “false”
startAtTimeDeltaNSubscription Options. Only one can be used. Sets the desired start time position and state using the delta“10m”, “23s”
startAtTimeNSubscription Options. Only one can be used. Sets the desired start time position and state“Feb 3, 2013 at 7:54pm (PST)”
startAtTimeFormatNMust be used with startAtTime. Sets the format for the time“Jan 2, 2006 at 3:04pm (MST)”
concurrencyModeNCall the subscriber sequentially (“single” message at a time), or concurrently (in “parallel”). Default: “parallel”“single”, “parallel”

Create a NATS server

Run a NATS server locally using Docker:

  1. docker run -d --name nats-streaming -p 4222:4222 -p 8222:8222 nats-streaming

Interact with the server using the client port: localhost:4222.

Install NATS on Kubernetes by using the kubectl:

  1. # Single server NATS
  3. kubectl apply -f https://raw.githubusercontent.com/nats-io/k8s/master/nats-server/single-server-nats.yml
  5. kubectl apply -f https://raw.githubusercontent.com/nats-io/k8s/master/nats-streaming-server/single-server-stan.yml

This installs a single NATS-Streaming and NATS into the default namespace. To interact with NATS, find the service with:

  1. kubectl get svc stan

For example, if installing using the example above, the NATS Streaming address would be:

<YOUR-HOST>:4222

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