NATS can be used as the event bus for BindPlane OP 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.nats config 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 OP servers 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.

1eventBus:
2  type: nats
3  nats:
4    # NATS client connects to the NATS server on the same
5    # node. The client will publish and consume events
6    # from the subject "bindplane-event-bus.
7    client:
8      endpoint: nats://localhost:4222
9      subject: bindplane-event-bus
10
11    # NATS server accepts client connections on localhost
12    # and cluster connections on all interfaces.
13    server:
14      enable: true
15      client:
16        host: localhost
17        port: 4222
18      http:
19        host: localhost
20        port: 8222
21      cluster:
22        name: bindplane
23        host: '0.0.0.0'
24        port: 6222
25        routes:
26          - 'nats://bindplane-0.corp.net:6222'
27          - 'nats://bindplane-0.corp.net:6222'
28          - 'nats://bindplane-0.corp.net:6222'

Configuration Parameters

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

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

1eventBus:
2  type: local
3  nats:
4    server:
5      client:
6        host: localhost
7        port: 4222
8      http:
9        host: localhost
10        port: 8222
11      cluster:
12        name: bindplane
13        host: localhost
14        port: 6222
15    client:
16      endpoint: nats://localhost:4222
17      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 OP 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 to 0.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.port option 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.

1nats:
2  server:
3    enable: true
4    cluster:
5      host: '0.0.0.0'
6      routes:
7        - 'nats://bindplane-0.corp.net:6222'
8        - 'nats://bindplane-1.corp.net:6222'
9        - '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.

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

1eventBus:
2  type: nats
3  nats:
4    enableTLS: true
5    tls:
6      tlsCert: /etc/bindplane/nats.crt
7      tlsKey: /etc/bindplane/nats.key
8      tlsCa:
9        - /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:

1step certificate create \
2  ca.corp.net \
3    ca.crt ca.key \
4    --profile root-ca \
5    --no-password \
6    --insecure \
7    --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.

1step certificate create \
2    nats \
3    --san "bindplane-0.corp.net" \
4    --san "bindplane-1.corp.net" \
5    --san "bindplane-2.corp.net" \
6    --san localhost \
7    nats.crt nats.key \
8    --profile leaf \
9    --not-after 2160h \
10    --no-password \
11    --insecure \
12    --ca ca.crt \
13    --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.

1sudo chown bindplane:bindplane \
2  /etc/bindplane/ca.crt \
3  /etc/bindplane/nats.crt \
4  /etc/bindplane/nats.key
5
6sudo chmod 0400 bindplane:bindplane \
7  /etc/bindplane/ca.crt \
8  /etc/bindplane/nats.crt \
9  /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

1eventBus:
2  type: nats
3  nats:
4    enableTLS: true
5    tls:
6      tlsCert: /etc/bindplane/nats.crt
7      tlsKey: /etc/bindplane/nats.key
8      tlsCa:
9        - /etc/bindplane/ca.crt