How to configure

OnSphere configuration is stored in a Git repository made available by the osp-configuration-dispatcher core-module. To reduce services downtime to a minimum, the osp-configuration-dispatcher uses one branch for the configuration currently running and another (the edit branch) for the configuration being edited. The edit branch is therefore the one you need to checkout and work on to interact with the OnSphere stack configuration. It does not mean you can not create other branches to work on (it is even recommended as it allows better granularity control on what is being modified) but once you are done, this is the branch your changes will have to be pushed on. When something is pushed on the edit branch, the osp-configuration-dispatcher checks the new configuration validity and either makes use of the new configuration or prevent the push when it detects errors.

OnSphere modularity means the whole stack does not have to be restarted each and every time a configuration change is made. Modules are only restarted when they are concerned by new configuration pushed on the edit branch. This behavior is offered by osp-configuration-dispatcher that handles per-module configuration processing.

OnSphere has four Core modules which are required for any OnSphere stack to properly work. Any module other than those four modules is called a plugin module which you can instantiate or not depending on your need, allowing you to only pay for what you need.

Note

To help you getting started with plugin modules default base configurations are provided. Those configurations are made available using Git branches. They are named osp-[MODULE]-configuration (e.g osp-modbus-configuration). The complete list can be found by calling :

$ git branch -a

in your OnSphere configuration directory. Once you have found the one you want to use, apply its content using :

$ git checkout origin/osp-[MODULE]-configuration -- .

The osp-configuration-dispatcher does the following for you:

  • Control the configuration validity.

    • Control field typing, field value validity, syntax, referencing, …

    • Only allow the deployment of a valid configuration.

  • Send the configuration to each module.

Git user

By default, git uses the user provided by Keycloak to access the configuration. A user needs to be a member of the group configuration to be able to retrieve and edit the configuration.

An osp user exists on the dispatcher allowing push even when the Keycloak module is down (error on the configuration). The password of this user is set by the secret admin-pwd. It can be changed by adding a new secret and setting, on the module.service of the configuration dispatcher. The new secret has to be mapped to admin-pwd.

Fetch the configuration

The configuration can be updated using git. It can be cloned with the following command:

git clone ssh://{user}@{IP}:{PORT}/git/onsphere.git

where {user} is a user member of the administrator group, {IP} is the IP address of the machine on which the configuration dispatcher is running and {PORT} is the exported port (by default 5022) of the SSH service on any node of the swarm.