CaaS Module

Migration Guide

e-Spirit AG

2020-03-30
Table of Contents

1. Introduction

As the CaaS develops, it is necessary to make internal adjustments that require manual modification by the user.

Starting from version 2.12 this document exclusively describes changes applying to the FirstSpirit module. Changes necessary for the platform are documented in a separate document.

Information relating to earlier versions is also contained and may apply to either module or platform.

If one or more versions are skipped during an update (for example, version 1.1.1 to 1.3.0) the migration steps of these versions must still be completed.

2. Update to version 2.9

As a prerequisite for the update to version 2.9, the CaaS version 2.8.6 must be installed! Before carrying out the update, we recommend that you back up the data stored in MongoDB.

2.1. Configuration of the MongoDB featureCompatibilityVersion

After updating MongoDB to version 4.0, the parameter featureCompatibilityVersion is now also set to 4.0. In the Kubernetes stack the configuration is fully automated, but in the Docker stack this must be done manually.

Once the CaaS is running in version 2.9, please execute the following command:

docker exec -it docker_caas-mongo_1 mongo \
    -u $MONGO_INITDB_ROOT_USERNAME \
    -p $MONGO_INITDB_ROOT_PASSWORD \
    --authenticationDatabase admin \
    --eval "db.adminCommand( { setFeatureCompatibilityVersion: '4.0' } )"

Of course, please replace the placeholders with the credentials you have configured.

For more information, see the MongoDB documentation.

3. Update to version 2.8

The MongoDB is being updated from version 3.6 to 4.0.

As a prerequisite for the update to version 2.8, the CaaS version 2.7.9 must be installed! Before carrying out the update, we recommend that you back up the data stored in MongoDB.

3.1. Compatibility changes of MongoDB

In general, you should check that all applications accessing the CaaS can handle the MongoDB compatibility changes in version 4.0. For a detailed listing of these changes, see the MongoDB documentation.

3.2. MongoDB featureCompatibilityVersion

After updating the CaaS to 2.8, the MongoDB will run in version 4.0 and with the parameter featureCompatibilityVersion set to the value 3.6. The update to the new MongoDB version and updating the featureCompatibilityVersion are kept separate on purpose. This value will be set to 4.0 in a subsequent release in order to be able to perform the update properly without downtime in the Kubernetes stack. More information can be found here:

3.3. Docker Compose

Please check before the update that the parameter featureCompatibilityVersion is set to 3.6. For more information about this requirement, see the official MongoDB documentation.

4. Update to version 2.7

As a prerequisite for the update to version 2.7, the CaaS version 2.6.1 must be installed! Before carrying out the update, we recommend that you back up the data stored in MongoDB.

4.1. Configuration of the MongoDB featureCompatibilityVersion

After updating MongoDB to version 3.6, the parameter featureCompatibilityVersion is now also set to 3.6. In the Kubernetes stack the configuration is fully automated, but in the Docker stack this must be done manually.

If you initially started using the Docker stack with a MongoDB version 3.6, then the featureCompatibilityVersion is already configured to 3.6 and this step is not necessary. If you are unsure, please consult the MongoDB documentation on how to query the featureCompatibilityVersion.

Once the CaaS is running in version 2.7, please execute the following command:

docker exec -it docker_caas-mongo_1 mongo \
    -u $MONGO_INITDB_ROOT_USERNAME \
    -p $MONGO_INITDB_ROOT_PASSWORD \
    --authenticationDatabase admin \
    --eval "db.adminCommand( { setFeatureCompatibilityVersion: '3.6' } )"

Of course, please replace the placeholders with the credentials you have configured.

For more information, see the MongoDB documentation.

4.2. Adaption of the Rest-API

This CaaS version eliminates the ping endpoint /_logic/metrics/ping from Rest-API.

If you use this endpoint, you can switch to using the metrics endpoint /_metrics instead.

5. Update to version 2.6

The MongoDB is being updated from version 3.4 to 3.6.

As a prerequisite for the update to version 2.6, the CaaS version 2.5.7 must be installed! Before carrying out the update, we recommend that you back up the data stored in MongoDB.

5.1. Compatibility changes of MongoDB

