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
paymentscan reach. The manifests use the client addresstls://nats.messaging.svc:4222. - In
payments, a Secretpayments-secretswith the creds of a user in the account that you manage, under the keynats.creds, and a Secretmessaging-nats-cawith the CA of the NATS cluster under the keyca.crt. Whoever runs the auth plane of that NATS cluster gives you the creds. - To follow every fork of this guide, the streams
PAYMENTSandLEDGERin 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.
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.yamlAdopt the streams#
Apply three NatsStreams.
Each one takes a different path with a stream that it did not create:
paymentssetsadoptionPolicy: Adopt. UseAdoptto 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 withAdoptedFalse, reasonNotFound, and does not create it.refundssetsadoptionPolicy: AdoptOrCreate. UseAdoptOrCreateto adopt the stream if it exists and create it if not. The JetStream controller applies the spec as written either way.ledgerleavesadoptionPolicyat its default,Never, and setsterminalPolicy: Retry.
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.yamlAdoptionPolicy 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 yamlThe JetStream controller has written the config of the stream into the spec. The output is similar to this:
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:
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 yamlLEDGER 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:
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.
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.yamlNatsKeyValueSpec 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, setstreamto the name of the stream on the server, asledger-auditdoes. The connection of the consumer must land in the account of the stream. - If the stream has a
NatsStream, setstreamRefto it, aspayments-settlementdoes. The consumer then uses the connection of the stream, and the JetStream controller creates the consumer once the stream isReady.
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.yamlDeleting a NatsConsumer deletes the consumer on the server unless the resource sets deletionPolicy: Retain.
NatsConsumerSpec in the API reference lists every field.