From 1fa147fa36415a4e52e3248de925737308ceba9e Mon Sep 17 00:00:00 2001 From: jkoberg Date: Wed, 26 Oct 2022 14:26:33 +0200 Subject: [PATCH] readme for nats service Signed-off-by: jkoberg --- services/nats/README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 services/nats/README.md diff --git a/services/nats/README.md b/services/nats/README.md new file mode 100644 index 0000000000..ddadada901 --- /dev/null +++ b/services/nats/README.md @@ -0,0 +1,21 @@ +# Nats Service + +The nats service is the event broker of the system. It distributes events among all other services and enables other services to communicate asynchrounos. + +Services can `Publish` events to the nats service and nats will store these events on disk respectively distribute these events to other services eventually. Services can `Consume` events from the nats services 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 ressource. + +## Underlying technology + +As the service name suggests, this service is based on [NATS](https://nats.io/) specifically on [NATS Jetstream](https://docs.nats.io/nats-concepts/jetstream) to enable persistence. + +## 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.