Adding a System

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.

Control Plane 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 in Control Plane:

Setting up a new NATS cluster and copying the decentralized auth resolver configuration from the Control Plane UI into the NATS server configuration file
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.

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 Directly to NATS.

In the unlikely scenario that Control Plane cannot access the NATS servers directly (not on the same network), Private Link can be used. See the Private Link documentation for more information.

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 Control Plane, if the NATS server connection requires TLS, fill out the relevant fields. and then 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:

Importing a system using the syn-cp CLI (recommended)
Importing a system through Control Plane UI

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

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

Control Plane 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

Control Plane 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 Control Plane UI and click on the home button (the Synadia icon) to see the list of systems.

Using the Control Plane 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 Control Plane.

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 Directly to NATS. If the NATS server connection requires TLS, fill out the relevant fields. and then click Test Connection. You should see a success message and click Submit.

In the unlikely scenario that Control Plane cannot access the NATS servers directly (not on the same network), Private Link can be used. See the Private Link documentation for more information.

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.