NATS Streaming

Detailed documentation on the NATS Streaming pubsub component

Component format

To setup NATS Streaming pubsub create a component of type pubsub.natsstreaming. See this guide on how to create and apply a pubsub configuration.

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

Warning

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

Spec metadata fields

FieldRequiredDetailsExample
natsURLYNATS server address URL“nats://localhost:4222”
natsStreamingClusterIDYNATS cluster ID“clusterId”
subscriptionTypeYSubscription type. Allowed values “topic”, “queue”“topic”
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)”
startAtTimeDeltaNMust be used with startAtTime. Sets the format for the time“Jan 2, 2006 at 3:04pm (MST)”

Create a NATS server

You can run a NATS server locally using Docker:

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

You can then 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: kubectl get svc stan.

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

<YOUR-HOST>:4222

Last modified May 26, 2021: Update to point to 1.2 (#1518) (c690379)