# Bring your own NATS

Synadia Cloud supports an add-on to any plan that allows you to connect your own NATS system into Synadia Cloud. This provides a number of benefits including:

* One place to manage your remote NATS clusters
* View server stats, connections, message rates, and more
* Seamlessly manage accounts and users with a full audit log
* Manage JetStream assets and view stream data live
* Easily share streams and services across accounts

Go to the team `Settings > Billing` page to subscribe to the add-on.

## Specifics

* For each instance of the add-on, you can connect one NATS system
* Each system can have up to nine NATS servers (if you have more, contact us)
* There are no limits on the NATS system itself since you are running it!
* No NATS messaging/stream data is stored in Synadia Cloud
* Discounted annual billing is coming soon

## Getting started

A **System** is defined as one or more connected NATS servers that shares a system account. This could be a cluster, a supercluster, or (super)cluster with leafnodes that also share the system account.

Synadia Cloud BYON currently requires NATS servers to be configured with [decentralized authentication](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/jwt) (also referred to as operator mode). This auth model enables dynamic account and user creation and management, where-as other config-based auth models requires changing the configuration file of the server and reloading all servers to take effect.

There are two workflows for creating a system:

1. Setting up a new NATS cluster and copying the decentralized auth resolver configuration from the Cloud UI into the NATS server configuration file
2. Configuring an existing NATS system and importing the operator, account, and user seeds from `nsc`

## Setting up a new cluster

On the systems overview page, click `Add System > Create System` and fill out the form.

note

It is a best practice to configure an application connecting to NATS with multiple URLs, each to a different server. If one URL is specified and that server happens to be temporarily unavailable, the application will not be able to connect. By providing multiple URLs, the application can try each one until it successfully connects.

Once the form is filled out, click `Save` and you will be redirected to the `Settings > NATS Connection` page.

### Configure the NATS connection

Under the `Deploy NATS` section, choose the appropriate option for how the NATS cluster will be deployed. The steps provided show a basic way to run a single NATS server, however any method of deploying is supported. The main requirement is that the generated configuration is included in the NATS server configuration file.

Click `Continue`, then under `Connection Method`, choose `Connect using Synadia Private Link`. Follow the instructions shown in the UI after the NATS server/cluster is running (next section).

note

In the case that your NATS system is publicly addressable to the Internet, the second option is `Connect Directly to NATS`. This method supports various TLS options that can be configured, including mutual TLS.

### Start the NATS cluster

Depending the platform/deployment method of choice, start the NATS cluster, ensuring that the configuration file includes the decentralized auth resolver configuration copied above.

### Test the NATS connection

Back in the Synadia Cloud UI, click `Test Connection`. You should see a success message and click `Submit`. Finally, click on the `Overview` tab to see the cluster visualization.

## Importing an existing system

There are two ways to import an existing system:

1. Importing a system using the `synctl` CLI (recommended)
2. Importing a system through Synadia Cloud UI

Both methods requires access to the `nsc` store in order to inspect and import required keys and JWTs.

note

If there are multiple operators being managed by `nsc`, ensure the correct one is selected by running `nsc env -o <name>` before running any commands noted below.

### Generating signing keys

Synadia Cloud requires operator and system account *signing keys* in order to be imported. This is to ensure that the *root* key for the operator and system account can be reserved in the event that new signing keys need to be created.

If signing keys are *not* currently being used in the system, they can be generated using the `nsc` CLI.

```
# Generate an operator signing key.

nsc edit operator --sk generate



# Generate a system account signing key.

nsc edit account -n <sys-name> --sk generate
```

Note, once these are generated, the NATS server configuration file will need to be updated with the new JWTs (since signing keys are in the claims). The command `nsc generate config` provides a simple way to generate the desired resolver config. For example, the command to generate a *full* resolver:

```
nsc generate config --nats-resolver
```

Note, there are options for memory (`--mem-resolver`) and cache-only (`--nats-resolver-cache`) resolvers as well.

