Story 01 · Tutorial
A NATS cluster with JetStream
Contents
In this tutorial you deploy a three-server NATS cluster with JetStream on one Kubernetes cluster. You then restart its servers with more memory, create a stream and publish a message to it.
Before you begin#
You need:
- A Kubernetes cluster with the cluster controller and the JetStream controller installed. Install shows how.
- Nodes with 3 CPUs and 24Gi of memory that pods can still request. Each of the three servers requests 1 CPU, and 8Gi of memory by the end.
- A StorageClass named
standard. A kind cluster has one. - The
kubectltool, with its current context set to that Kubernetes cluster. - The NATS CLI.
Each manifest on this page is followed by the command that applies it. Following a story says more about the manifests and the status files.
Create the namespace#
Every object in this tutorial is in the namespace nats-system.
Create it:
kubectl create namespace nats-systemThe output is:
namespace/nats-system createdDeploy the NATS cluster#
Apply the NatsCluster named demo.
It asks for three servers, each with a 20Gi volume for JetStream.
apiVersion: cluster.nats-operator.io/v1beta1
kind: NatsCluster
metadata:
name: demo
namespace: nats-system
spec:
version: 2.15.0
replicas: 3
resources:
requests:
cpu: "1"
memory: 4Gi
limits:
memory: 4Gi
jetstream:
volumeClaimTemplate:
spec:
storageClassName: standard
resources:
requests:
storage: 20Gi
kubectl apply -f https://nats-operator.io/docs/stories/01-quickstart/01-natscluster.yamlThe output is:
natscluster.cluster.nats-operator.io/demo createdWait until the NATS cluster is ready:
kubectl -n nats-system wait --for=condition=Ready natscluster/demo --timeout=5mThe output is:
natscluster.cluster.nats-operator.io/demo condition metList the pods:
kubectl -n nats-system get podsThe output is similar to this:
NAME READY STATUS RESTARTS AGE
demo-0-0 2/2 Running 0 26s
demo-1-0 2/2 Running 0 26s
demo-2-0 2/2 Running 0 26sNotice the names.
The cluster controller creates one StatefulSet for each server, so the pod of the server demo-0 is demo-0-0.
If a pod stays Pending, the nodes do not have the CPU or the memory that the manifest requests.
Now look at what the NatsCluster reports:
kubectl -n nats-system get natscluster demo -o yamlThe status in the output is similar to this:
status:
observedGeneration: 1
version: 2.15.0
replicas: 3
readyReplicas: 3
conditions:
- type: Ready
status: "True"
reason: AllServersReady
- type: Settled
status: "True"
reason: AllGroupsCurrent
message: every Raft group has a leader and every member is current
- type: Progressing
status: "False"
reason: UpToDate
endpoints:
client: nats://demo.nats-system.svc:4222
monitor: http://demo-headless.nats-system.svc:8222
config:
revision: 3f9a1c
appliedBy: Restart
jetstream:
metaLeader: demo-1
limits:
maxMemoryStore: 3Gi
maxFileStore: 19Gi
servers:
- name: demo-0
version: 2.15.0
ready: true
configRevision: 3f9a1c
- name: demo-1
version: 2.15.0
ready: true
configRevision: 3f9a1c
- name: demo-2
version: 2.15.0
ready: true
configRevision: 3f9a1c
Notice that Settled is True.
Every Raft group has a leader, and every member of every group is current.
Notice endpoints.client as well.
It is the address that clients connect to, and you use it when you create the stream.
Raise the memory limit#
Apply the same NatsCluster with its memory request and limit raised from 4Gi to 8Gi.
apiVersion: cluster.nats-operator.io/v1beta1
kind: NatsCluster
metadata:
name: demo
namespace: nats-system
spec:
version: 2.15.0
replicas: 3
resources:
requests:
cpu: "1"
memory: 8Gi
limits:
memory: 8Gi
jetstream:
volumeClaimTemplate:
spec:
storageClassName: standard
resources:
requests:
storage: 20Gi
kubectl apply -f https://nats-operator.io/docs/stories/01-quickstart/02-natscluster-8gi.yamlThe output is:
natscluster.cluster.nats-operator.io/demo configuredA pod gets a new memory limit only when it restarts.
The cluster controller restarts one server at a time, and waits for Settled before it restarts the next.
Rollout in the design has the details.
Look at the NatsCluster again while the servers restart:
kubectl -n nats-system get natscluster demo -o yamlThe status in the output is similar to this:
status:
observedGeneration: 2
version: 2.15.0
replicas: 3
readyReplicas: 2
conditions:
- type: Ready
status: "True"
reason: QuorumAvailable
message: 2 of 3 servers ready
- type: Settled
status: "False"
reason: GroupsCatchingUp
message: 4 Raft groups have a member on demo-1 that is not current
- type: Progressing
status: "True"
reason: RollingRestart
message: restarting demo-1 (2 of 3); waiting for Settled
config:
revision: 8b27e0
appliedBy: Restart
restartReason: the StatefulSet spec is restart-only
rollout:
targetRevision: 8b27e0
updated: [demo-2]
current: demo-1
pending: [demo-0]
gate:
waitingFor: Settled
since: "2026-09-25T16:02:11Z"
jetstream:
metaLeader: demo-0
servers:
- name: demo-0
version: 2.15.0
ready: true
configRevision: 3f9a1c
- name: demo-1
version: 2.15.0
ready: false
configRevision: 8b27e0
- name: demo-2
version: 2.15.0
ready: true
configRevision: 8b27e0
Notice rollout.
It lists the servers that have restarted, the server that is restarting and the servers still to restart.
Yours differs with the moment you look.
Wait until the last server has restarted:
kubectl -n nats-system wait --for=condition=Progressing=false natscluster/demo --timeout=10mThe output is:
natscluster.cluster.nats-operator.io/demo condition metCheck the memory limit of a server:
kubectl -n nats-system get pod demo-0-0 -o jsonpath='{.spec.containers[0].resources.limits.memory}{"\n"}'The output is:
8GiCreate a stream#
The JetStream controller connects to a NATS cluster through a NatsConnection.
Apply one that has the client address from the status of the NatsCluster.
apiVersion: nats-operator.io/v1beta1
kind: NatsConnection
metadata:
name: demo
namespace: nats-system
spec:
servers: ["nats://demo.nats-system.svc:4222"]
kubectl apply -f https://nats-operator.io/docs/stories/01-quickstart/03-natsconnection.yamlThe output is:
natsconnection.nats-operator.io/demo createdApply the NatsStream.
It declares the stream ORDERS on the subjects orders.>, with three replicas.
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
name: orders
namespace: nats-system
spec:
connectionRef:
name: demo
adoptionPolicy: Never
deletionPolicy: Retain
terminalPolicy: Hold
name: ORDERS
subjects: ["orders.>"]
storage: File
replicas: 3
retention: Limits
maxAge: 72h
maxBytes: 5Gi
kubectl apply -f https://nats-operator.io/docs/stories/01-quickstart/03-natsstream.yamlThe output is:
natsstream.jetstream.nats-operator.io/orders createdThe manifest sets adoptionPolicy, deletionPolicy and terminalPolicy to their defaults.
NatsStreamSpec in the API reference lists the values of each.
Look at what the NatsStream reports:
kubectl -n nats-system get natsstream orders -o yamlThe status in the output is similar to this:
status:
observedGeneration: 1
conditions:
- type: Ready
status: "True"
reason: Synced
- type: Synced
status: "True"
reason: MatchesSpec
message: server config matches spec as of last check
lastTransitionTime: "2026-09-25T15:58:40Z"
lastSyncedTime: "2026-09-25T16:10:40Z"
ownership:
origin: Created
uid: 5b1e0c4a-2f7d-4c0e-9a51-0d6f3e2b7c19
server:
created: "2026-09-25T15:58:39Z"
leader: demo-2
replicas:
- name: demo-0
current: true
- name: demo-1
current: true
messages: 18204
bytes: 41Mi
Notice that Ready and Synced are True.
The stream exists on the servers and matches the manifest.
Your stream is empty, so server.bytes is 0 and server.messages is absent.
Publish a message#
Open a second terminal. In it, forward the client port of the NATS cluster to your machine, and leave the command running:
kubectl -n nats-system port-forward svc/demo 4222:4222The output is similar to this:
textForwarding from 127.0.0.1:4222 -> 4222In the first terminal, publish a message on a subject of the stream:
nats -s nats://localhost:4222 pub orders.created '{"id": 1}'The output is similar to this:
text11:54:45 Published 9 bytes to "orders.created"Read the state of the stream:
nats -s nats://localhost:4222 stream info ORDERSThe output ends with the state of the stream, similar to this:
textState: Host Version: 2.15.0 Required API Level: 0 hosted at level 5 Messages: 1 Bytes: 53 B First Sequence: 1 @ 2026-10-04 11:54:45 Last Sequence: 1 @ 2026-10-04 11:54:45 Active Consumers: 0 Number of Subjects: 1Notice
Messages: 1. The stream stored the message that you published.
You have built a three-server NATS cluster with JetStream, restarted it with more memory, and declared a stream on it as a Kubernetes resource.
Clean up#
Remove the stream from the servers. Deleting a
NatsStreamleaves its stream in place, and the cluster controller does not delete a NATS cluster that has a stream.nats -s nats://localhost:4222 stream rm ORDERS -fThe command prints nothing.
In the second terminal, press Ctrl+C to stop the port-forward.
Delete the three resources, and then the namespace:
kubectl -n nats-system delete natsstream orders kubectl -n nats-system delete natsconnection demo kubectl -n nats-system delete natscluster demo kubectl delete namespace nats-systemThe output is:
textnatsstream.jetstream.nats-operator.io "orders" deleted from nats-system namespace natsconnection.nats-operator.io "demo" deleted from nats-system namespace natscluster.cluster.nats-operator.io "demo" deleted from nats-system namespace namespace "nats-system" deletedDeleting the namespace also deletes the three volumes, which outlast the
NatsCluster.
To do the tutorial again, start from Create the namespace.
What’s next#
- This NATS cluster has no auth plane, so every client is in the global account. Put a NATS cluster under a NATS operator shows how, with accounts and users declared as resources.
- Stories lists the guides for the other tasks.
- The API reference has every field of
NatsCluster,NatsConnectionandNatsStream.