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.

TLS Is Mandatory Where Secrets Travel

In PROD and LAB, a microservice that defines any secret config refuses to start over a plaintext connection, failing with refusing to start with secret configs over an insecure transport. Secret values travel from the configurator to each microservice over the bus, so a plaintext connection would put them on the wire in the clear.

The rule reaches further than an application’s own secrets: several shipped core microservices declare secrets of their own — metrics.core, bearertoken.core and foreman.core among them — so an application running any of them must connect over TLS even if it declares no secret configs itself. A short-circuit bundle, where there is no wire at all, satisfies the requirement without TLS.

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.