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:
- Both NATS clusters in one supercluster. Build a supercluster across Kubernetes clusters joins
eastandwest. - A
NatsStreamfor the stream. If the stream has none, adopt it first: see Adopting streams.
Check where the stream is#
This guide starts from a NatsStream whose spec.placement.cluster is east.
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.yamlRead its status:
kubectl -n orders 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
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.
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.yamlnats-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 yamlWhile the move runs, the status in the output is similar to this:
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:
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.