Story 08 · JetStream

Move a stream to another NATS cluster

Contents

This guide shows you how to move a stream from one NATS cluster of a supercluster to another, together with its consumers. The manifests move the stream ORDERS from the NATS cluster east to the NATS cluster west.

To move every stream off a NATS cluster that you are retiring, see Retire a NATS cluster. An evacuation leaves a stream whose NatsStream sets placement.cluster where it is, so move such a stream with this guide.

Before you begin#

You need:

Check where the stream is#

This guide starts from a NatsStream whose spec.placement.cluster is east.

01-natsstream-before.yaml yaml ·
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: orders
  namespace: orders
spec:
  connectionRef:
    name: acme-orders
  name: ORDERS
  subjects: ["orders.>"]
  storage: File
  replicas: 3
  placement:
    cluster: east
kubectl apply -f https://nats-operator.io/docs/stories/08-stream-transfer/01-natsstream-before.yaml

Read its status:

kubectl -n orders get natsstream orders -o yaml

The status in the output is similar to this:

01-status-natsstream-in-east.yaml yaml ·
status:
  observedGeneration: 1
  conditions:
    - type: Ready
      status: "True"
      reason: Synced
    - type: Synced
      status: "True"
      reason: MatchesSpec
  server:
    leader: east-0

server.leader is a server of east.

Change the placement#

Set spec.placement.cluster to the name of the target NATS cluster, change nothing else, and apply the manifest.

02-natsstream-after.yaml yaml ·
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: orders
  namespace: orders
spec:
  connectionRef:
    name: acme-orders
  name: ORDERS
  subjects: ["orders.>"]
  storage: File
  replicas: 3
  placement:
    cluster: west
kubectl apply -f https://nats-operator.io/docs/stories/08-stream-transfer/02-natsstream-after.yaml

nats-server builds new replicas in west, copies the stream and its consumers to them, and then removes the replicas in east.

During the move, clients get what nats-server provides for a placement move. See Guarantees in the design.

Follow the move#

Read the status again:

kubectl -n orders get natsstream orders -o yaml

While the move runs, the status in the output is similar to this:

02-status-natsstream-transferring.yaml yaml ·
status:
  observedGeneration: 2
  conditions:
    - type: Ready
      status: "True"
      reason: Synced
    - type: Synced
      status: "False"
      reason: Moving
      message: moving to NATS cluster west; 2 of 3 new replicas current
  transfer:
    from: east
    to: west
    started: "2026-09-26T12:04:10Z"
    replicas:
      - name: west-0
        current: true
      - name: west-1
        current: true
      - name: west-2
        current: false
        lag: 18231
    consumers:
      moved: 1
      total: 2
  server:
    leader: east-1

Synced is False with the reason Moving. transfer.replicas has one entry for each new replica, and transfer.consumers counts the consumers that have moved. StreamTransfer in the API reference describes every field.

Confirm that the move is done#

The move is done when the replicas in east are gone. The status is then similar to this:

03-status-natsstream-in-west.yaml yaml ·
status:
  observedGeneration: 2
  conditions:
    - type: Ready
      status: "True"
      reason: Synced
    - type: Synced
      status: "True"
      reason: MatchesSpec
  server:
    leader: west-0

Synced is True, transfer is gone, and server.leader is a server of west.

Esc
↓ ↑ Navigate Enter Select Esc Close