Nats

Abstract

The nats service is the event broker of the system. It distributes events among all other services and enables other services to communicate asynchronous.

Services can Publish events to the nats service and nats will store these events on disk and distribute these events to other services eventually. Services can Consume events from the nats service by registering to a ConsumerGroup. Each ConsumerGroup is guaranteed to get each event exactly once. In most cases, each service will register its own ConsumerGroup. When there are multiple instances of a service, those instances will usually use that ConsumerGroup as common resource.

Underlying Technology
Default Registry
Persistance
TLS Encryption
Example Yaml Config

Underlying Technology

As the service name suggests, this service is based on NATS specifically on NATS Jetstream to enable persistence.

Default Registry

By default, nats-js-kv is configured as embedded default registry via the MICRO_REGISTRY environment variable. If you do not want using the build-in nats registry, set MICRO_REGISTRY_ADDRESS to the address of the nats-js cluster, which is the same value as OCIS_EVENTS_ENDPOINT. Optionally use MICRO_REGISTRY_AUTH_USERNAME and MICRO_REGISTRY_AUTH_PASSWORD to authenticate with the external nats cluster.

Persistance

To be able to deliver events even after a system or service restart, nats will store events in a folder on the local filesystem. This folder can be specified by setting the NATS_NATS_STORE_DIR enviroment variable. If not set, the service will fall back to $OCIS_BASE_DATA_PATH/nats.

TLS Encryption

Connections to the nats service (Publisher/Consumer see above) can be TLS encrypted by setting the corresponding env vars NATS_TLS_CERT, NATS_TLS_KEY to the cert and key files and ENABLE_TLS to true. Checking the certificate of incoming request can be disabled with the NATS_EVENTS_ENABLE_TLS environment variable.

Certificate files can also be set via global variables starting with OCIS_, for details see the environment variable list.

Note that using TLS is highly recommended for productive environments, especially when using container orchestration with Kubernetes.

Example Yaml Config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# Autogenerated
# Filename: nats-config-example.yaml

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9234
  token: ""
  pprof: false
  zpages: false
nats:
  host: 127.0.0.1
  port: 9233
  clusterid: ocis-cluster
  store_dir: /var/lib/ocis/nats
  tls_cert: /var/lib/ocis/nats/tls.crt
  tls_key: /var/lib/ocis/nats/tls.key
  tls_skip_verify_client_cert: false
  enable_tls: false

Environment Variables

Name	Type	Default Value	Description
OCIS_TRACING_ENABLED NATS_TRACING_ENABLED	bool	false	Activates tracing.
OCIS_TRACING_TYPE NATS_TRACING_TYPE	string		The type of tracing. Defaults to ‘’, which is the same as ‘jaeger’. Allowed tracing types are ‘jaeger’ and ’’ as of now.
OCIS_TRACING_ENDPOINT NATS_TRACING_ENDPOINT	string		The endpoint of the tracing agent.
OCIS_TRACING_COLLECTOR NATS_TRACING_COLLECTOR	string		The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset.
OCIS_LOG_LEVEL NATS_LOG_LEVEL	string		The log level. Valid values are: ‘panic’, ‘fatal’, ’error’, ‘warn’, ‘info’, ‘debug’, ’trace’.
OCIS_LOG_PRETTY NATS_LOG_PRETTY	bool	false	Activates pretty log output.
OCIS_LOG_COLOR NATS_LOG_COLOR	bool	false	Activates colorized log output.
OCIS_LOG_FILE NATS_LOG_FILE	string		The path to the log file. Activates logging to this file if set.
NATS_DEBUG_ADDR	string	127.0.0.1:9234	Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.
NATS_DEBUG_TOKEN	string		Token to secure the metrics endpoint.
NATS_DEBUG_PPROF	bool	false	Enables pprof, which can be used for profiling.
NATS_DEBUG_ZPAGES	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.
NATS_NATS_HOST	string	127.0.0.1	Bind address.
NATS_NATS_PORT	int	9233	Bind port.
NATS_NATS_CLUSTER_ID	string	ocis-cluster	ID of the NATS cluster.
NATS_NATS_STORE_DIR	string	/var/lib/ocis/nats	The directory where the filesystem storage will store NATS JetStream data. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/nats.
NATS_TLS_CERT	string	/var/lib/ocis/nats/tls.crt	Path/File name of the TLS server certificate (in PEM format) for the NATS listener. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/nats.
NATS_TLS_KEY	string	/var/lib/ocis/nats/tls.key	Path/File name for the TLS certificate key (in PEM format) for the NATS listener. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/nats.
OCIS_INSECURE NATS_TLS_SKIP_VERIFY_CLIENT_CERT	bool	false	Whether the NATS server should skip the client certificate verification during the TLS handshake.
OCIS_EVENTS_ENABLE_TLS NATS_EVENTS_ENABLE_TLS	bool	false	Enable TLS for the connection to the events broker. The events broker is the ocis service which receives and delivers events between the services.