1. Introduction

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

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

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

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 still must be completed.

2. Update to version 2.16

As a prerequisite for the update to version 2.16, the CaaS platform version 2.15.0 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.4, the parameter featureCompatibilityVersion is now also set to 4.4. 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.16, 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.4' } )"

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

For more information, see the MongoDB documentation.

3. Update to version 2.15

The MongoDB is being updated from version 4.2 to 4.4.

As a prerequisite for the update to version 2.15, the CaaS version 2.13.3 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.4. For a detailed listing of these changes, see the MongoDB documentation.

3.2. MongoDB featureCompatibilityVersion

After updating the CaaS to 2.15, the MongoDB will run in version 4.4 and with the parameter featureCompatibilityVersion set to the value 4.2. The update to the new MongoDB version and updating the featureCompatibilityVersion are kept separate on purpose. This value will be set to 4.4 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:

4. Update to version 2.14

The Rest-API is being updated from version 4.1 to 5.1.

4.1. Architectural changes

Authentication and Authorization in Rest-API are no longer located in a separate component (security proxy). It is no longer possible to disable the security proxy.

5. Update to version 2.13

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

5.1. Configuration of the MongoDB featureCompatibilityVersion

After updating MongoDB to version 4.2, the parameter featureCompatibilityVersion is now also set to 4.2. 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.13, 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.2' } )"

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

For more information, see the MongoDB documentation.

6. Update to version 2.12

The MongoDB is being updated from version 4.0 to 4.2.

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

6.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.2. For a detailed listing of these changes, see the MongoDB documentation.

6.2. MongoDB featureCompatibilityVersion

After updating the CaaS to 2.12, the MongoDB will run in version 4.2 and with the parameter featureCompatibilityVersion set to the value 4.0. The update to the new MongoDB version and updating the featureCompatibilityVersion are kept separate on purpose. This value will be set to 4.2 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:

6.3. Configuration of the MongoDB metrics endpoint

It is no longer possible to configure the MongoDB metrics endpoint via the Helm Chart. Specifically, the configuration items 'mongo.metrics.port', 'mongo.metrics.path' and 'mongo.metrics.socketTimeout' have been removed. The metrics are now permanently accessible under /metrics on port 9216.

7. Update to version 2.11

7.1. Re-installation of the Docker Compose stack

Starting with this version, it is necessary that MongoDB is run as replica set and no longer in standalone mode. To achieve this, the Docker Compose stack must be rebuilt. Kubernetes installations are not affected.

You can do so by removing the stack and simply running the setup steps again for the stack. Please keep in mind that the Docker Compose stack is no longer supported for any other situation than development work. New setups using the Docker Compose stack will already be set up correctly.

7.2. Changed health check URL

The Healthcheck endpoint URL has changed from /_logic/metrics/healthcheck to /_logic/healthcheck.

7.3. Configuration changes

It is no longer possible to use a custom logback.xml for log configuration. The components use INFO log level by default.

7.4. Architectural changes

Authentication and Authorization have been extracted from the Rest-API and are now located in a separate component. While this should not have any impact on users of CaaS, it is important to be aware of this for failure analysis and operations. URLs do not change.

7.5. Elimination of the included example monitoring stack

This version of the CaaS-Platform eliminates the deployments of kube-state-metrics, Prometheus, Alertmanager and Grafana. Therefore, the example monitoring stack previously included is no longer available. Instead, CaaS expects a monitoring environment set up with Prometheus operator into which it integrates automatically. For more information please consult the CaaS documentation.

7.6. Integration into the Prometheus operator monitoring stack

By default, CaaS-Platform is configured to automatically integrate into a monitoring stack installed by using Prometheus operator. CaaS-Platform achieves this by including labels for ServiceMonitors and Alerts that match the labels used by Prometheus in its default configuration. If you use a custom Prometheus configuration, please adapt the CaaS-Platform configuration accordingly to be picked up by Prometheus. Likewise for Grafana dashboards: the CaaS-Platform labels match the default labels used by the Grafana Sidecar container. The adaption of the CaaS-Platform labels is required if you used custom labels values.

7.7. Integration of additional dashboards

The integration of additional dashboards using the helm chart is no longer supported. Please use the default Grafana Sidecar container to integrate custom dashboards.

8. 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.

8.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.

9. 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.

9.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.

9.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:

9.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.

10. 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.

10.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.

10.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.

11. 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.

11.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.

11.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:

11.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.

12. 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.

13. 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.

14. 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.

15. 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.

15.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.

15.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.

16. 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.

17. Help

The Technical Support of the e-Spirit AG provides expert technical support covering any topic related to the FirstSpiritâ„¢ product. You can get and find more help concerning relevant topics in our community.

18. 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.