osp-configuration-dispatcher

Overview

The configuration dispatcher functions as a repository that stores configurations and facilitates access for other modules. It maintains a configuration history, allowing for change tracking and the ability to revert to previous configurations.

This module provides the following functionalities:

• Module authentication

  • Generation of module certificates when required.

  • Storage of certificates in Swarm.

  • Maintenance of up-to-date stack definitions based on the configuration.

• Configuration storage (see the persistent configuration section for details).

• Sending configurations to modules.

• A GIT interface with configuration validation.

Warning

During its initial execution, the dispatcher may experience delays in certificate generation. These delays can be particularly pronounced if the system lacks a reliable entropy source, such as in virtual machine environments. It is essential to ensure that your system is properly configured for optimal performance in such cases.

List of Configuration Files

Filename	Short Description	Format	Documentation
module.service	Each service is described in its own file and then assembled	yml	See the Swarm administration or Official documentation
module.dispatcher	Defines the dispatcher configuration	json	module.dispatcher
owner.dispatcher	Defines the supervision of modules	json	module.dispatcher

Environment Variables

All modules env variables

Variable Name	Default Value	Usage
PROMETHEUS_PORT	9100	The internal port used for Openmetrics exposition.
DISPATCHER_HOST	modules_configuration-dispatcher_main	The hostname on which the modules can fetch the configuration.
DISPATCHER_PORT	10000	The port used by the module to listen for configuration request.
USE_LEGACY_RESTART	Not set	When this flag is enabled, the container will terminate itself whenever a restart is needed (for example, after a configuration change). This is the legacy restart (before version 2.1.0). Otherwise, the system will simply restart the process running inside the container.
CUSTOM_JVM_OPTIONS	Not set	Allow to inject JVM options. See Configuration changes for more information.
ALLOW_VERSION_MISMATCH	Not set	Allow to disable the version check when a new configuration is published to a module. By default, a module will not be restarted if its configuration does not match its version.

Dedicated variables

Variable Name	Default Value	Usage
ORCHESTRATOR_MODE	SWARM	Sets the orchestrator mode on which OnSphere is running. Possible values are: SWARM For stacks running in a managed Swarm environment. Uses Portainer to manage module lifecycles and automatically create/destroy modules based on the configuration. See this section for installation in this mode.. UNMANAGED Fully unmanaged mode. The dispatcher no longer handles module creation or destruction. The integrator must manually create all resources required by the application. This provides full control but requires solid knowledge of OnSphere and the selected orchestrator. See this section for installation in this mode.
K8S_NAMESPACE	None	Used only in UNMANAGED mode. Specifies the namespace of the stack.
PORTAINER_USER	admin	The username used to connect to Portainer. This variable overrides any value set in the configuration.
PORTAINER_PASSWORD	swissdotnet	The password used to connect to Portainer. This variable overrides any value set in the configuration.
PORTAINER_ADDRESS	None	The address used to connect to Portainer. This variable overrides any value set in the configuration.
PORTAINER_STACK_NAME	None	The name of the Portainer stack. This variable overrides any value set in the configuration.
PORTAINER_ENDPOINT_ID	None	The Portainer endpoint used for this stack. This variable overrides any value set in the configuration. More information available in the Portainer documentation.
dispatcher-threads-number	50	Sets the number of threads used by the configuration dispatcher. This is useful when managing a large number of modules. One thread is dedicated to each module during configuration parsing. Reduce this value if working with limited CPU resources.
dispatcher-threads-file-hierarchy	50	Sets the number of virtual threads used during the initial configuration parsing phase. Adjusting this value balances synchronization time and concurrent performance. These are virtual threads, so there’s no strict limit on their number.
aggregation-timeout-ms	15000	Maximum time in milliseconds allowed to parse a configuration after it is pushed. If this timeout is exceeded, the configuration is rejected.
wait-for-configuration-timeout-ms	60000	Maximum time (in milliseconds) to wait for a configuration to be fully parsed.

Supervision Prometheus (Beta)

Module state supervision

Warning

OpenMetrics only allow a dedicated character set a-zA-Z0-9_; any other character is replaced with _.

Metric	Type	Description
module_id + _heartbeat_counter_total	counter	Number of messages published to RabbitMQ but not acknowledged by the server.
module_id + _heartbeat_state	gauge	Each module communicates with the dispatcher via a heartbeat. This metric reports the module’s state as computed by the dispatcher: - 0.0 = RUNNING - 1.0 = RUNNING_WITH_ERROR - 2.0 = CONFIG_OUTDATED - 3.0 = UNREACHABLE - 4.0 = REMOVED

Default Aggregator Execution Time Metrics

Warning

These metrics can be modified at any time and expose the internal state and behavior of the system, which is useful for debugging the stack.

Metric	Labels	Description
git_hook_api_seconds	gauge	Execution time in seconds for the git hook API. Labels: step
executor_file_hierarchy_change_seconds	gauge	File hierarchy session execution time for changes
get_values_seconds	gauge	Execution time in seconds for getting values
aggregator_main_aggregate_seconds	gauge	Aggregate execution time. Labels: module
default_aggregator_seconds	gauge	Default aggregator execution time in seconds. Labels: module, step
executor_aggregation_total_async_task	gauge	Aggregation execution time for every async task
executor_aggregation_async_task	gauge	Aggregation execution time for async tasks. Labels: module, aggregator

Healthcheck

The healthcheck process sends an API request to the dispatcher’s REST “git hook” to ensure the module is running.