In general, you should check that all applications accessing the CaaS can handle the MongoDB compatibility changes in version 3.6. For a detailed listing of these changes, see the MongoDB documentation.

5.2. MongoDB featureCompatibilityVersion

After updating the CaaS to 2.6, the MongoDB will run in version 3.6 and with the parameter featureCompatibilityVersion set to the value 3.4. The update to the new MongoDB version and updating the featureCompatibilityVersion are kept separate on purpose. This value will be set to 3.6 in a subsequent release in order to be able to perform the update properly without downtime in the Kubernetes stack. More information can be found here:

5.3. Docker Compose

Please check before the update that the parameter featureCompatibilityVersion is set to 3.4. For more information about this requirement, see the official MongoDB documentation.

6. Update to version 2.4.9

This CaaS version will deliver a new implementation of the URL configurations. Existing URL configurations will be automatically migrated. For this purpose, after module installation on the FirstSpirit server (and a restart), the project components must be updated as usual. Updating (or reinstalling) the project component performs the migration of the old data. If an error occurs, the process is aborted.

If an error occurs while updating the components, migration of the existing data can not be performed. In this case, the module must be rolled back, as this version of the module no longer evaluates the old database.

7. Update to version 2.4.0

This CaaS version eliminates the included self-signed SSL certificates. Please take a look at the corresponding chapters in our documentation.

If you have used the supplied certificates so far, you must now set up and manage them independently. More information can be found in the Docker or Kubernetes documentation.

8. Update to version 2.3.1

The configuration of the URL factory used for media usage has been made via a free text field in the configuration dialog of the project component via a fully qualified class name. Starting with CaaS version 2.3.1, the UI provides a selection of available URL factories from which to choose which one to use. The selection now uses the names of the components under which they were published.

Existing configurations must be migrated in the project because the name of the class name is now invalid.

For configurations whose class names can be uniquely assigned to components available on the server, an automatic migration is performed when the project component is updated. Other URL factory entries must be corrected by reselecting and saving the project component. Please note that you need to update the module, restart the FirstSpirit server, and then update the project components to the new version.

9. Update to version 2.1.6

This release is different in relation to remote media than previous versions of CaaS. Unless you are using remote media and / or remote projects, this change does not affect you.

In CaaS versions prior to 2.1.6, media from remote projects have been transferred to the CaaS. From 2.1.6 this is no longer the case. This applies both to configurations with remote projects, as well as configurations that use a remote project configuration on their own project.

9.1. Why was this change made?

The use of remote projects makes it possible to reference elements in a project without having to generate them. For example, mainly static media can be maintained in a separate project and generated using a separate job.

Referencing projects can use the static content and generate it much more often because their jobs are now more resource-efficient.

In the past, resource-conserving setup with CaaS generation was not possible and, e.g. media deployment into a CDN was not feasible because remote content was always generated as well.

Choosing between classic FirstSpirit deployment and CaaS media deployment now enables the implementation of the scenarios listed above and meets the flexibility and efficiency requirements of a modern FirstSpirit project.

The use of remote projects in a CaaS generation is now also identical to common FirstSpirit projects.

9.2. What do I have to consider in the project?

If you use media in the project that is referenced from a remote project, these must now be made available in a place by the remote project, which can be reached by the application using the CaaS. In the remote project configuration the same URL Creator must be used that is also used in the remote project. The "paths prefix" must be set so that the application using the CaaS can resolve the media.

10. Update to version 2.0.22

The CaaS module now requires FirstSpirit 2018-07 or newer for operation.

Since FirstSpirit 5.2.1806, CaaS deployments have issued the warning "Access denied to de.espirit.firstspirit.agency.ConnectionDelegatingSpecialistsBroker$ManagerBrokerImpl". Previously, it was possible to suppress these warnings by setting a feature flag. As of FirstSpirit 2018-09, this is no longer possible, and using these internal APIs will result in errors that prevent installation and operation of an older CaaS module.

The CaaS module has been updated to run in FirstSpirit from 2018-09 as well. These changes mean that the CaaS module requires FirstSpirit 2018-07 or later from this release.

11. Disclaimer

This document is provided for information purposes only. e-Spirit may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. e-Spirit specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.