From d82e0ff5ef5e821c4eb1540597fca980a6addadd Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Mon, 14 Oct 2024 10:42:00 +0200 Subject: [PATCH 1/8] add registry --- .../services/env-vars-special-scope.adoc | 2 ++ .../pages/deployment/services/registry.adoc | 22 +++++++++++++++++++ modules/ROOT/partials/nav.adoc | 1 + 3 files changed, 25 insertions(+) create mode 100644 modules/ROOT/pages/deployment/services/registry.adoc diff --git a/modules/ROOT/pages/deployment/services/env-vars-special-scope.adoc b/modules/ROOT/pages/deployment/services/env-vars-special-scope.adoc index 18500dae3..a129eb498 100644 --- a/modules/ROOT/pages/deployment/services/env-vars-special-scope.adoc +++ b/modules/ROOT/pages/deployment/services/env-vars-special-scope.adoc @@ -36,6 +36,8 @@ see the readme.md file in that folder. :service_name: extended +Note, see the xref:deployment/services/registry.adoc[Registry] documentation for details on the Micro Registry and their available settings. + include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only] diff --git a/modules/ROOT/pages/deployment/services/registry.adoc b/modules/ROOT/pages/deployment/services/registry.adoc new file mode 100644 index 000000000..57d4fb206 --- /dev/null +++ b/modules/ROOT/pages/deployment/services/registry.adoc @@ -0,0 +1,22 @@ += Registry +:toc: right +:description: Services need, to be able to communicate with each other, register in a common registry. + +== Introduction + +{description} The registry is defined via xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[Extended Environment Variables]. + +== Available Registries + +The type of registry to use can be configured with the `MICRO_REGISTRY` environment variable and subsequent ones. Supported values are: + +* *nats-js-kv* (Default) + +Set the environment variable to `nats-js-kv` or leave it empty to use a nats-js key value store as registry. ++ +NOTE: If not running _build-in nats_, `MICRO_REGISTRY_ADDRESS` needs to be set to the address of the nats-js cluster, which is the same value as `OCIS_EVENTS_ENDPOINT`. Optional: Use `MICRO_REGISTRY_AUTH_USERNAME` and `MICRO_REGISTRY_AUTH_PASSWORD` to authenticate with the nats cluster. + +* *kubernetes* + +When deploying in a kubernetes cluster, the Kubernetes registry can be used. Additionally, the `MICRO_REGISTRY_ADDRESS` environment variable needs to be set to the url of the Kubernetes registry. + +* *memory* + +Setting the environment variable to memory starts an in-memory registry. This only works with the single binary deployment. diff --git a/modules/ROOT/partials/nav.adoc b/modules/ROOT/partials/nav.adoc index d699bc246..c44858fa8 100644 --- a/modules/ROOT/partials/nav.adoc +++ b/modules/ROOT/partials/nav.adoc @@ -23,6 +23,7 @@ **** xref:deployment/services/env-var-note.adoc[Environment Variable Notes] **** xref:deployment/services/env-vars-special-scope.adoc[Environment Variables with Special Scope] **** xref:deployment/services/env-var-changes.adoc[Environment Variable Changes] +**** xref:deployment/services/registry.adoc[Registry] **** xref:deployment/services/caching.adoc[Caching and Persistence] **** xref:deployment/services/gateways.adoc[Gateways] **** xref:deployment/services/logging.adoc[Logging] From db26d2dee4a171de48d08df5624c8191045847bb Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Mon, 14 Oct 2024 11:01:32 +0200 Subject: [PATCH 2/8] update nats --- modules/ROOT/pages/deployment/services/registry.adoc | 4 ++-- modules/ROOT/pages/deployment/services/s-list/nats.adoc | 6 ++++++ 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/deployment/services/registry.adoc b/modules/ROOT/pages/deployment/services/registry.adoc index 57d4fb206..fd0aaa7f7 100644 --- a/modules/ROOT/pages/deployment/services/registry.adoc +++ b/modules/ROOT/pages/deployment/services/registry.adoc @@ -1,10 +1,10 @@ = Registry :toc: right -:description: Services need, to be able to communicate with each other, register in a common registry. +:description: All services need to be able to communicate with each other. To do so, they register in a common registry. == Introduction -{description} The registry is defined via xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[Extended Environment Variables]. +{description} The registry is defined via xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[Extended Environment Variables]. Also see the xref:{s-path}/nats.adoc[nats] service which provides an embedded nats based registry. == Available Registries diff --git a/modules/ROOT/pages/deployment/services/s-list/nats.adoc b/modules/ROOT/pages/deployment/services/s-list/nats.adoc index 5269dfee3..0bd676589 100644 --- a/modules/ROOT/pages/deployment/services/s-list/nats.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/nats.adoc @@ -21,6 +21,12 @@ Services can `Consume` events from the nats service by registering to a `Consume As the service name suggests, this service is based on https://nats.io/[NATS] specifically on https://docs.nats.io/nats-concepts/jetstream[NATS Jetstream] to enable persistence. +== Default Registry + +By default, `nats-js-kv` is configured as embedded default registry via the `MICRO_REGISTRY` environment variable, see the xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[Extended Environment Variables] and xref:deployment/services/registry.adoc[Registry] documentation for more details. 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. + +NOTE: When `MICRO_REGISTRY` is configured using `kubernetes`, the NATS service will not be used but the Kubernetes registry. In this case, the `MICRO_REGISTRY_ADDRESS` environment variable needs to be set to the url of the Kubernetes registry. + == Persistence 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` environment variable. If not set, the service will fall back to `$OCIS_BASE_DATA_PATH:/nats`. From 880dfc43688b5a90a27777d759824fdb8ad35740 Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Mon, 14 Oct 2024 12:35:36 +0200 Subject: [PATCH 3/8] more texts and fixes --- modules/ROOT/pages/deployment/services/caching.adoc | 10 +++++++++- .../ROOT/pages/deployment/services/s-list/nats.adoc | 4 ++-- .../pages/deployment/services/s-list/thumbnails.adoc | 2 +- modules/ROOT/partials/multi-location/caching-list.adoc | 4 ++++ 4 files changed, 16 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/deployment/services/caching.adoc b/modules/ROOT/pages/deployment/services/caching.adoc index 51885579d..aad84c456 100644 --- a/modules/ROOT/pages/deployment/services/caching.adoc +++ b/modules/ROOT/pages/deployment/services/caching.adoc @@ -17,7 +17,7 @@ With this kind of store, saving information temporarily on a persistent media is * *Scaling* + When services are scaled horizontally (instantiated), a common and persistent base for generated data is necessary. -=== Identifying Caches by their Name +=== Identifying Caches by Their Name * *Performance caches* + Can be identified via environment variables ending with `xxx_CACHE_STORE` which is valid for both local and global ones. @@ -34,6 +34,14 @@ This type has best performance but is not suitable for all requirements as it ha * *External products* + These products like `nats-js-kv` or `redis-sentinel` are independent services not related to Infinite Scale. They are usually installed on separate hardware requiring their own performance, availability and scalability measures. These products are connected via a fast network. Infinite Scale connects to these store types and uses their services like a black box. +=== Overview of Available Types + +The following table gives an overview of available store types in Ininite Scale. + +{empty} + +include::partial$multi-location/caching-list.adoc[tag=store-types-list] + === Local vs Global Configuration * Performance and persistent types can be configured per service individually or via global environment variables. See the xref:deployment/services/env-var-note.adoc[Notes for Environment Variables] for details with regards to settings precedence. diff --git a/modules/ROOT/pages/deployment/services/s-list/nats.adoc b/modules/ROOT/pages/deployment/services/s-list/nats.adoc index 0bd676589..dd9c07755 100644 --- a/modules/ROOT/pages/deployment/services/s-list/nats.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/nats.adoc @@ -15,7 +15,7 @@ Services can `Consume` events from the nats service by registering to a `Consume == Default Values * Thumbnails listens on port 9230 by default. -* The default location storing events is $OCIS_BASE_DATA_PATH:/nats +* The default location storing events is $OCIS_BASE_DATA_PATH/nats == Underlying Technology @@ -29,7 +29,7 @@ NOTE: When `MICRO_REGISTRY` is configured using `kubernetes`, the NATS service w == Persistence -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` environment variable. If not set, the service will fall back to `$OCIS_BASE_DATA_PATH:/nats`. +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 diff --git a/modules/ROOT/pages/deployment/services/s-list/thumbnails.adoc b/modules/ROOT/pages/deployment/services/s-list/thumbnails.adoc index feceec4c4..0c2b841c4 100644 --- a/modules/ROOT/pages/deployment/services/s-list/thumbnails.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/thumbnails.adoc @@ -13,7 +13,7 @@ Note for developers, more information is available with regards to querying thum == Default Values * Thumbnails listens on port 9185 by default. -* The default location storing thumbnails is $OCIS_BASE_DATA_PATH:/thumbnails +* The default location storing thumbnails is $OCIS_BASE_DATA_PATH/thumbnails == Configuration Hints diff --git a/modules/ROOT/partials/multi-location/caching-list.adoc b/modules/ROOT/partials/multi-location/caching-list.adoc index 8c04925cd..7131ad8d9 100644 --- a/modules/ROOT/partials/multi-location/caching-list.adoc +++ b/modules/ROOT/partials/multi-location/caching-list.adoc @@ -20,6 +20,8 @@ Note that for each global environment variable, a service-based one might be ava {empty} + {empty} + +tag::store-types-list[] + [width=100%,cols="25%,85%",options=header] |=== | Store Type @@ -50,6 +52,8 @@ Note that for each global environment variable, a service-based one might be ava | *(deprecated)* Stores data using the key-value-store feature of https://docs.nats.io/nats-concepts/jetstream/key-value-store[NATS JetStream]. |=== +end::store-types-list[] + Other store types may work but are currently not supported. NOTE: The {service_name} service can only be scaled if not using the `memory` store and the stores are configured identically over all instances! From e175de046d85ea84b57760de54399efb858a0a50 Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Mon, 14 Oct 2024 15:51:36 +0200 Subject: [PATCH 4/8] tag import and fixes --- .../ROOT/pages/deployment/services/caching.adoc | 2 +- .../partials/multi-location/caching-list.adoc | 17 ++++++++++------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/deployment/services/caching.adoc b/modules/ROOT/pages/deployment/services/caching.adoc index aad84c456..3a0544cae 100644 --- a/modules/ROOT/pages/deployment/services/caching.adoc +++ b/modules/ROOT/pages/deployment/services/caching.adoc @@ -36,7 +36,7 @@ These products like `nats-js-kv` or `redis-sentinel` are independent services no === Overview of Available Types -The following table gives an overview of available store types in Ininite Scale. +The following table gives an overview of store types available in Ininite Scale. {empty} diff --git a/modules/ROOT/partials/multi-location/caching-list.adoc b/modules/ROOT/partials/multi-location/caching-list.adoc index 7131ad8d9..8e4e7d209 100644 --- a/modules/ROOT/partials/multi-location/caching-list.adoc +++ b/modules/ROOT/partials/multi-location/caching-list.adoc @@ -17,10 +17,11 @@ The {service_name} service can use a configured store via the global `{env_store Note that for each global environment variable, a service-based one might be available additionally. For precedences see xref:deployment/services/env-var-note.adoc[Environment Variable Notes]. Check the configuration section below. Supported stores are: -{empty} + -{empty} + +{empty} -tag::store-types-list[] +// note *in this case* the comment for the tag is necessary: https://asciidoc.zulipchat.com/#narrow/stream/335214-general/topic/Tag.20region.20question.20-.20rendering.20issue.20in.20some.20cases + +// tag::store-types-list[] [width=100%,cols="25%,85%",options=header] |=== @@ -28,13 +29,15 @@ tag::store-types-list[] | Description | `memory` -| Basic in-memory store and the default. +| Basic in-memory store. + +Usually the default for caches, see store environment variable which one is used. | `redis-sentinel` | Stores data in a configured Redis Sentinel cluster. | `nats-js-kv` -| Stores data using key-value-store feature of https://docs.nats.io/nats-concepts/jetstream/key-value-store[NATS JetStream]. +| Stores data using key-value-store feature of https://docs.nats.io/nats-concepts/jetstream/key-value-store[NATS JetStream]. + +Usually the default for stores, see store environment variable which one is used. | `noop` | Stores nothing. Useful for testing. Not recommended in production environments. @@ -52,7 +55,7 @@ tag::store-types-list[] | *(deprecated)* Stores data using the key-value-store feature of https://docs.nats.io/nats-concepts/jetstream/key-value-store[NATS JetStream]. |=== -end::store-types-list[] +// end::store-types-list[] Other store types may work but are currently not supported. @@ -67,7 +70,7 @@ Store specific notes:: The Redis master to use is configured via e.g. `{env_nodes}` in the form of `:/` like `10.10.0.200:26379/mymaster`. * When using `nats-js-kv`: + -** It is recommended to set `{env_nodes}` to the same value as `OCIS_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. +** It is recommended to set `{env_nodes}` to the same value as `OCIS_EVENTS_ENDPOINT`. That way the cache uses the same nats instance as the event bus. See the xref:event-bus-configuration[Event Bus Configuration] for more details. ** Authentication can be added, if configured, via `OCIS_CACHE_AUTH_USERNAME` and `OCIS_CACHE_AUTH_PASSWORD`. ** It is possible to set `OCIS_CACHE_DISABLE_PERSISTENCE` to instruct nats to not persist cache data on disc. -- From 2ce5755340db609e0dfda2b8495312af97cf7a0c Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Mon, 14 Oct 2024 16:09:01 +0200 Subject: [PATCH 5/8] unifying caching/storing/event_bus --- .../deployment/services/s-list/frontend.adoc | 8 +++---- .../deployment/services/s-list/gateway.adoc | 4 ++++ .../deployment/services/s-list/graph.adoc | 14 ++++++------ .../services/s-list/postprocessing.adoc | 8 +++---- .../deployment/services/s-list/proxy.adoc | 22 +++++++++++-------- .../deployment/services/s-list/settings.adoc | 22 +++++++++++-------- .../services/s-list/storage-system.adoc | 4 ++++ .../services/s-list/storage-users.adoc | 8 +++---- .../deployment/services/s-list/userlog.adoc | 22 +++++++++---------- 9 files changed, 64 insertions(+), 48 deletions(-) diff --git a/modules/ROOT/pages/deployment/services/s-list/frontend.adoc b/modules/ROOT/pages/deployment/services/s-list/frontend.adoc index 7da529124..9ed3e2c2e 100644 --- a/modules/ROOT/pages/deployment/services/s-list/frontend.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/frontend.adoc @@ -113,10 +113,6 @@ While the frontend service does not persist any data, it does cache information A lot of user management is done via the standardized LibreGraph API. Depending on how the system is configured, there might be some user attributes that an Infinite Scale instance admin can't change because of properties coming from an external LDAP server, or similar. This can be the case when the Infinite Scale admin is not the LDAP admin. To make life easier for admins, read-only attributes can be displayed differently, e.g. grayed out. To configure these hints for the frontend, use the environment variable `FRONTEND_READONLY_USER_ATTRIBUTES`, which takes a comma separated list of attributes. See the environment variable for supported values. -== Event Bus Configuration - -include::partial$multi-location/event-bus.adoc[] - == Caching // renders dependent on is_cache or is_stat @@ -124,6 +120,10 @@ include::partial$multi-location/event-bus.adoc[] include::partial$multi-location/caching-list.adoc[] +== Event Bus Configuration + +include::partial$multi-location/event-bus.adoc[] + == Configuration include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-yaml] diff --git a/modules/ROOT/pages/deployment/services/s-list/gateway.adoc b/modules/ROOT/pages/deployment/services/s-list/gateway.adoc index bda6752db..da2cab89f 100644 --- a/modules/ROOT/pages/deployment/services/s-list/gateway.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/gateway.adoc @@ -21,6 +21,10 @@ include::partial$multi-location/caching-list.adoc[] +== Event Bus Configuration + +include::partial$multi-location/event-bus.adoc[] + == Configuration include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-yaml] diff --git a/modules/ROOT/pages/deployment/services/s-list/graph.adoc b/modules/ROOT/pages/deployment/services/s-list/graph.adoc index 20ae67a68..02bbc0b02 100644 --- a/modules/ROOT/pages/deployment/services/s-list/graph.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/graph.adoc @@ -72,13 +72,6 @@ To use the graph service for managing (create, update, delete) users and groups, Some API endpoints provided by the graph service allow query filters to be specified. The filter syntax is based on the https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_SystemQueryOptionfilter[OData Specification,window=_blank]. See the https://owncloud.dev/libre-graph-api/#/users/ListUsers[Libre Graph API,window=_blank] for examples on the filters supported when querying users. -== Caching - -// renders dependent on is_cache or is_stat -:is_cache: true - -include::partial$multi-location/caching-list.adoc[] - == Keycloak Configuration for the Personal Data Export If Keycloak is used for authentication, GDPR regulations require to add all personal identifiable information that Keycloak has about the user to the personal data export. To do this, the following environment variables must be set: @@ -124,6 +117,13 @@ Note that these roles are only available to assign if the client is in the `mast :envvar_name: GRAPH_TRANSLATION_PATH include::partial$deployment/services/translations.adoc[] +== Caching + +// renders dependent on is_cache or is_stat +:is_cache: true + +include::partial$multi-location/caching-list.adoc[] + == Event Bus Configuration include::partial$multi-location/event-bus.adoc[] diff --git a/modules/ROOT/pages/deployment/services/s-list/postprocessing.adoc b/modules/ROOT/pages/deployment/services/s-list/postprocessing.adoc index 63444f09b..c8ceb3a2f 100644 --- a/modules/ROOT/pages/deployment/services/s-list/postprocessing.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/postprocessing.adoc @@ -97,10 +97,6 @@ ocis postprocessing restart -s "finished" # Equivalent to the above. ocis postprocessing restart -s "virusscan" # Restart all uploads currently in virusscan step. ---- -== Event Bus Configuration - -include::partial$multi-location/event-bus.adoc[] - == Storing // renders dependent on is_cache or is_stat @@ -110,6 +106,10 @@ The `postprocessing` service needs to store some metadata about uploads to be ab include::partial$multi-location/caching-list.adoc[] +== Event Bus Configuration + +include::partial$multi-location/event-bus.adoc[] + == Configuration include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-yaml] diff --git a/modules/ROOT/pages/deployment/services/s-list/proxy.adoc b/modules/ROOT/pages/deployment/services/s-list/proxy.adoc index 6988deaed..bc335a68f 100644 --- a/modules/ROOT/pages/deployment/services/s-list/proxy.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/proxy.adoc @@ -148,15 +148,6 @@ The default `role_claim` (or `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`) is `roles`. The * In a production deployment, you want to have basic authentication (`PROXY_ENABLE_BASIC_AUTH`) _disabled_ which is the default state. You should also set up a firewall to only allow requests to the proxy service or the reverse proxy if you have one. Requests to the other services should be blocked by the firewall. -== Caching - -Important, also see section xref:presigned-urls[Presigned Urls] below. - -// renders dependent on is_cache or is_stat -:is_cache: true - -include::partial$multi-location/caching-list.adoc[] - == Presigned Urls Important, also see section xref:caching[caching] above. @@ -205,6 +196,19 @@ When using the Infinite Scale xref:{s-path}/idp.adoc[IDP service] instead of an For details on monitoring see the xref:monitoring/prometheus.adoc[Metrics for Prometheus] documentation. +== Caching + +Important, also see section xref:presigned-urls[Presigned Urls] below. + +// renders dependent on is_cache or is_stat +:is_cache: true + +include::partial$multi-location/caching-list.adoc[] + +== Event Bus Configuration + +include::partial$multi-location/event-bus.adoc[] + == Configuration include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-yaml] diff --git a/modules/ROOT/pages/deployment/services/s-list/settings.adoc b/modules/ROOT/pages/deployment/services/s-list/settings.adoc index cc748f4da..ad0710bfd 100644 --- a/modules/ROOT/pages/deployment/services/s-list/settings.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/settings.adoc @@ -30,15 +30,6 @@ The settings service supports two different backends for persisting the data. Th multiple intances of the `settings` service in a scale-out deployment and should be therefore considered deprecated. -== Caching - -// renders dependent on is_cache or is_stat -:is_cache: true - -When using `SETTINGS_STORE_TYPE=metadata`, the `settings` service caches the results of queries against the storage backend to provide faster responses. The content of this cache is independent of the cache used in the `storage-system` service as it caches directory listing and settings content stored in files. - -include::partial$multi-location/caching-list.adoc[] - == Settings Management Infinite Scale services can register *settings bundles* with the settings service. @@ -97,6 +88,19 @@ To create custom roles: See the full https://owncloud.dev/services/settings/#custom-roles[Custom Roles] json example in the developer documentation for more details. +== Caching + +// renders dependent on is_cache or is_stat +:is_cache: true + +When using `SETTINGS_STORE_TYPE=metadata`, the `settings` service caches the results of queries against the storage backend to provide faster responses. The content of this cache is independent of the cache used in the `storage-system` service as it caches directory listing and settings content stored in files. + +include::partial$multi-location/caching-list.adoc[] + +== Event Bus Configuration + +include::partial$multi-location/event-bus.adoc[] + == Configuration include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-yaml] diff --git a/modules/ROOT/pages/deployment/services/s-list/storage-system.adoc b/modules/ROOT/pages/deployment/services/s-list/storage-system.adoc index ad5fc9bce..536c92ece 100644 --- a/modules/ROOT/pages/deployment/services/s-list/storage-system.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/storage-system.adoc @@ -19,6 +19,10 @@ include::partial$multi-location/caching-list.adoc[] +== Event Bus Configuration + +include::partial$multi-location/event-bus.adoc[] + == Configuration include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-yaml] diff --git a/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc b/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc index edee78eff..d277576bf 100644 --- a/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc @@ -277,9 +277,9 @@ ocis storage-users trash-bin restore [command options] ['spaceID' required] ['it ---- -- -== Event Bus Configuration +== Resource Optimisation -include::partial$multi-location/event-bus.adoc[] +See the xref:deployment/storage/general-considerations.adoc#resource-optimisation[General Storage Considerations and Settings] documentation for details configuring the `STORAGE_USERS_OCIS_MAX_CONCURRENCY` environment variable. == Caching @@ -290,9 +290,9 @@ The `storage-users` service caches stat, metadata and uuids of files and folders include::partial$multi-location/caching-list.adoc[] -== Resource Optimisation +== Event Bus Configuration -See the xref:deployment/storage/general-considerations.adoc#resource-optimisation[General Storage Considerations and Settings] documentation for details configuring the `STORAGE_USERS_OCIS_MAX_CONCURRENCY` environment variable. +include::partial$multi-location/event-bus.adoc[] == Configuration diff --git a/modules/ROOT/pages/deployment/services/s-list/userlog.adoc b/modules/ROOT/pages/deployment/services/s-list/userlog.adoc index 63691d24f..89275ed9c 100644 --- a/modules/ROOT/pages/deployment/services/s-list/userlog.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/userlog.adoc @@ -20,17 +20,6 @@ include::partial$deployment/services/log-service-ecosystem.adoc[] Running the `userlog` service without running the xref:{s-path}/eventhistory.adoc[eventhistory] service is not possible. -== Storing - -// renders dependent on is_cache or is_stat -:is_stat: true - -include::partial$multi-location/caching-list.adoc[] - -== Event Bus Configuration - -include::partial$multi-location/event-bus.adoc[] - == Configuring Events Currently, the configuration which user-related events are of interest is hard-coded and cannot be changed. @@ -87,6 +76,17 @@ to remove a global message is a restricted action, see the xref:authentication[A :envvar_name: USERLOG_TRANSLATION_PATH include::partial$deployment/services/translations.adoc[] +== Storing + +// renders dependent on is_cache or is_stat +:is_stat: true + +include::partial$multi-location/caching-list.adoc[] + +== Event Bus Configuration + +include::partial$multi-location/event-bus.adoc[] + == Configuration include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-yaml] From 7f8a90c11fbb90b91fdd6501981b4240ab5f21e9 Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Wed, 16 Oct 2024 10:46:59 +0200 Subject: [PATCH 6/8] remove deprecated envvar descriptions --- .../ROOT/pages/deployment/services/registry.adoc | 3 --- .../partials/multi-location/caching-list.adoc | 16 +--------------- 2 files changed, 1 insertion(+), 18 deletions(-) diff --git a/modules/ROOT/pages/deployment/services/registry.adoc b/modules/ROOT/pages/deployment/services/registry.adoc index fd0aaa7f7..d44bbb9b7 100644 --- a/modules/ROOT/pages/deployment/services/registry.adoc +++ b/modules/ROOT/pages/deployment/services/registry.adoc @@ -15,8 +15,5 @@ Set the environment variable to `nats-js-kv` or leave it empty to use a nats-js + NOTE: If not running _build-in nats_, `MICRO_REGISTRY_ADDRESS` needs to be set to the address of the nats-js cluster, which is the same value as `OCIS_EVENTS_ENDPOINT`. Optional: Use `MICRO_REGISTRY_AUTH_USERNAME` and `MICRO_REGISTRY_AUTH_PASSWORD` to authenticate with the nats cluster. -* *kubernetes* + -When deploying in a kubernetes cluster, the Kubernetes registry can be used. Additionally, the `MICRO_REGISTRY_ADDRESS` environment variable needs to be set to the url of the Kubernetes registry. - * *memory* + Setting the environment variable to memory starts an in-memory registry. This only works with the single binary deployment. diff --git a/modules/ROOT/partials/multi-location/caching-list.adoc b/modules/ROOT/partials/multi-location/caching-list.adoc index 8e4e7d209..ec6cfeb59 100644 --- a/modules/ROOT/partials/multi-location/caching-list.adoc +++ b/modules/ROOT/partials/multi-location/caching-list.adoc @@ -19,7 +19,7 @@ Note that for each global environment variable, a service-based one might be ava {empty} -// note *in this case* the comment for the tag is necessary: https://asciidoc.zulipchat.com/#narrow/stream/335214-general/topic/Tag.20region.20question.20-.20rendering.20issue.20in.20some.20cases +// note *in this case* the comment for the tag block is NECCESSARY: https://asciidoc.zulipchat.com/#narrow/stream/335214-general/topic/Tag.20region.20question.20-.20rendering.20issue.20in.20some.20cases // tag::store-types-list[] @@ -41,24 +41,10 @@ Usually the default for stores, see store environment variable which one is used | `noop` | Stores nothing. Useful for testing. Not recommended in production environments. - -| `ocmem` -| *(deprecated)* Advanced in-memory store allowing max size. - -| `redis` -| *(deprecated)* Stores data in a configured Redis cluster. - -| `etcd` -| *(deprecated)* Stores data in a configured etcd cluster. - -| `nats-js` -| *(deprecated)* Stores data using the key-value-store feature of https://docs.nats.io/nats-concepts/jetstream/key-value-store[NATS JetStream]. |=== // end::store-types-list[] -Other store types may work but are currently not supported. - NOTE: The {service_name} service can only be scaled if not using the `memory` store and the stores are configured identically over all instances! NOTE: If you have used one of the deprecated stores of a former version, you should reconfigure to use one of the supported ones as the deprecated stores will be removed in a later version. From 6d72fd7b700127d51517b0728df59d0affa6c42d Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 16 Oct 2024 11:08:31 +0200 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Phil Davis --- modules/ROOT/pages/deployment/services/caching.adoc | 2 +- modules/ROOT/pages/deployment/services/registry.adoc | 2 +- modules/ROOT/pages/deployment/services/s-list/nats.adoc | 4 ++-- .../ROOT/pages/deployment/services/s-list/storage-users.adoc | 2 +- modules/ROOT/partials/multi-location/caching-list.adoc | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/deployment/services/caching.adoc b/modules/ROOT/pages/deployment/services/caching.adoc index 3a0544cae..37f3daf87 100644 --- a/modules/ROOT/pages/deployment/services/caching.adoc +++ b/modules/ROOT/pages/deployment/services/caching.adoc @@ -36,7 +36,7 @@ These products like `nats-js-kv` or `redis-sentinel` are independent services no === Overview of Available Types -The following table gives an overview of store types available in Ininite Scale. +The following table gives an overview of store types available in Infinite Scale. {empty} diff --git a/modules/ROOT/pages/deployment/services/registry.adoc b/modules/ROOT/pages/deployment/services/registry.adoc index d44bbb9b7..fc318acce 100644 --- a/modules/ROOT/pages/deployment/services/registry.adoc +++ b/modules/ROOT/pages/deployment/services/registry.adoc @@ -13,7 +13,7 @@ The type of registry to use can be configured with the `MICRO_REGISTRY` environm * *nats-js-kv* (Default) + Set the environment variable to `nats-js-kv` or leave it empty to use a nats-js key value store as registry. + -NOTE: If not running _build-in nats_, `MICRO_REGISTRY_ADDRESS` needs to be set to the address of the nats-js cluster, which is the same value as `OCIS_EVENTS_ENDPOINT`. Optional: Use `MICRO_REGISTRY_AUTH_USERNAME` and `MICRO_REGISTRY_AUTH_PASSWORD` to authenticate with the nats cluster. +NOTE: If not running _built-in nats_, `MICRO_REGISTRY_ADDRESS` needs to be set to the address of the nats-js cluster, which is the same value as `OCIS_EVENTS_ENDPOINT`. Optional: Use `MICRO_REGISTRY_AUTH_USERNAME` and `MICRO_REGISTRY_AUTH_PASSWORD` to authenticate with the nats cluster. * *memory* + Setting the environment variable to memory starts an in-memory registry. This only works with the single binary deployment. diff --git a/modules/ROOT/pages/deployment/services/s-list/nats.adoc b/modules/ROOT/pages/deployment/services/s-list/nats.adoc index dd9c07755..2750a08e7 100644 --- a/modules/ROOT/pages/deployment/services/s-list/nats.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/nats.adoc @@ -23,9 +23,9 @@ As the service name suggests, this service is based on https://nats.io/[NATS] sp == Default Registry -By default, `nats-js-kv` is configured as embedded default registry via the `MICRO_REGISTRY` environment variable, see the xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[Extended Environment Variables] and xref:deployment/services/registry.adoc[Registry] documentation for more details. 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. +By default, `nats-js-kv` is configured as the embedded default registry via the `MICRO_REGISTRY` environment variable, see the xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[Extended Environment Variables] and xref:deployment/services/registry.adoc[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. -NOTE: When `MICRO_REGISTRY` is configured using `kubernetes`, the NATS service will not be used but the Kubernetes registry. In this case, the `MICRO_REGISTRY_ADDRESS` environment variable needs to be set to the url of the Kubernetes registry. +NOTE: When `MICRO_REGISTRY` is configured using `kubernetes`, the Kubernetes registry will be used and not the NATS service. In this case, the `MICRO_REGISTRY_ADDRESS` environment variable needs to be set to the url of the Kubernetes registry. == Persistence diff --git a/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc b/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc index d277576bf..d7ec12dbb 100644 --- a/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/storage-users.adoc @@ -279,7 +279,7 @@ ocis storage-users trash-bin restore [command options] ['spaceID' required] ['it == Resource Optimisation -See the xref:deployment/storage/general-considerations.adoc#resource-optimisation[General Storage Considerations and Settings] documentation for details configuring the `STORAGE_USERS_OCIS_MAX_CONCURRENCY` environment variable. +See the xref:deployment/storage/general-considerations.adoc#resource-optimisation[General Storage Considerations and Settings] documentation for details about configuring the `STORAGE_USERS_OCIS_MAX_CONCURRENCY` environment variable. == Caching diff --git a/modules/ROOT/partials/multi-location/caching-list.adoc b/modules/ROOT/partials/multi-location/caching-list.adoc index ec6cfeb59..650a3afc5 100644 --- a/modules/ROOT/partials/multi-location/caching-list.adoc +++ b/modules/ROOT/partials/multi-location/caching-list.adoc @@ -30,14 +30,14 @@ Note that for each global environment variable, a service-based one might be ava | `memory` | Basic in-memory store. + -Usually the default for caches, see store environment variable which one is used. +Usually the default for caches, see the store environment variable for which one is used. | `redis-sentinel` | Stores data in a configured Redis Sentinel cluster. | `nats-js-kv` | Stores data using key-value-store feature of https://docs.nats.io/nats-concepts/jetstream/key-value-store[NATS JetStream]. + -Usually the default for stores, see store environment variable which one is used. +Usually the default for stores, see the store environment variable for which one is used. | `noop` | Stores nothing. Useful for testing. Not recommended in production environments. From f9e1e9f5513f8a72deffc5e5cdd8a1ba17e5b8de Mon Sep 17 00:00:00 2001 From: Martin Mattel Date: Wed, 16 Oct 2024 11:12:13 +0200 Subject: [PATCH 8/8] remove kubernetes remnant --- modules/ROOT/pages/deployment/services/s-list/nats.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/modules/ROOT/pages/deployment/services/s-list/nats.adoc b/modules/ROOT/pages/deployment/services/s-list/nats.adoc index 2750a08e7..67972865e 100644 --- a/modules/ROOT/pages/deployment/services/s-list/nats.adoc +++ b/modules/ROOT/pages/deployment/services/s-list/nats.adoc @@ -25,8 +25,6 @@ As the service name suggests, this service is based on https://nats.io/[NATS] sp By default, `nats-js-kv` is configured as the embedded default registry via the `MICRO_REGISTRY` environment variable, see the xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[Extended Environment Variables] and xref:deployment/services/registry.adoc[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. -NOTE: When `MICRO_REGISTRY` is configured using `kubernetes`, the Kubernetes registry will be used and not the NATS service. In this case, the `MICRO_REGISTRY_ADDRESS` environment variable needs to be set to the url of the Kubernetes registry. - == 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`.