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 kubectl tool, 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-system

The output is:

text
namespace/nats-system created

Deploy the NATS cluster#

Apply the NatsCluster named demo. It asks for three servers, each with a 20Gi volume for JetStream.

01-natscluster.yaml yaml ·
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.yaml

The output is:

text
natscluster.cluster.nats-operator.io/demo created

Wait until the NATS cluster is ready:

kubectl -n nats-system wait --for=condition=Ready natscluster/demo --timeout=5m

The output is:

text
natscluster.cluster.nats-operator.io/demo condition met

List the pods:

kubectl -n nats-system get pods

The output is similar to this:

text
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          26s

Notice 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 yaml

The status in the output is similar to this:

01-status-natscluster-at-rest.yaml yaml ·
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.

02-natscluster-8gi.yaml yaml ·
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.yaml

The output is:

text
natscluster.cluster.nats-operator.io/demo configured

A 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 yaml

The status in the output is similar to this:

02-status-natscluster-mid-rollout.yaml yaml ·
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=10m

The output is:

text
natscluster.cluster.nats-operator.io/demo condition met

Check 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:

text
8Gi

Create 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.

03-natsconnection.yaml yaml ·
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.yaml

The output is:

text
natsconnection.nats-operator.io/demo created

Apply the NatsStream. It declares the stream ORDERS on the subjects orders.>, with three replicas.

03-natsstream.yaml yaml ·
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.yaml

The output is:

text
natsstream.jetstream.nats-operator.io/orders created

The 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 yaml

The status in the output is similar to this:

03-status-natsstream.yaml yaml ·
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#

  1. 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:4222

    The output is similar to this:

    text
    Forwarding from 127.0.0.1:4222 -> 4222
  2. In 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:

    text
    11:54:45 Published 9 bytes to "orders.created"
  3. Read the state of the stream:

    nats -s nats://localhost:4222 stream info ORDERS

    The output ends with the state of the stream, similar to this:

    text
    State:
    
                          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: 1

    Notice 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#

  1. Remove the stream from the servers. Deleting a NatsStream leaves 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 -f

    The command prints nothing.

  2. In the second terminal, press Ctrl+C to stop the port-forward.

  3. 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-system

    The output is:

    text
    natsstream.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" deleted

    Deleting 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, NatsConnection and NatsStream.
Esc
↓ ↑ Navigate Enter Select Esc Close