Upgrade

This section describes how to upgrade Everyware Cloud.

🚧

Read and understand these instructions before upgrading. Carefully review the planning and upgrading instructions.

Planning the upgrade

The upgrade process for Everyware Cloud provides minimal downtime.

There are a few factors to consider when planning an upgrade.

• To reduce risks Eurotech recommends a continual upgrade strategy to provide access to product improvements and new features and reduce version impacts
• A big gap between the current version and the target version could potentially make the upgrade more dangerous and risky

Upgrades from Everyware Cloud 5.0, 5.1, 5.2 or 5.3 require an interim upgrade to 5.4.
When upgrading to a minor version, first upgrade to the latest patch release on your current version.

Backup

Eurotech recommends backing up your data prior to any version upgrade. This includes both the databases and custom configurations. A backup provides the ability to revert and restore all the data used in the previous version if necessary.

Upgrade order

Eurotech recommends the following upgrade order:

• Events broker
• Messaging service
• Admin Console
• RESTful API
• VPN

Upgrade for patch releases

General recommendations

Be sure to read the Everyware Cloud release notes and the planning the upgrade section.

Preparing to upgrade

Before upgrading to a patch release be sure to follow these steps:

• backup the databases
• backup your existing configuration exporting all project configurations

Upgrade steps

Patch releases of Everyware Cloud usually do no introduce configuration or database changes. If any change is requires it will be describes pointing to the Everyware Cloud version that requires it.

The process to upgrade Everyware Cloud is the following:

• push the new version images to the local registry. This step is the same as the one described in Installation
• update the deployments with the new Docker images by editing the various deployment configurations selecting the new image to use

Upgrade steps for 5.5.2

🚧

Database Schema Update Notice

This patch introduces changes to the database schema. Remember to change the readiness and liveness probe initialDelaySeconds values to several minutes to avoid having the container recycled while the schema is being updated.

Version 5.5.2 introduces a fix for some of the tables of the database. The procedure for this upgrade differs slightly from the normal patch release update.

• push the new version images to the local registry. This step is the same as the one described in Installation
• scale down all the deployments to 0 pods
• change the value of the readiness and liveness probes for the broker pod to 100000, keeping track of the previous values
• update the deployments with the new Docker images by editing the various deployment configurations selecting the new image to use
• scale up the broker deployment to 1 pod and wait for the schema to be updates. This can be followed in the pod logs
• scale up all the other containers to the desired number of pods
• change back the readiness and liveness probes of the broker to the previous values
• scale up the broker to the desired number of pods

Upgrade from 5.4 to 5.5

General recommendations

Be sure to read the Everyware Cloud release notes and the planning the upgrade section.

It's recommended to upgrade to the latest version of the 5.4.x release before moving to 5.5.

Preparing to upgrade

Before upgrading to a patch release be sure to follow these steps:

• backup the databases
• backup your existing configuration exporting all project configurations

Upgrade steps

This upgrades requires schema updates in the database used by Everyware Cloud.

🚧

Database Schema Update Notice

This patch introduces changes to the database schema. Remember to change the readiness and liveness probe initialDelaySeconds values to several minutes to avoid having the container recycled while the schema is being updated.

The easiest way to deploy version 5.5.x is to delete the various OpenShift Deployments and redeploy them using the new templates. In this case it's important to take note of all the customisation that has been done to the original deployment. The procedure is the same described for the Deployments in Installation. It is not necessary to redeploy ConfigMaps, Secrets and Services.

Alternatively it's possible to update the existing Deployments following the rest of this chapter.

Before starting the update execute the following general:

• push the new version images to the local registry. This step is the same as the one described in Installation
• stop the various services. This can be achieved scaling down the deployments to 0. Official documentation could be found here
• enable schema update changing the config map containing Everyware Cloud deployments configuration to true
• add a new variable to the config map containing called db.ssl and set it to false (or true if your database exposes an SSL endpoint with a certificate signed by a well known authority)

To update the Events Broker:

• remove the JAVA_OPTS and JAVA_ARGS variables.
• update the deployments with the new Docker images by editing the various deployment configurations selecting the new image to use
• change the number of pods to the original one. Official documentation could be found here

To update the REST APIs:

• add a new variable DB_SSL and make it point to the db.ssl property of the config map
• add a new variable MAX_HEAP with the value of xmx from JAVA_OPTS
• if you ever added anything custom to the JAVA_OPTS environment variable remove everything except the customisation. If the value is the default completely remove the JAVA_OPTS variable
• update the deployments with the new Docker images by editing the various deployment configurations selecting the new image to use
• change the number of pods to the original one. Official documentation could be found here

To update the Web Console:

• add a new variable DB_SSL and make it point to the db.ssl property of the config map
• add a new variable MAX_HEAP with the value of xmx from JAVA_OPTS
• if you ever added anything custom to the JAVA_OPTS environment variable remove everything except the customisation. If the value is the default completely remove the JAVA_OPTS variable
• update the deployments with the new Docker images by editing the various deployment configurations selecting the new image to use
• change the number of pods to the original one. Official documentation could be found here

To update the Message Broker:

• add a new variable DB_SSL and make it point to the db.ssl property of the config map
• add a new variable MAX_HEAP with the value of xmx from ACTIVEMQ_OPTS
• add a new variable CLUSTER_NAME with the value of cluster.name from ACTIVEMQ_OPTS
• if you ever added anything custom to the ACTIVEMQ_OPTS environment variable remove everything except the customisation. If the value is the default completely remove the ACTIVEMQ_OPTS variable
• update the deployments with the new Docker images by editing the various deployment configurations selecting the new image to use
• change the number of pods to the original one. Official documentation could be found here

To update the VPN Server:

• add a new variable DB_SSL and make it point to the db.ssl property of the config map
• add a new variable MAX_HEAP with the value of xmx from JAVA_OPTS
• if you ever added anything custom to the JAVA_OPTS environment variable remove everything
• in the VPN Server deployment configuration create a new variable VPN_SERVER_NAME containing the name of the VPN Server deployment
• update the deployments with the new Docker images by editing the various deployment configurations selecting the new image to use
• change the number of pods to the original one. Official documentation could be found here

Once the update of the various components is complete:

• enable schema update changing the config map containing Everyware Cloud deployments configuration to false

Rollback an upgrade

In case of problems with the upgraded version it's possible to revert to a previous version.

The steps for the rollback are the following:

• stop all the services scaling down the deployments to 0. Official documentation could be found here
• restore the databases to the backed-up version
• revert the deployment configuration to the previous version. OpenShift official documentation could be found here
• start the services scaling up the deployments to 1 and then, once the service is available again, to the original number of pods. Follow the order described in the planning section. Official documentation could be found here

Known Issues

In case of problems logging in to the Console after the upgrade refresh the page (usually F12 on most browsers). This is usually caused by files cached by the browser and not compatible between different versions of the Console.