Connecting Wadm to NATS

info

These guides are for deploying wadm in production. For local development and testing, simply run wash up. For more information on wadm, see the wadm docs.

wadm uses NATS for communication with lattices in wasmCloud. For production deployments, wasmCloud supports decentralized JWT authentication for NATS.

Generating Credentials

To manage a lattice, wadm requires NATS credentials with access to the internal lattice subjects used by wasmCloud.

NATS architectures are varied, and there is no one-size-fits-all solution for how to configure NATS credentials for wadm, but this guide should be enough to get started.

The following tutorial creates an environment that is secure for wadm and its consumers using the NATS nsc CLI. The instructions create two users: one for wadm, and one for wadm consumers, such as wash.

Creating a Sample Account and Users

nsc add operator -n wadmdemo
nsc add account --name WADM
nsc add user --name wadmconsumer

Take note of where the user's credentials were created. They aren't part of the server configuration, so you'll need them later.

[ OK ] generated user creds file `~/.local/share/nats/nsc/keys/creds/wadmdemo/WADM/wadmapp.creds`

Continuing on:

nsc edit user --name wadmconsumer --allow-pub-response --allow-pub "wadm.api.>,wasmbus.ctl.>" 
nsc add user --name wadmapp

Again, keep track of where the credentials were created.

nsc edit user --name wadmapp --allow-pub-response --allow-sub "wadm.api.>" --allow-pub "wadm.>,wasmbus.ctl.>,$JS.>"
nsc generate config --mem-resolver --config-file ./server.conf

The generated file will look something like this:

// Operator "wadmdemo"
operator: eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5LW5rZXkifQ.eyJqdGkiOiI2QU9ESE9BRDdHTUU0NEE1NFZTSVJXTUlVVzdVWFNUQURVMlBaVVRVVlFERklSQlFKQ1FRIiwiaWF0IjoxNjg0NDEzNDk1LCJpc3MiOiJPQ1BFU1dCRVlWVjNDSkFFUEs2QjdUS0xJQ1hMUzZRTDQ0VTRaNzQ3NFlSVFdMSVFFWE41U0dXMiIsIm5hbWUiOiJ3YWRtZGVtbyIsInN1YiI6Ik9DUEVTV0JFWVZWM0NKQUVQSzZCN1RLTElDWExTNlFMNDRVNFo3NDc0WVJUV0xJUUVYTjVTR1cyIiwibmF0cyI6eyJ0eXBlIjoib3BlcmF0b3IiLCJ2ZXJzaW9uIjoyfX0.eXv6L4qNC6qqsAXrVmxHiRkVIShCpiRrboPcOgC9MUqCosgAN4ybxFKDprCSCx8Y0V17eRUurNndgM4unOEDDQ

resolver: MEMORY

resolver_preload: {
  // Account "WADM"
  ACQ7XAJEVR6L3MVSGFBD7E5OMQY5Z2V3P35YZD4D6Z535O5FE4AMTCYH: eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5LW5rZXkifQ.eyJqdGkiOiJLUTdDQk9MU1NESllDTlJLNUZFNjJOS0VDUTVaM0FTNENTTklJNkZZT1BCNDIzT0JRNFVRIiwiaWF0IjoxNjg0NDEzNjA4LCJpc3MiOiJPQ1BFU1dCRVlWVjNDSkFFUEs2QjdUS0xJQ1hMUzZRTDQ0VTRaNzQ3NFlSVFdMSVFFWE41U0dXMiIsIm5hbWUiOiJXQURNIiwic3ViIjoiQUNRN1hBSkVWUjZMM01WU0dGQkQ3RTVPTVFZNVoyVjNQMzVZWkQ0RDZaNTM1TzVGRTRBTVRDWUgiLCJuYXRzIjp7ImxpbWl0cyI6eyJzdWJzIjotMSwiZGF0YSI6LTEsInBheWxvYWQiOi0xLCJpbXBvcnRzIjotMSwiZXhwb3J0cyI6LTEsIndpbGRjYXJkcyI6dHJ1ZSwiY29ubiI6LTEsImxlYWYiOi0xfSwiZGVmYXVsdF9wZXJtaXNzaW9ucyI6eyJwdWIiOnt9LCJzdWIiOnt9fSwidHlwZSI6ImFjY291bnQiLCJ2ZXJzaW9uIjoyfX0.EwPe-PxWvkBwvKpx4ddhI4qLWU649l6HqUGqIFjK0w6NIoXVTzxq8TCAUPLnNQnU9ItXa50X_uxDkdCljAsgCQ

}

This configuration file can be provided to a server via nats-server -c server.conf. This will start NATS with the newly generated account and two users. The wadmconsumer user can be used by wash to consume the wadm API, and the wadmapp user will be used by wadm to connect to NATS.

If either of the users' permissions need to be updated, re-run nsc edit user .... to modify the credentials files. Note this does not require changing the server.conf file.

Note that this example uses an in-memory account resolver for simplicity. For most production deploys, using the NATS-based resolver is recommended.

note

The credentials generated above work for the multi-lattice management pattern. To restrict wadm to a single lattice, change the allow statements to use wasmbus.ctl.{lattice-id}.> instead of wasmbus.ctl.> and wadm.api.{lattice-id}.> instead of wadm.api.>. Please consult the NATS documentation for even more examples on how to restrict credentials

Authenticating to NATS

After generating credentials, wadm can be configured to use them in a few different ways:

• To connect to a non-local NATS server, set the -s/--nats-server option to the address of the NATS endpoint (e.g. nats.example.com:4222)
• To reference a credentials file, set the --nats-creds-file option to the path of the credentials file
• To pass the JWT and seed directly, set the --nats-jwt and --nats-seed options