NATS Connection Settings

NATS is the messaging substrate beneath every microservice on the bus, carrying not only direct service-to-service traffic but also the dispatches that drive workflow tasks. Every microservice connects to NATS at startup; without a connection it can neither send nor receive messages.

Server URL

By default each connector tries nats://127.0.0.1:4222. Override with the MICROBUS_NATS environment variable, e.g. nats://nats.internal:4222 for a shared cluster.

Authentication

Microbus’s recommended production auth model for NATS is operator-mode with a per-microservice signed user JWT. Each microservice in a bundled executable holds its own <hostname>_nats.creds file, opens its own NATS connection, and presents its own narrow JWT to the broker. The broker pins each connected microservice to publish only under its own source segment, which is what makes interservice ACL work end-to-end.

The connector resolves four optional auth artifacts at startup. For each, the per-service form {hostname}_<artifact> in CWD wins, with the bare form as the shared-default fallback:

If neither form is present for an artifact, the connector connects without it. With no creds and no certs at all, the connector connects unauthenticated. That is fine for local development against a permissive NATS server, but the wrong shape for production.

TLS

A cert.pem + key.pem pair (or per-service equivalents) configures a TLS client certificate. A ca.pem (or {hostname}_ca.pem) is loaded as a root CA for verifying the NATS server’s certificate.

Local Development

For development against a local unauthenticated NATS server (nats-server with default config), no credentials files are needed. Just point MICROBUS_NATS at the server (or rely on the 127.0.0.1:4222 default) and the connector connects in the clear.

Generating Creds

Per-microservice .creds files are produced by gencreds, one step in the deploy pipeline detailed in Operational Security. The tool scans the bundle’s source code for the call patterns each microservice uses, derives the NATS subject ACL each microservice needs, and signs one user JWT per microservice against an operator-managed account NKey.

Connection Pooling

The transport package pools connections by credential hash. Two microservices in the same process whose .creds resolve to byte-identical content share one underlying NATS connection. Two microservices with distinct per-service .creds get their own connections, which is what gives each microservice broker-pinned per-service identity.

Deprecated Env-Var Auth

Earlier versions of Microbus exposed NATS auth via environment variables (MICROBUS_NATS_USER, MICROBUS_NATS_PASSWORD, MICROBUS_NATS_TOKEN, MICROBUS_NATS_USER_JWT, MICROBUS_NATS_NKEY_SEED). These remain functional for backward compatibility but are removed from documentation: env vars are process-scoped, not service-scoped, so they can’t carry per-service identity. New deployments should use per-service <hostname>_nats.creds files (operator-mode) or the shared-default nats.creds (single user across the bundle).