NATS Service Configuration

Table of Contents

Introduction
Default Values
Underlying Technology
Default Registry
Persistence
TLS Encryption
Configuration
- Environment Variables
- YAML Example

Introduction

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

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 a common resource.

Default Values

Thumbnails listens on port 9230 by default.
The default location storing events is $OCIS_BASE_DATA_PATH/nats

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 the embedded default registry via the MICRO_REGISTRY environment variable, see the Extended Environment Variables and Registry documentation for more details. If you do not want using the built-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.

Persistence

To be able to deliver events even after a system or service restart, the built in nats will store events in a folder on the local filesystem. This folder can be specified by setting the NATS_NATS_STORE_DIR environment 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 an 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 production environments, especially when using container orchestration with Kubernetes.

Configuration

Environment Variables

The nats service is configured via the following environment variables. Read the Environment Variable Types documentation for important details. Column IV shows with which release the environment variable has been introduced.

master + Rolling 6.6.1

Environment variables for the nats service
Name	IV	Type	Default Value	Description
`OCIS_TRACING_ENABLED` `NATS_TRACING_ENABLED`	pre5.0	bool	false	Activates tracing.
`OCIS_TRACING_TYPE` `NATS_TRACING_TYPE`	pre5.0	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`	pre5.0	string		The endpoint of the tracing agent.
`OCIS_TRACING_COLLECTOR` `NATS_TRACING_COLLECTOR`	pre5.0	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`	pre5.0	string		The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.
`OCIS_LOG_PRETTY` `NATS_LOG_PRETTY`	pre5.0	bool	false	Activates pretty log output.
`OCIS_LOG_COLOR` `NATS_LOG_COLOR`	pre5.0	bool	false	Activates colorized log output.
`OCIS_LOG_FILE` `NATS_LOG_FILE`	pre5.0	string		The path to the log file. Activates logging to this file if set.
`NATS_DEBUG_ADDR`	pre5.0	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`	pre5.0	string		Token to secure the metrics endpoint.
`NATS_DEBUG_PPROF`	pre5.0	bool	false	Enables pprof, which can be used for profiling.
`NATS_DEBUG_ZPAGES`	pre5.0	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.
`NATS_NATS_HOST`	pre5.0	string	127.0.0.1	Bind address.
`NATS_NATS_PORT`	pre5.0	int	9233	Bind port.
`NATS_NATS_CLUSTER_ID`	pre5.0	string	ocis-cluster	ID of the NATS cluster.
`NATS_NATS_STORE_DIR`	pre5.0	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`	pre5.0	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`	pre5.0	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`	pre5.0	bool	false	Whether the NATS server should skip the client certificate verification during the TLS handshake.
`OCIS_EVENTS_ENABLE_TLS` `NATS_EVENTS_ENABLE_TLS`	pre5.0	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.

YAML Example

Note the file shown below must be renamed and placed in the correct folder according to the Configuration File Naming conventions to be effective.
See the Notes for Environment Variables if you want to use environment variables in the yaml file.

master + Rolling 6.6.1

# 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