NATS as Event Bus

How to setup Bindplane to use NATS as its event bus

IMPORTANT

🚧 This feature is only available in Bindplane Enterprise. Learn more here.

NATS can be used as the event bus for Bindplane Enterprise and is a good option for distributed on-prem deployments. NATS is embedded into Bindplane and does not require external infrastructure.

Configuration

In order to use NATS as the event bus the eventBus.type field must be set to nats and the eventBus.natsconfig must be filled out. On Linux, the path to the configuration file is /etc/bindplane/config.yaml.

Here is an example configuration snippet using NATS as the event bus. In this example, there are three Bindplane severs named bindplane-0, bindplane-1, and bindplane-2. Each Bindplane server is operating the NATS client and server. Each NATS client will connect to its local server over localhost. Each NATS server will connect to other servers using their hostname and port.

eventBus:
  type: nats
  nats:
    # NATS client connects to the NATS server on the same
    # node. The client will publish and consume events
    # from the subject "bindplane-event-bus.
    client:
      endpoint: nats://localhost:4222
      subject: bindplane-event-bus

    # NATS server accepts client connections on localhost
    # and cluster connections on all interfaces.
    server:
      enable: true
      client:
        host: localhost
        port: 4222
      http:
        host: localhost
        port: 8222
      cluster:
        name: bindplane
        host: '0.0.0.0'
        port: 6222
        routes:
          - 'nats://bindplane-0.corp.net:6222'
          - 'nats://bindplane-1.corp.net:6222'
          - 'nats://bindplane-2.corp.net:6222'

Configuration Parameters

NATS Event Bus can be configured with the following configuration options, flags, and environment variables.

Option	Flag	Environment Variable
eventBus.nats.client.name	--nats-client-name	BINDPLANE_NATS_CLIENT_NAME
eventBus.nats.client.endpoint	--nats-client-endpoint	BINDPLANE_NATS_CLIENT_ENDPOINT
eventBus.nats.client.subject	--nats-client-subject	BINDPLANE_NATS_CLIENT_SUBJECT
eventBus.nats.server.enable	--nats-server-enable	BINDPLANE_NATS_SERVER_ENABLE
eventBus.nats.server.name	--nats-server-name	BINDPLANE_NATS_SERVER_NAME
eventBus.nats.server.client.host	--nats-server-client-host	BINDPLANE_NATS_SERVER_CLIENT_HOST
eventBus.nats.server.client.port	--nats-server-client-port	BINDPLANE_NATS_SERVER_CLIENT_PORT
eventBus.nats.server.http.host	--nats-server-http-host	BINDPLANE_NATS_SERVER_HTTP_HOST
eventBus.nats.server.http.port	--nats-server-http-port	BINDPLANE_NATS_SERVER_HTTP_PORT
eventBus.nats.server.cluster.name	--nats-server-cluster-name	BINDPLANE_NATS_SERVER_CLUSTER_NAME
eventBus.nats.server.cluster.host	--nats-server-cluster-host	BINDPLANE_NATS_SERVER_CLUSTER_HOST
eventBus.nats.server.cluster.port	--nats-server-cluster-port	BINDPLANE_NATS_SERVER_CLUSTER_PORT
eventBus.nats.server.cluster.advertise	--nats-server-cluster-advertise	BINDPLANE_NATS_SERVER_CLUSTER_ADVERTISE
eventBus.nats.server.cluster.routes	--nats-server-cluster-routes	BINDPLANE_NATS_SERVER_CLUSTER_ROUTES
eventBus.nats.tls.enableTLS	--nats-enable-tls	BINDPLANE_NATS_ENABLE_TLS
eventBus.nats.tls.tlsCert	--nats-tls-cert	BINDPLANE_NATS_TLS_CERT
eventBus.nats.tls.tlsKey	--nats-tls-key	BINDPLANE_NATS_TLS_KEY
eventBus.nats.tls.tlsCA	--nats-tls-ca	BINDPLANE_NATS_TLS_CA
eventBus.nats.tls.tlsSkipVerify	--nats-tls-skip-verify	BINDPLANE_NATS_TLS_SKIP_VERIFY

Default installations of Bindplane will include the following configuration. Notice that the event bus type is local, NATS is disabled by default.

eventBus:
  type: local
  nats:
    server:
      client:
        host: localhost
        port: 4222
      http:
        host: localhost
        port: 8222
      cluster:
        name: bindplane
        host: localhost
        port: 6222
    client:
      endpoint: nats://localhost:4222
      subject: bindplane-event-bus

Client Name

The NATS client name can be set with eventBus.nats.client.name. It is required that clients have unique names. It is safe for this value to match NATS server's name when Bindplane is operating the NATS client and server.

Default value: System's hostname.

Client Endpoint

The endpoint used by the client to connect to a NATS server can be set with eventBus.nats.client.endpoint. The endpoint should be a URI containing the nats scheme as well as the hostname and port of the NATS server. Generally, localhost is used to target the server operating on the same node.

Default value: nats://localhost:4222.

Client Subject

The eventBus.nats.client.subject option configures the NATS subject used to publish and consume events from the event bus. All clients should have the same subject.

Default value: bindplane-event-bus.

Server Enable

The eventBus.nats.server.enable option enables the embedded NATS server. For small Bindplane deployments (3 to 5 nodes), it is recommended to operate NATS client and server on all Bindplane nodes. For large deployments (> 5), it is recommended to enable NATS server on three nodes.

