Skip to main content
Version: 0.3

Set up the admin account

This guide gives the gateways an admin account, where an operator lists and kicks clients, rebalances NATS connections and starts lame duck mode. The gateway serves these admin requests in the admin account alone, for every account it serves. Clients in the other accounts cannot reach them.

The admin account is optional. Without it, the gateways serve clients as usual, and lame duck mode still starts with SIGUSR2.

Before you start, you need:

  • Gateways and a config file, with mqtt or amqp set.
  • A nats-server.conf that you can edit and reload, or nsc in operator mode.
  • The nats CLI.

1. Generate the permissions​

mq-gateway generate --config gateway.yaml --format nats-server > permissions.conf

The end of permissions.conf holds two variables, commented out:

  • $admin_gateway_permissions: the gateway's user in the admin account.
  • $operator_permissions: a user that sends the admin requests.

Remove the # in front of both variables. Leave the other comments.

2. Add the admin account​

Add an account that no client is in. The gateway refuses to start when its admin user is in an account that it serves clients in.

include "permissions.conf"
accounts {
  PLANT_A: { jetstream: enabled, users: [ ... ] }
  ADMIN: { users: [
    { user: gateway-admin, password: "...", permissions: $admin_gateway_permissions }
    { user: operator, password: "...", permissions: $operator_permissions }
  ] }
}

Reload the server:

nats-server --signal reload

In operator mode, add the account and its two users with nsc. Give them the subjects of each variable. Push the account JWT to the resolver.

3. Give the gateways the admin credential​

Add the credential under nats.admin. It takes the same keys as nats, and the gateway reaches it at nats.url:

nats:
  url: nats://nats-1:4222,nats://nats-2:4222
  creds: /etc/mqg/gateway.creds
  admin:
    creds: /etc/mqg/gateway-admin.creds

Give each gateway its own id. Then restart the gateways one at a time, as in Change the config.

Check it works​

  1. Look for the admin control enabled line in each gateway's log. It names the gateway id and the admin account.

  2. As the operator user, send info to every gateway:

    nats req '$MQG.admin.ping.info' '' --replies 0 --timeout 1s

    Each gateway replies with its id and its clients in each account.

  3. As a client user, send the same request. It gets no responders.

If a gateway does not serve the admin requests, it logs why and keeps serving clients. /healthz names the admin account and the reason.

Things to know​

  • One admin user for the fleet. Every gateway can use the same admin credential. Each gateway subscribes to its own server subjects, and all of them to the ping and account subjects.
  • The admin account is powerful. Its operator users can kick any client and stop any gateway. Give them to operators only.
  • Liveness stays in the client accounts. Gateways that share a sessions bucket check each other in that bucket's account. A lost admin connection does not end any session.