Swarm administration¶

Service definition¶

The configuration is stored, checked and dispatched to OnSphere’s modules through the osp-configuration-dispatcher. More information is available in the osp-configuration-dispatcher chapter.

Common configuration of services¶

Each module will generate one service. Each of them has a default configuration provided but in some case you need to modify this configuration to fit your needs. This can be freely done in the OnSphere Git.

The compose file is an aggregate of all the module.service files present in the configuration, and a list of “generic-compose files” :

Files	Usage
stack.version	The version of the compose file
stack.configs	The access of the swarm configurations files
stack.networks	The configuration of networks
stack.volumes	The configuration of volumes

You can visualize the result of this aggregate directly in portainer.

../_images/portainer-view-stack-editor.png

Default networks¶

Network	Use
back	Used by modules to communicate with each other.
front	Used by modules that will communicate with the user (through the front-end).
outside_access	Used by modules needing to make queries to the outside of the swarm (e.g. a modbus connectors need to establish connections with the modbus slaves).
portainer	Used by the `osp-configuration-dispatcher` to control the stack.

For more information about the network configuration, you can check the official docker network configuration.

Defaults volumes¶

Warning

Docker swarm does not share volumes between node. See Persistent storage for more information.

The minimum configuration is :

volumes:
  osp-git: null
  osp-mysql: null
  osp-runtime-configuration: null

Volume	Usage
osp-git	Contains the stack configuration
osp-mysql	Contains the Keycloak configuration (authentication)
osp-runtime-configuration	Contains the currently running configuration

Additional documentation is available at docker volumes documentation.

Configurations¶

This is the link with the configuration provided for this SWARM.

configs:
  osp-config-1:
    external: true

Additional documentation is available at docker-configs documentation.

Modify the configuration of a service¶

Each service has a file named module.service. This name is used for the generation of the compose file.

You can add every docker-compose options you want to any service. The only rule is the first line must begin with the name of the service.

Note

You cannot change the name of the osp-services as the internal network routing is done with this naming format.

A typical module.service file looks like this :

osp-alarms:
  image: ${{image-repository}}osp-alarms${{image-version}}
  networks:
    - "back"
    - "mongo"
  depends_on:
    - "osp-configuration-dispatcher"
  secrets:
    ${{auto-generated-secret-access}}

Where :

${{auto-generated-secret-access}} is replaced at runtime by the secrets generated by the osp-configuration-dispatcher
${{image-repository}} is replaced by the docker repository from which the image should be retrieved from
${{image-version}} is replaced by the image version tag

Keywords¶

OnSphere provides some keywords to inject elements on the generated stack file (e.g to open a port when the debug mode is enabled).

There are two types of keywords.

Line¶

This type of keywords will replace the entire line.

keyword	Usage
`- ${{debug-tag:TAG}}`	The line is replaced by the _TAG_ on debug mode with ‘-’ at the beginning of the line
`${{auto-generated-secrets}}:`	Internal usage only : Is replaced by the generations of secret for all services. This field is mandatory in the stack.secrets files
`${{auto-generated-secrets-access}}`	Gives access to auto-generated module certificates signed by the local CA, usable only in services section ()not for external-services)
`${{disable-generic-logger-conf}}:`	Appends the default logger configuration from the content of the file service-default-logger
`${{ports}}:`	Generates the port declaration of the service - i.e. `ports:` - if a port - e.g. debug-port or remote-port - is generated.
`${{debug-port:FIRST_PORT(:SECOND_PORT)}}`	This value is replaced with a port declaration to expose the given port if the service is in debug mode. This keyword must be placed inside the service port declaration. The _FIRST_PORT_ must be replaced by the mapping port on the container. e.g., if debug is accessible via port 5005 on the container, `${{debug-port:5005}}` will be replaced by “5005/tcp” where a port is generated by docker. Optionally, you can provide _SECOND_PORT_ which will act as docker-compose format `HOST:CONTAINER`.
`- ${{remote-port:PORT_DEF}}`	Insert _PORT_DEF_ if a remote connector is used in the configuration. This keyword must be placed inside the service port declaration. e.g. `${{remote-port:"5671:5671/tcp"}}` will expose port 5671 only if a remote module is present in the configuration.
`${{optional-env-section}}:`	Is replaced with `environment:` if any environment variable is added via keywords (should be added if `environment:` only depends on keywords, if you manually configure a variable, then you need to manually replace `${{optional-env-section}}:` with environment:).
`- ${{image-repo-env}}`	Creates an environment variable `IMAGE_REPO` containing the image repository (see ${{image-repository}}).
`- ${{image-version-env}}`	Creates an environment variable `IMAGE_VERSION` containing the image version (see ${{image-version}}).

In place¶

This type of keywords will only replace itself, allowing it to be injected into a line

keyword	Usage
`${{stackid}}`	Is replaced by the stack-id
`${{image-repository}}`	Is replaced by the image repository configured in the configuration dispatcher module.
`${{image-version}}`	Is replaced by the image version configured in the configuration dispatcher module.
`${{service-name}}`	Is replaced by the service name of the current module