JetStream

Detailed documentation on the NATS JetStream component

Component format

To set up JetStream pub/sub, create a component of type pubsub.jetstream. 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: jetstream-pubsub
  5. spec:
  6.   type: pubsub.jetstream
  7.   version: v1
  8.   metadata:
  9.   - name: natsURL
  10.     value: "nats://localhost:4222"
  11.   - name: jwt # Optional. Used for decentralized JWT authentication.
  12.     value: "eyJhbGciOiJ...6yJV_adQssw5c"
  13.   - name: seedKey # Optional. Used for decentralized JWT authentication.
  14.     value: "SUACS34K232O...5Z3POU7BNIL4Y"
  15.   - name: tls_client_cert # Optional. Used for TLS Client authentication.
  16.     value: "/path/to/tls.crt"
  17.   - name: tls_client_key # Optional. Used for TLS Client authentication.
  18.     value: "/path/to/tls.key"
  19.   - name: token # Optional. Used for token based authentication.
  20.     value: "my-token"
  21.   - name: consumerID
  22.     value: "channel1"
  23.   - name: name
  24.     value: "my-conn-name"
  25.   - name: streamName
  26.     value: "my-stream"
  27.   - name: durableName 
  28.     value: "my-durable"
  29.   - name: queueGroupName
  30.     value: "my-queue"
  31.   - name: startSequence
  32.     value: 1
  33.   - name: startTime # In Unix format
  34.     value: 1630349391
  35.   - name: flowControl
  36.     value: false
  37.   - name: ackWait
  38.     value: 10s
  39.   - name: maxDeliver
  40.     value: 5
  41.   - name: backOff
  42.     value: "50ms, 1s, 10s"
  43.   - name: maxAckPending
  44.     value: 5000
  45.   - name: replicas
  46.     value: 1
  47.   - name: memoryStorage
  48.     value: false
  49.   - name: rateLimit
  50.     value: 1024
  51.   - name: heartbeat
  52.     value: 15s
  53.   - name: ackPolicy
  54.     value: explicit
  55.   - name: deliverPolicy
  56.     value: all
  57.   - name: domain
  58.     value: hub
  59.   - name: apiPrefix
  60.     value: PREFIX

Spec metadata fields

FieldRequiredDetailsExample
natsURLYNATS server address URL“nats://localhost:4222”
jwtNNATS decentralized authentication JWT“eyJhbGciOiJ…6yJV_adQssw5c”
seedKeyNNATS decentralized authentication seed key“SUACS34K232O…5Z3POU7BNIL4Y”
tls_client_certNNATS TLS Client Authentication Certificate“/path/to/tls.crt”
tls_client_keyNNATS TLS Client Authentication Key“/path/to/tls.key”
tokenNNATS token based authentication“my-token”
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”
nameNNATS connection name“my-conn-name”
streamNameNName of the JetStream Stream to bind to“my-stream”
durableNameNDurable name“my-durable”
queueGroupNameNQueue group name“my-queue”
startSequenceNStart Sequence1
startTimeNStart Time in Unix format1630349391
flowControlNFlow Controltrue
ackWaitNAck Wait10s
maxDeliverNMax Deliver15
backOffNBackOff“50ms, 1s, 5s, 10s”
maxAckPendingNMax Ack Pending5000
replicasNReplicas3
memoryStorageNMemory Storagefalse
rateLimitNRate Limit1024
heartbeatNHeartbeat10s
ackPolicyNAck Policyexplicit
deliverPolicyNOne of: all, last, new, sequence, timeall
domainN[JetStream Leafondes]HUB
apiPrefixN[JetStream Leafnodes]PREFIX

Create a NATS server

You can run a NATS Server with JetStream enabled locally using Docker:

  1. docker run -d -p 4222:4222 nats:latest -js

You can then interact with the server using the client port: localhost:4222.

Install NATS JetStream on Kubernetes by using the helm:

  1. helm repo add nats https://nats-io.github.io/k8s/helm/charts/
  2. helm install --set nats.jetstream.enabled=true my-nats nats/nats

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

  1. kubectl get svc my-nats

For more information on helm chart settings, see the Helm chart documentation.

Create JetStream

It is essential to create a NATS JetStream for a specific subject. For example, for a NATS server running locally use:

  1. nats -s localhost:4222 stream add myStream --subjects mySubject

Last modified June 19, 2023: Merge pull request #3565 from dapr/aacrawfi/skip-secrets-close (b1763bf)