# Stories


The stories are the guides to the controllers, one task each, with the manifests that do it.
Each manifest uses the resource API, and the [API reference](https://nats-operator.io/docs/reference/api/index.md) lists every kind and field.

If you are new to the controllers, start with [the quickstart](https://nats-operator.io/docs/stories/01-quickstart/index.md), a tutorial that deploys a NATS cluster with JetStream and creates a stream on it.

The other stories are how-to guides:

- The auth plane: [put a NATS cluster under a NATS operator](https://nats-operator.io/docs/stories/02-auth-plane/index.md), [let a team declare its own users and streams](https://nats-operator.io/docs/stories/04-team-self-service/index.md), [share a stream and a service between accounts](https://nats-operator.io/docs/stories/05-account-wiring/index.md), and [adopt a NATS operator and accounts made with nsc](https://nats-operator.io/docs/stories/14-nsc-adoption/index.md).
- JetStream: [manage JetStream on a NATS cluster that you did not deploy](https://nats-operator.io/docs/stories/03-unmanaged/index.md), [balance JetStream leaders and copies](https://nats-operator.io/docs/stories/07-balancing/index.md), [move a stream to another NATS cluster](https://nats-operator.io/docs/stories/08-stream-transfer/index.md), and [retire a NATS cluster](https://nats-operator.io/docs/stories/11-evacuation/index.md).
- Several NATS clusters: [build a supercluster across Kubernetes clusters](https://nats-operator.io/docs/stories/06-supercluster/index.md), [deploy a production supercluster of three NATS clusters](https://nats-operator.io/docs/stories/09-acceptance/index.md), [join a NATS cluster to a hub as a leaf](https://nats-operator.io/docs/stories/10-leafnodes/index.md), and [add a NATS cluster to a supercluster that you did not deploy](https://nats-operator.io/docs/stories/13-join-supercluster/index.md).
- Metrics: [scrape the controllers' metrics over verified TLS](https://nats-operator.io/docs/stories/12-metrics/index.md).

## Following a story

1. Create the namespaces that the manifests use, `nats-system` and, in some stories, `orders`, `payments` or `monitoring`:

   ```sh
   for ns in nats-system orders payments monitoring; do kubectl create namespace "$ns"; done
   ```

   In a story that spans Kubernetes clusters, create them in each one.

1. Apply each manifest with the `kubectl` command that follows it on the page.
   In a story that spans Kubernetes clusters, the command sets the kubeconfig context of its Kubernetes cluster with `--context`.

1. Compare what `kubectl get -o yaml` shows with the status file on the page.
   A value that differs from one Kubernetes cluster to the next is an example.

## Running the stories

To run the stories end to end on kind clusters from a checkout of the repository, run `just e2e`.
[`hack/e2e`](https://github.com/mikluko/nats-operator/tree/main/hack/e2e) describes what the harness needs.


- [A NATS cluster with JetStream](https://nats-operator.io/docs/stories/01-quickstart/index.md)
- [Put a NATS cluster under a NATS operator](https://nats-operator.io/docs/stories/02-auth-plane/index.md)
- [Manage JetStream on a NATS cluster that you did not deploy](https://nats-operator.io/docs/stories/03-unmanaged/index.md)
- [Let a team declare its own users and streams](https://nats-operator.io/docs/stories/04-team-self-service/index.md)
- [Share a stream and a service between accounts](https://nats-operator.io/docs/stories/05-account-wiring/index.md)
- [Build a supercluster across Kubernetes clusters](https://nats-operator.io/docs/stories/06-supercluster/index.md)
- [Balance JetStream leaders and copies](https://nats-operator.io/docs/stories/07-balancing/index.md)
- [Move a stream to another NATS cluster](https://nats-operator.io/docs/stories/08-stream-transfer/index.md)
- [Deploy a production supercluster of three NATS clusters](https://nats-operator.io/docs/stories/09-acceptance/index.md)
- [Join a NATS cluster to a hub as a leaf](https://nats-operator.io/docs/stories/10-leafnodes/index.md)
- [Retire a NATS cluster](https://nats-operator.io/docs/stories/11-evacuation/index.md)
- [Scrape the controllers' metrics over verified TLS](https://nats-operator.io/docs/stories/12-metrics/index.md)
- [Add a NATS cluster to a supercluster that you did not deploy](https://nats-operator.io/docs/stories/13-join-supercluster/index.md)
- [Adopt a NATS operator and accounts made with nsc](https://nats-operator.io/docs/stories/14-nsc-adoption/index.md)
