Cloning configuration

Accessing the configuration

Since under the hood the configuration is git-managed, to access it after the deployment of the stack you simply need to clone it as you would any other git repository :

git clone ssh://administrator@<your-stack-ip>:5022/git/onsphere.git

or

git clone ssh://osp@<your-stack-ip>:5022/git/onsphere.git

The password for the administrator user is onsphere by default. See osp-keycloak to modify it. The password for the osp user is defined by the <stack-name>-admin-pwd secret.

Edition of the configuration

In order to be able to properly run while still letting you edit the configuration, OnSphere uses a two branches system. Each branch has its purpose and characteristics:

  • “master”: is the branch representing the configuration currently used, it is protected and can only be written through merges

  • “edit”: is the branch you will edit when you want to modify the configuration. For it to be used, it needs to be merged into the “master” branch

As you would for any git managed projects, once your modifications are done, you still need to add them to what is going to be part of the next commit using the git add command. e.g.:

git add path/to/file/impacted/by/modification

Once all modifications you want to be part of the next commit have been added, commit your changes with an appropriate message explaining why you made those changes, e.g.

git commit -m "Message explaining why you made those changes"

It is possible to make multiple modifications (therefore multiple commit) before requesting OnSphere to use the new configuration (which would reduce the number of module restart and therefore the associated services downtime).

After all modification you wanted to make are done (added and committed), you need to ask OnSphere to check the new configuration’s validity and if everything is OK, make use of the new configuration, e.g.:

git pull
git push

(the “git pull” command is called to make sure the local copy of the configuration you are working on is up to date)

The osp-configuration-dispatcher will then identify modules impacted by the modifications and run their “validity checker” (each module has its own binary used to verify the configuration complies with its requirements) to make sure the new configuration can be used. If everything is OK the osp-configuration-dispatcher will accept the new configuration and use it, otherwise it will return an error message explaining why the changes were refused.

A typical use case would look like this :

@startuml skinparam backgroundColor transparent hide footbox skinparam monochrome true title ** Configuration typical use case ** Actor Integrator box "osp-configuration-dispatcher" Actor "edit branch" as editBranch Actor "osp-configuration-dispatcher" as dispatcher Actor "master branch" as masterBranch end box Actor "module-X" as moduleX == Configuration retrieval == Integrator -> dispatcher : git clone ssh://administrator@your-stack-ip:5022/git/onsphere.git dispatcher -> Integrator : makes local copy of the configuration available Integrator -> dispatcher : git checkout edit dispatcher -> Integrator : switch to edit branch == Configuration edition == Integrator -> editBranch : modification A Integrator -> editBranch : git add path/to/modified/files/impacted/by/modify/A Integrator -> editBranch : modification B note right Modification B is not "added" here, only as an example to show that it is possible to modify something and not include it in the next commit end note Integrator -> editBranch : modification C Integrator -> editBranch : git add path/to/modified/files/impacted/by/modify/C == Changes validation == Integrator -> editBranch : git commit -m "Reason you made the modifications A and C" == Try to use new configuration == Integrator -> dispatcher : git pull note right The git pull command is used to make sure the local copy of the configuration we are working on is up to date (someone, from somewhere else could have modified it) end note Integrator -> dispatcher : git push dispatcher -> dispatcher : gather module configuration dispatcher -> dispatcher : identify modules whose configuration has been impacted dispatcher -> dispatcher : run modules targeted by modification validity checker alt Modification accepted dispatcher -> Integrator : new configuration accepted dispatcher -> masterBranch : merge origin/edit Integrator -> dispatcher : git pull note right To retrieve commit issued from the merge end note else Modification refused dispatcher -> Integrator : configuration refused because : ERROR MSG end @enduml