# Move a stream to another NATS cluster


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](https://nats-operator.io/docs/stories/11-evacuation/index.md).
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](https://nats-operator.io/docs/stories/06-supercluster/index.md) joins `east` and `west`.
- A `NatsStream` for the stream. If the stream has none, adopt it first: see [Adopting streams](https://nats-operator.io/docs/stories/03-unmanaged/index.md#adopting-streams).

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

```sh
kubectl apply -f https://nats-operator.io/docs/stories/08-stream-transfer/01-natsstream-before.yaml
```


Read its status:

```sh
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
```

```sh
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](https://nats-operator.io/docs/design/v1/index.md#8-guarantees) in the design.

## Follow the move

Read the status again:

```sh
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](https://nats-operator.io/docs/reference/api/index.md#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`.

