Skip to main content

Change the config

This guide applies a new config file to a fleet of gateways, one gateway at a time. Clients move to the other gateways and keep their sessions.

The gateway reads its config once, when it starts. A change takes effect only when the gateway restarts. SIGHUP does not reload the config. The gateway logs config not reloaded and continues with its old config.

Before you start, you need:

  • Two or more gateways that share a sessions bucket. See Deploy for high availability.
  • The new config file.
  • The nats CLI, with a user in each account that the gateways serve.

1. Check the new file​

Run check with the new file:

mq-gateway check --config gateway.new.yaml

check reads nats.url from the file only. It ignores --nats.url and MQGW_ variables. It cannot check a file with nats.embed: true.

Fix every failure before you continue. An account that fails its check at start serves no clients until the next restart.

2. Add new streams, buckets and permissions​

Do this step only if the new file adds a binding or a bucket.

  1. Generate the resources and the permissions from the new file:

    mq-gateway generate --config gateway.new.yaml --format nats-cli > provision.sh
    mq-gateway generate --config gateway.new.yaml --format nats-server > permissions.conf

  2. Create the new streams and buckets. See Provision the streams and buckets.

  3. Copy the topics that you narrowed into the new permissions.conf. See Configure listeners and auth.

  4. Reload the NATS servers.

  5. Run check again.

3. Restart the gateways one at a time​

Put the new file in place on each host. Then do these steps for each gateway:

  1. Start lame duck mode with a signal, or with an admin request from the gateway's own account:

    mq-gateway signal ldm --pid <pid>
    nats req '$MQGW.admin.gw-1.ldm' ''

  2. Wait for the gateway to exit with status 0.

  3. Start the gateway with the new file and the same --id.

  4. Wait until /readyz returns 200.

  5. Check that the gateway serves every account. Do these checks:

    • /healthz lists no account under errors.

    • In each account, the reply to ping includes the gateway id:

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

  6. Go to the next gateway.

In lame duck mode, the gateway closes its listeners immediately. After ldm.grace-period (default 10s), it closes its client connections a few at a time over ldm.duration (default 2m). Each client reconnects to another gateway and resumes its session. An MQTT 5 client gets the reason "Server shutting down".

/readyz returns 200 even when an account failed its start-up check. Use /healthz or ping to find such an account.

While the restart runs​

Gateways with the old file and gateways with the new file serve at the same time. A client gets the behavior of the gateway it connects to.

  • Accounts: only gateways with the new file serve an added account. Only gateways with the old file serve a removed account.
  • Bindings: if only one file binds a topic, the other gateways refuse a QoS 1 publish to it. Add a stream before the restart. Remove one after it.
  • Sessions bucket: gateways on different buckets do not share sessions. If you rename the bucket, clients lose their persistent sessions.
  • --id: keep each gateway id different from all others.

A gateway that runs alone has no other gateway to take its clients. Lame duck mode still closes the clients gradually, and they reconnect after the restart.

Changes that need no restart​

The gateway follows these changes in NATS while it runs:

ChangeWhat the gateway does
A user's permissionsNATS applies them to the next action of the client. An existing QoS 1 subscription keeps its consumer. To stop it immediately, revoke the credential
A revoked credentialThe gateway disconnects the client. An MQTT 5 client gets "Not authorized"
A user moved to another accountClients of a fixed listener move at once. Kick a passthrough client to move it now. See Operate a fleet
A rotated creds file, or TLS client certificate, key or CA fileThe gateway reads the file again at its next NATS reconnect. This applies to gateway users and fixed listeners
A NATS server restartNATS connections move to the other servers

Check it works​

After the last gateway restarts:

  • mq-gateway check --config gateway.new.yaml exits 0.
  • ping in each account gets one reply from each gateway.
  • If you added a binding, a client subscribes at QoS 1 to one of its topics and gets QoS 1.