Default value: false.

Server Name

The NATS server name can be set with eventBus.nats.server.name. It is required that servers have unique names. It is safe for this value to match the NATS client's name when Bindplane is operating the NATS client and server.

Default value: System's hostname.

Server Client Host

The eventBus.nats.server.client.host option is used to configure the network interface used by the NATS server to receive incoming connections from clients. This can be localhost if the server is only receiving connections from the local NATS client, in situations where Bindplane is operating the client and server.

Default value: localhost.

Server Client Port

The eventBus.nats.server.client.port option is used to configure the TCP port used by the NATS server to receive incoming connections from clients.

Default value: 4222

Server HTTP Host

The eventBus.nats.server.http.host option is used to configure the network interface used to expose the NATS server Monitoring API. You can find documentation for the API here. This should be set to localhost, with any monitoring tools running on the server system.

Default value: localhost.

Server HTTP Port

The eventBus.nats.server.http.port option is used to configure the TCP port used by the NATS server to expose the Monitoring API.

Default value: 8222.

Server Cluster Name

The eventBus.nats.server.cluster.name option sets the name of the NATS cluster. All nodes within the NATS cluster should have the same cluster name.

Default value: bindplane.

Server Cluster Host

The eventBus.nats.server.cluster.host option is used to configure the network interface used to expose the NATS server's cluster interface. When operating more than one NATS server, it should be set to0.0.0.0 or a specific IP address that is reachable by all other NATS servers.

Default value: localhost.

Server Cluster Port

The eventBus.nats.server.cluster.portoption is used to configure the TCP port used by the NATS server's cluster interface.

Default value: 6222.

Server Cluster Advertise

The eventBus.nats.server.cluster.advertise option can be used to advertise the endpoint other servers in the cluster should use to reach the NATS server. This option should be considered advanced and is generally not required. The configured value should be of the form host:port, it should not contain a URI scheme.

Default value: Unset.

Server Cluster Routes

The eventBus.nats.server.cluster.routes option is used to define a list of servers that the NATS server should connect to. This list can contain the local server.

In this example, there are three Bindplane servers. All three servers will make connections to each endpoint in the list of routes. The servers will detect if they are connected to themselves, and automatically remove the route as it is unnecessary.

nats:
  server:
    enable: true
    cluster:
      host: '0.0.0.0'
      routes:
        - 'nats://bindplane-0.corp.net:6222'
        - 'nats://bindplane-1.corp.net:6222'
        - 'nats://bindplane-2.corp.net:6222'

Default value: Unset.

Authentication

Authentication is supported by configuring TLS. The NATS event bus uses mutual TLS to authenticate the client and server.

TLS Configuration

The following options can be set under eventBus.nats.tls. When TLS is enabled, NATS will use mutual TLS to authenticate the NATS clients and servers. A certificate authority file is required to enforce the use of mutual TLS.

Option	Description	Default
enableTLS	Enable or disable TLS	false
tlsCert	File path to TLS x509 PEM encoded certificate	required
tlsKey	File path to TLS x509 PEM encoded private key	required
tlsCA	File path(s) to TLS x509 PEM encoded certificate authority	required
tlsSkipVerify	Enable or disable strict hostname verification	false

The following example enables TLS by setting enableTLS, tlsCert, tlsKey, and tlsCa.

eventBus:
  type: nats
  nats:
    enableTLS: true
    tls:
      tlsCert: /etc/bindplane/nats.crt
      tlsKey: /etc/bindplane/nats.key
      tlsCa:
        - /etc/bindplane/ca.crt

Generating Certificates

You can use Step CLI, OpenSSL, or other tools to generate certificates. Certificates do not need to be publicly signed.

The following examples will use step to generate a certificate authority and a signed certificate suitable for use with NATS.

Create the certificate authority:

step certificate create \
  ca.corp.net \
    ca.crt ca.key \
    --profile root-ca \
    --no-password \
    --insecure \
    --not-after=43800h

Modify the san flag values to the hostnames of your Bindplane servers. If you have more than three servers, add additional san flags. You can also issue unique certificates for each server.

step certificate create \
    nats \
    --san "bindplane-0.corp.net" \
    --san "bindplane-1.corp.net" \
    --san "bindplane-2.corp.net" \
    --san localhost \
    nats.crt nats.key \
    --profile leaf \
    --not-after 2160h \
    --no-password \
    --insecure \
    --ca ca.crt \
    --ca-key ca.key

Copy ca.crt, nats.crt, nats.key to /etc/bindplane on all of your servers. After copying them, set the filesystem permissions.

sudo chown bindplane:bindplane \
  /etc/bindplane/ca.crt \
  /etc/bindplane/nats.crt \
  /etc/bindplane/nats.key

sudo chmod 0400 bindplane:bindplane \
  /etc/bindplane/ca.crt \
  /etc/bindplane/nats.crt \
  /etc/bindplane/nats.key

Update your NATS configuration section to include the TLS options.

• eventBus.nats.enableTLS

• eventBus.nats.tls.tlsCert

• eventBus.nats.tls.tlsKey

• eventBus.nats.tls.tlsCa

eventBus:
  type: nats
  nats:
    enableTLS: true
    tls:
      tlsCert: /etc/bindplane/nats.crt
      tlsKey: /etc/bindplane/nats.key
      tlsCa:
        - /etc/bindplane/ca.crt