Upgrading swarm configuration

Note

If your onsphere instance is running using an unmanaged system check this page Upgrading unmanaged configuration

The following guide explains how to update the stack to a newer version.

Warning

Before doing anything, you should first make sure the host running the stack has enough free disk space remaining to perform an update. (Each new module takes around 500MB)

Warning

The following process aims at minimizing services interruption time but restart of service will always create a downtime.

Warning

If MongoDB doesn’t start during the upgrade process, check if it has been upgraded to a new major version. If so, the MongoDB fail to start after update guide will help you resolve the issue.

Note

To speed up the whole process you can pull all required images for the new version before starting the update.

0. (optional) to free space beforehand and make sure after update you only have versions N and N-1

docker image prune

1. Ensure that the Composer version is at least the same as the wanted version

2. Update the configuration-dispatcher version

Edit the file modules/configuration-dispatcher/main/module.service from

image: ${{image-repository}}osp-configuration-dispatcher${{image-version}}
environment:
  - IMAGE_REPO=nexus.onsphere.ch
  - IMAGE_VERSION=[old-version]

Note

Usage of place-holder image-version to specify the osp-configuration-dispatcher version is deprecated. As such it is possible (and valid) your module.service file already uses hardcoded version (e.g 1.3.3).

to

image: ${{image-repository}}osp-configuration-dispatcher:[new-version]
environment:
  - IMAGE_REPO=nexus.onsphere.ch
  - IMAGE_VERSION=[old-version]

Note

If the environment section of your configuration does not look like this but instead uses only variables (i.e ${{optional-env-section}}, ${{image-repo-env}}, ${{image-version-env}}) you can simply replace ${{image-repo-env}} and ${{image-version-env}} with above format : IMAGE_REPO and IMAGE_VERSION.

Warning

If you change the IMAGE_VERSION, every module will restart and wait for the configuration. The valid configuration will not be available until step 8.

3. Push the configuration

4. Update your configuration by applying patches

5. Set the version for all modules

Edit the file modules/configuration-dispatcher/main/module.service from

image: ${{image-repository}}osp-configuration-dispatcher:[new-version]
environment:
  - IMAGE_REPO=nexus.onsphere.ch
  - IMAGE_VERSION=[old-version]

to

image: ${{image-repository}}osp-configuration-dispatcher:[new-version]
environment:
  - IMAGE_REPO=nexus.onsphere.ch
  - IMAGE_VERSION=[new-version]

6. Wait until the osp-configuration-dispatcher is running with the targeted version

7. Push the updated configuration

8. Check if the configuration is accepted

• Fix it if it is not by using the provided error message, then re-push

9. Wait until the system is running with the new version

Note

Updates take disk space. Keeping version N-1 (N being the version now running) on the host is always a good idea in case a rollback is needed. Anything prior N-1 can (should) be removed.