# Manage JetStream on a NATS cluster that you did not deploy


This guide shows you how to declare streams, consumers, a key-value bucket and an object store as Kubernetes resources on a NATS cluster that the cluster controller did not deploy, and how to adopt streams that already exist without recreating them.
The manifests reach a NATS cluster in the namespace `messaging` and declare everything in the namespace `payments`.

## Before you begin

You need:

- A Kubernetes cluster with the JetStream controller installed.
  [Install](https://nats-operator.io/docs/install/index.md) shows how.
- The namespace `payments`.
- A NATS cluster with JetStream that pods in `payments` can reach.
  The manifests use the client address `tls://nats.messaging.svc:4222`.
- In `payments`, a Secret `payments-secrets` with the creds of a user in the account that you manage, under the key `nats.creds`, and a Secret `messaging-nats-ca` with the CA of the NATS cluster under the key `ca.crt`.
  Whoever runs the auth plane of that NATS cluster gives you the creds.
- To follow every fork of this guide, the streams `PAYMENTS` and `LEDGER` in that account, created by something other than the JetStream controller.

## Connect to the NATS cluster

Apply a `NatsConnection` with the address, the CA and the creds.
Every resource that uses it lands in the account that the creds sign in to.

`01-natsconnection.yaml`

```yaml
apiVersion: nats-operator.io/v1beta1
kind: NatsConnection
metadata:
  name: shared-payments
  namespace: payments
spec:
  servers: ["tls://nats.messaging.svc:4222"]
  tls:
    ca:
      secretKeyRef:
        name: messaging-nats-ca
  credentials:
    secretKeyRef:
      name: payments-secrets
      key: nats.creds
```

```sh
kubectl apply -f https://nats-operator.io/docs/stories/03-unmanaged/01-natsconnection.yaml
```


## Adopt the streams {#adopting-streams}

Apply three `NatsStream`s.
Each one takes a different path with a stream that it did not create:

- `payments` sets `adoptionPolicy: Adopt`.
  Use `Adopt` to adopt a stream that exists and keep its config: the spec needs only the fields that identify the stream.
  If the stream does not exist, the resource waits with `Adopted` False, reason `NotFound`, and does not create it.
- `refunds` sets `adoptionPolicy: AdoptOrCreate`.
  Use `AdoptOrCreate` to adopt the stream if it exists and create it if not.
  The JetStream controller applies the spec as written either way.
- `ledger` leaves `adoptionPolicy` at its default, `Never`, and sets `terminalPolicy: Retry`.

`01-natsstreams.yaml`

```yaml
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: payments
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  adoptionPolicy: Adopt
  name: PAYMENTS
---
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: refunds
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  adoptionPolicy: AdoptOrCreate
  name: REFUNDS
  subjects: ["refunds.>"]
  storage: File
  replicas: 3
  maxAge: 2160h
---
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: ledger
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  terminalPolicy: Retry
  name: LEDGER
  subjects: ["ledger.>"]
  replicas: 3
```

```sh
kubectl apply -f https://nats-operator.io/docs/stories/03-unmanaged/01-natsstreams.yaml
```


[AdoptionPolicy](https://nats-operator.io/docs/reference/api/index.md#AdoptionPolicy) and [TerminalPolicy](https://nats-operator.io/docs/reference/api/index.md#TerminalPolicy) in the API reference describe each value.
[Lifecycle policies](https://nats-operator.io/docs/design/v1/index.md#63-lifecycle-policies) in the design describes ownership.

### Check the adopted stream

Read `payments`:

```sh
kubectl -n payments get natsstream payments -o yaml
```

The JetStream controller has written the config of the stream into the spec.
The output is similar to this:

`01-live-natsstream-payments.yaml`

```yaml
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsStream
metadata:
  name: payments
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  adoptionPolicy: Adopt
  name: PAYMENTS
  subjects: ["payments.>"]
  storage: File
  replicas: 3
  retention: Limits
  maxAge: 168h0m0s
  maxBytes: "-1"
  discard: Old
```


The `status` in the output is similar to this:

`01-status-natsstream-payments.yaml`

```yaml
status:
  observedGeneration: 2
  conditions:
    - type: Ready
      status: "True"
      reason: Synced
    - type: Adopted
      status: "True"
      reason: FoundUnowned
      message: adopted existing stream PAYMENTS; spec written from the server
      lastTransitionTime: "2026-09-26T09:12:05Z"
    - type: Synced
      status: "True"
      reason: MatchesSpec
  lastSyncedTime: "2026-09-26T09:42:05Z"
  ownership:
    origin: Adopted
    uid: 0f7c1a92-8e44-4a0b-b3a5-6c2de0f19b77
  server:
    leader: nats-1
    messages: 3810442
    bytes: 2Gi
```


### Check the stream that was not adopted

Read `ledger`:

```sh
kubectl -n payments get natsstream ledger -o yaml
```

`LEDGER` exists and the JetStream controller does not own it, so the resource stops and the stream on the server stays as it is.
The `status` in the output is similar to this:

`01-status-natsstream-ledger.yaml`

```yaml
status:
  observedGeneration: 1
  conditions:
    - type: Ready
      status: "False"
      reason: Terminal
    - type: Terminal
      status: "True"
      reason: ExistsUnowned
      message: >-
        stream LEDGER exists and carries no ownership marker; set
        spec.adoptionPolicy to Adopt or AdoptOrCreate to take it over
      lastTransitionTime: "2026-09-26T09:12:06Z"
  nextCheckTime: "2026-09-26T09:22:06Z"
```


To take `LEDGER` over, set `adoptionPolicy` to `Adopt` or `AdoptOrCreate`.
With `terminalPolicy: Retry`, the resource checks again at `nextCheckTime`, and `Terminal` clears once `LEDGER` is gone.
With the default, `Hold`, `Terminal` clears only when you edit the resource.

## Declare a key-value bucket and an object store

Apply a `NatsKeyValue` and a `NatsObjectStore` on the same connection.
They take the same lifecycle policies as a stream.

`01-natskeyvalue-objectstore.yaml`

```yaml
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsKeyValue
metadata:
  name: sessions
  namespace: payments
  labels:
    traffic: requests
spec:
  connectionRef:
    name: shared-payments
  adoptionPolicy: AdoptOrCreate
  deletionPolicy: Retain
  name: sessions
  history: 5
  ttl: 24h
  maxValueSize: 64Ki
  maxBytes: 1Gi
  storage: File
  replicas: 3
---
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsObjectStore
metadata:
  name: receipts
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  name: receipts
  ttl: 2160h
  maxBytes: 50Gi
  storage: File
  replicas: 3
  compression: true
```

```sh
kubectl apply -f https://nats-operator.io/docs/stories/03-unmanaged/01-natskeyvalue-objectstore.yaml
```


[NatsKeyValueSpec](https://nats-operator.io/docs/reference/api/index.md#NatsKeyValueSpec) and [NatsObjectStoreSpec](https://nats-operator.io/docs/reference/api/index.md#NatsObjectStoreSpec) in the API reference list their fields.

## Declare consumers

A consumer refers to its stream in one of two ways:

- If the stream has no `NatsStream`, set `stream` to the name of the stream on the server, as `ledger-audit` does.
  The connection of the consumer must land in the account of the stream.
- If the stream has a `NatsStream`, set `streamRef` to it, as `payments-settlement` does.
  The consumer then uses the connection of the stream, and the JetStream controller creates the consumer once the stream is `Ready`.

`01-natsconsumer.yaml`

```yaml
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsConsumer
metadata:
  name: ledger-audit
  namespace: payments
spec:
  connectionRef:
    name: shared-payments
  stream: LEDGER
  name: audit
  deliverPolicy: All
  ackPolicy: Explicit
---
apiVersion: jetstream.nats-operator.io/v1beta1
kind: NatsConsumer
metadata:
  name: payments-settlement
  namespace: payments
spec:
  streamRef:
    name: payments
  adoptionPolicy: AdoptOrCreate
  name: settlement
  deliverPolicy: All
  ackPolicy: Explicit
  ackWait: 30s
  maxDeliver: 10
  filterSubjects: ["payments.settled.>"]
```

```sh
kubectl apply -f https://nats-operator.io/docs/stories/03-unmanaged/01-natsconsumer.yaml
```


Deleting a `NatsConsumer` deletes the consumer on the server unless the resource sets `deletionPolicy: Retain`.
[NatsConsumerSpec](https://nats-operator.io/docs/reference/api/index.md#NatsConsumerSpec) in the API reference lists every field.