### Using the `synctl` CLI

To get started, [install and setup the `synctl` CLI](/platform/1.14/control-plane/cli/setup.md) on the machine where the `nsc` store is located.

The following command will start an import and will prompt you which operator you want to import (in case there are multiple).

```
synctl system import
```

Synadia Cloud will ignore the system if it has already been imported so it is safe to run this command multiple times.

You will be prompted to use the operator and system account signing keys. Choose `y` for both:

```
? Use Operator Signing Key? (y/N)

? Use SYS Account Signing Key? (y/N)
```

It is possible to import all accounts for a given operator as one command - use the `--all` flag:

```
synctl system import --all
```

You may also import all users using the `--users` flag:

```
synctl system import --all --users
```

To import specific accounts or users, use the `import-account` and `import-user` commands after the system has been imported.

Once the system has been imported, go to the Synadia Cloud UI and click on the home button (the Synadia icon) to see the list of systems.

### Using the Synadia Cloud UI

On the systems page, click `Add System > Import System`. For the `Operator JWT` field, this can be copied from the NATS server config or generated by the following `nsc` command:

```
nsc describe operator --raw
```

Similarily for the `System Account JWT`, this can be copied from the NATS server config or generated by the following `nsc` command:

```
nsc describe account -n <sys-name> --raw
```

For the `Operator Key` and `System Account Key` fields, the keys can be viewed by running the following command:

```
nsc list keys --account <sys-name> --show-seeds
```

This will output a table that looks something like this:

```
+-----------------------------------------------------------------------------------+

|                                    Seeds Keys                                     |

+--------+------------------------------------------------------------+-------------+

| Entity | Private Key                                                | Signing Key |

+--------+------------------------------------------------------------+-------------+

| local | SOAFF37NL6DJCGE54WDPBWTVKYFKF6NMWEO6DT3U6KY5YSVRCL7NKNSV3A |             |

| local | SOABODHWF4JFMVEXEAAEQ56UUASCD3WJ6DLRATXK4EKWQ33HYNDNEIGEKQ | *           |

|  SYS   | SAAARMKZCBXWIRNQHJPEI7H5J7ORGOWZUQKX7HXDEM7IOMT5PEDLJZZ3GE |             |

|  SYS   | SAABJ3MJEMAIHY5P5ZDU2UGTBUM4UFARROXHSVXIHTP6IFFFOJIHVFXERE | *           |

|   sys  | SUAF7SR6HYFJG7ZCCVWHUFQ3LOYOAS757FP3ZX32UIVNSHMFSLULRK2GWI |             |

+--------+------------------------------------------------------------+-------------+
```

The keys having the `*` are the signing keys. Copy the keys into the respective form fields in Synadia Cloud.

Once the form is filled out, click `Save` and you will be redirected to the `Settings > NATS Connection` page.

## Configuring NATS connection settings

Choose `Connect using Synadia Private Link`. Follow the instructions shown in the UI.

note

In the case that your NATS system is publicly addressable to the Internet, the second option is `Connect Directly to NATS`. This method supports various TLS options that can be configured, including mutual TLS.

Click `Test Connection`. You should see a success message and click `Submit`. Finally, click on the `Overview` tab to see the cluster visualization.

## FAQ

### Why is my system in a "provisioning" state?

If the system is in a `Provisioning` state, this means that Control Plane cannot connect to NATS for some reason. Refer to `Configuring NATS connection settings` above to troubleshoot the connection.

### What is the reason "test connection" fails?

There are a few reasons why this could be:

* The NATS server is not running or the URL is wrong which would result in a `i/o timeout` error
* The TLS settings are incorrect which would result in a `x509: certificate signed by unknown authority` or related error
* The imported JWTs or keys do not match the NATS server configuration which would result in a `authorization violation` error

### Can I run multiple Private Link agents for high availability?

Yes. Running multiple agents is supported and recommended for high availability. Note that even if the agent is down, the NATS system will continue to operate along with the client applications.
