Story 03 · JetStream

Manage JetStream on a NATS cluster that you did not deploy

Contents

This guide shows you how to declare streams, consumers, a key-value bucket and an object store as Kubernetes resources on a NATS cluster that the cluster controller did not deploy, and how to adopt streams that already exist without recreating them. The manifests reach a NATS cluster in the namespace messaging and declare everything in the namespace payments.

Before you begin#

You need:

  • A Kubernetes cluster with the JetStream controller installed. Install shows how.
  • The namespace payments.
  • A NATS cluster with JetStream that pods in payments can reach. The manifests use the client address tls://nats.messaging.svc:4222.
  • In payments, a Secret payments-secrets with the creds of a user in the account that you manage, under the key nats.creds, and a Secret messaging-nats-ca with the CA of the NATS cluster under the key ca.crt. Whoever runs the auth plane of that NATS cluster gives you the creds.
  • To follow every fork of this guide, the streams PAYMENTS and LEDGER in that account, created by something other than the JetStream controller.

Connect to the NATS cluster#

Apply a NatsConnection with the address, the CA and the creds. Every resource that uses it lands in the account that the creds sign in to.

01-natsconnection.yaml yaml ·
apiVersion: nats-operator.io/v1beta1
kind: NatsConnection
metadata:
  name: shared-payments
  namespace: payments
spec:
  servers: ["tls://nats.messaging.svc:4222"]
  tls:
    ca:
      secretKeyRef:
        name: messaging-nats-ca
  credentials:
    secretKeyRef:
      name: payments-secrets
      key: nats.creds
kubectl apply -f https://nats-operator.io/docs/stories/03-unmanaged/01-natsconnection.yaml

Adopt the streams#

Apply three NatsStreams. Each one takes a different path with a stream that it did not create:

  • payments sets adoptionPolicy: Adopt. Use Adopt to adopt a stream that exists and keep its config: the spec needs only the fields that identify the stream. If the stream does not exist, the resource waits with Adopted False, reason NotFound, and does not create it.
  • refunds sets adoptionPolicy: AdoptOrCreate. Use AdoptOrCreate to adopt the stream if it exists and create it if not. The JetStream controller applies the spec as written either way.
  • ledger leaves adoptionPolicy at its default, Never, and sets terminalPolicy: Retry.
01-natsstreams.yaml yaml ·
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: payments
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  adoptionPolicy: Adopt
  name: PAYMENTS
---
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: refunds
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  adoptionPolicy: AdoptOrCreate
  name: REFUNDS
  subjects: ["refunds.>"]
  storage: File
  replicas: 3
  maxAge: 2160h
---
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: ledger
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  terminalPolicy: Retry
  name: LEDGER
  subjects: ["ledger.>"]
  replicas: 3
kubectl apply -f https://nats-operator.io/docs/stories/03-unmanaged/01-natsstreams.yaml

AdoptionPolicy and TerminalPolicy in the API reference describe each value. Lifecycle policies in the design describes ownership.

Check the adopted stream#

Read payments:

kubectl -n payments get natsstream payments -o yaml

The JetStream controller has written the config of the stream into the spec. The output is similar to this:

01-live-natsstream-payments.yaml yaml ·
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: payments
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  adoptionPolicy: Adopt
  name: PAYMENTS
  subjects: ["payments.>"]
  storage: File
  replicas: 3
  retention: Limits
  maxAge: 168h0m0s
  maxBytes: "-1"
  discard: Old

The status in the output is similar to this:

01-status-natsstream-payments.yaml yaml ·
status:
  observedGeneration: 2
  conditions:
    - type: Ready
      status: "True"
      reason: Synced
    - type: Adopted
      status: "True"
      reason: FoundUnowned
      message: adopted existing stream PAYMENTS; spec written from the server
      lastTransitionTime: "2026-09-26T09:12:05Z"
    - type: Synced
      status: "True"
      reason: MatchesSpec
  lastSyncedTime: "2026-09-26T09:42:05Z"
  ownership:
    origin: Adopted
    uid: 0f7c1a92-8e44-4a0b-b3a5-6c2de0f19b77
  server:
    leader: nats-1
    messages: 3810442
    bytes: 2Gi

Check the stream that was not adopted#

Read ledger:

kubectl -n payments get natsstream ledger -o yaml

LEDGER exists and the JetStream controller does not own it, so the resource stops and the stream on the server stays as it is. The status in the output is similar to this:

01-status-natsstream-ledger.yaml yaml ·
status:
  observedGeneration: 1
  conditions:
    - type: Ready
      status: "False"
      reason: Terminal
    - type: Terminal
      status: "True"
      reason: ExistsUnowned
      message: >-
        stream LEDGER exists and carries no ownership marker; set
        spec.adoptionPolicy to Adopt or AdoptOrCreate to take it over
      lastTransitionTime: "2026-09-26T09:12:06Z"
  nextCheckTime: "2026-09-26T09:22:06Z"

To take LEDGER over, set adoptionPolicy to Adopt or AdoptOrCreate. With terminalPolicy: Retry, the resource checks again at nextCheckTime, and Terminal clears once LEDGER is gone. With the default, Hold, Terminal clears only when you edit the resource.

Declare a key-value bucket and an object store#

Apply a NatsKeyValue and a NatsObjectStore on the same connection. They take the same lifecycle policies as a stream.

01-natskeyvalue-objectstore.yaml yaml ·
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsKeyValue
metadata:
  name: sessions
  namespace: payments
  labels:
    traffic: requests
spec:
  connectionRef:
    name: shared-payments
  adoptionPolicy: AdoptOrCreate
  deletionPolicy: Retain
  name: sessions
  history: 5
  ttl: 24h
  maxValueSize: 64Ki
  maxBytes: 1Gi
  storage: File
  replicas: 3
---
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsObjectStore
metadata:
  name: receipts
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  name: receipts
  ttl: 2160h
  maxBytes: 50Gi
  storage: File
  replicas: 3
  compression: true
kubectl apply -f https://nats-operator.io/docs/stories/03-unmanaged/01-natskeyvalue-objectstore.yaml

NatsKeyValueSpec and NatsObjectStoreSpec in the API reference list their fields.

Declare consumers#

A consumer refers to its stream in one of two ways:

  • If the stream has no NatsStream, set stream to the name of the stream on the server, as ledger-audit does. The connection of the consumer must land in the account of the stream.
  • If the stream has a NatsStream, set streamRef to it, as payments-settlement does. The consumer then uses the connection of the stream, and the JetStream controller creates the consumer once the stream is Ready.
01-natsconsumer.yaml yaml ·
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsConsumer
metadata:
  name: ledger-audit
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  stream: LEDGER
  name: audit
  deliverPolicy: All
  ackPolicy: Explicit
---
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsConsumer
metadata:
  name: payments-settlement
  namespace: payments
spec:
  streamRef:
    name: payments
  adoptionPolicy: AdoptOrCreate
  name: settlement
  deliverPolicy: All
  ackPolicy: Explicit
  ackWait: 30s
  maxDeliver: 10
  filterSubjects: ["payments.settled.>"]
kubectl apply -f https://nats-operator.io/docs/stories/03-unmanaged/01-natsconsumer.yaml

Deleting a NatsConsumer deletes the consumer on the server unless the resource sets deletionPolicy: Retain. NatsConsumerSpec in the API reference lists every field.

Esc
↓ ↑ Navigate Enter Select Esc Close