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 (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.

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).

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 syn-cp 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.

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 syn-cp CLI

To get started, install and setup the syn-cp CLI 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).

syn-cp 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:

syn-cp system import --all

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

syn-cp 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.

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.