Introduction

This page provides information on how to upgrade a Kiuwan On-Premises Distributed installation. Note that this guide only applies to Kiuwan On-Premises installations distributed installations done using the kiuwan-cluster tool.

Checking for new versions

Web application mode

Currently installed versions and latest available versions of Kiuwan On-Premises are shown in the System Administration Console. To access this page, log into your Kiuwan On-Premises installation as "sysadmin".

You should see the following page (note that versions may change between this screenshot and your installation):

This table summarizes the meaning of the information shown in the previous screenshot:

Command Line Interface mode

You can also check your current Kiuwan On-Premises core version by running this command on a Kiuwan front instance host:

 cat [VOLUMES_DIR]/data-shared/publicData/current.version

Upgrade modes

You can upgrade only Kiuwan On-Premises clients or perform a full upgrade to your Kiuwan On-Premises installation.

Clients only mode

You can choose to upgrade only Kiuwan On-Premises clients as long as their latest versions are compatible with your currently installed Kiuwan core. The upgrade process will check this for your and stop the upgrade if your current Kiuwan core is not compatible with the latest available clients.

Kiuwan On-Premises clients are those Kiuwan products that your Kiuwan On-Premises servers will provide to your users:

• Kiuwan Local Analyzer
• Kiuwan Engine
• Kiuwan for developers IDE plugins or extensions (Eclipse, JetBrains, Visual Studio and Visual Studio Code).

There are more Kiuwan clients that you may need to upgrade, but are provided by external sources and you should follow the standard upgrade procedure of their platform. Note that these products latests versions may be only compatible with the latest available Kiuwan On-Premises core services:

• Kiuwan Jenkins plugin: downloadable from the Jenkins plugin repository.
• Kiuwan Microsoft TFS Azure extension: downloadable through the Azure DevOps marketplace.

Choose this upgrade mode when:

• New versions of Kiuwan On-Premises clients are available.
• You want to upgrade your installation to make your Kiuwan On-Premises servers provide the latest available versions of each client.
• You want to keep your Kiuwan services untouched.

Full mode

The full mode upgrade will upgrade both Kiuwan On-Premises clients and Kiuwan core services.

Keep in mind that when choosing this mode you should always download the latest kiuwan-cluster version available. The latest version is always accessible through this link: https://static.kiuwan.com/download/onpremise/kiuwan-cluster.tar.gz.

Choose this upgrade mode when:

• You want to upgrade your Kiuwan On-Premises clients but your Kiuwan core services version is not compatible with the latests client versions.
• You want to have the latest fixes and features available in Kiuwan.

Upgrade: common steps

Either if you are upgrading only clients or performing a full upgrade, your must follow these steps before starting the upgrade process.

Step 1: backup your current volumes

Just in case an unexpected error occurs during the upgrade process, it is convenient that your backup all your volumes before proceeding.

Your should copy all files under these directories and keep the copy in a safe place:

• [VOLUMES_DIR]/config-shared
• [VOLUMES_DIR]/data-local
• [VOLUMES_DIR]/data-shared

Step 2: check clients upgrade bypass configuration

To make sure that your current configuration is not ignoring new available clients, you should check if "kiuwan.clients.update" is set in the following file:

• [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties

Locate the key "kiuwan.clients.update" at the end of the file and make sure it is set to true:

kiuwan.clients.update=true

When the flag is set to true, all Kiuwan clients will be updated as long as a new version is available.

Step 3: check the status of Kiuwan On-Premises infrastructure

To upgrade Kiuwan On-Premises it is mandatory that at least these elements of the provided (or externalized if you chose to use your own) infrastructure are up and running:

• MySQL
• Redis cluster

If you have run any of the provided scripts that stop this infrastructure elements (or your own instances are stopped if externalized), please make sure you start them before proceding to upgrade.

Upgrade: clients only mode

Note that it is safe to update Kiuwan On-Premises clients WITHOUT stopping any of the provided services or containers, but make sure you have checked the Step 3 of the common steps before proceeding.

Step 1: run the clients upgrade

Open a terminal to your Kiuwan On-Premises host and locate the kiuwan-cluster tool you used to install Kiuwan On-Premises.

Change the directory to where the tool was untared (this directory is referred as [INSTALLER_DIR] in the Kiuwan On-Premises Distributed Installation Guide).

Once the current directory is [INSTALLER_DIR], execute this command:

sudo ./update-clients.sh

Upgrade: full mode

Note that a full upgrade will update your Kiuwan On-Premises clients as well, so there is no need to run the clients upgrade when performing a full upgrade.

This process will stop all Kiuwan services. This means that during the upgrade process:

• Users will not be able to access Kiuwan On-Premises web application.
• Analyses can be still run and will be queued until the new version is available.

Once the upgrade is finished, all services will be automatically restarted and you will be able to access Kiuwan On-Premises after a while.

Step 1: keep your old kiuwan-cluster installer

Your current installer may be needed in order to perform some maintenance tasks. It is usually a better idea to keep your current kiuwan-cluster version just in case you need to access it.

It is enough just to keep the already existing folder where you untared your current kiuwan-cluster as new versions will always be untared to a different folder.

If the old version of kiuwan-cluster is needed through the upgrade process, its path will be refererred to as [INSTALLER_DIR_OLD].

For example, if you are upgrading from Kiuwan On-Premises 2.8.1910.1 to Kiuwan On-Premises 2.8.1910.4, your folders will look like this:

• [INSTALLER_DIR_OLD]: /home/user/kiuwan-cluster_master.265-2.8.1910.1
• [INSTALLER_DIR]: /home/user/kiuwan-cluster_master.473-2.8.1910.4 (you will create this folder in the next steps).

Step 2: download kiuwan-cluster latest version

In order to upgrade to the latest versions of Kiuwan On-Premises images you need to download the latest version of the installation tool. Run this in your Kiuwan On-Premises host:

wget https://static.kiuwan.com/download/onpremise/kiuwan-cluster.tar.gz

This will download the latest available installation tool to the current directory.

Step 3: untar kiuwan-cluster

Once downloaded, you should untar the provided gz file:

tar xvzpf kiuwan-cluster.tar.gz

This will untar the installation tool to a folder with extended version information of the tool. For example:

/home/user/kiuwan-cluster_master.XXXX-2.8.YYMM.V

This folder will be referred to as [INSTALLER_DIR] throughout the following steps.

Step 4: update kiuwan-cluster volumes and user-content configuration

Copy the volumes configuration from the old to the new kiuwan-cluster folders:

cp [INSTALLER_DIR_OLD]/config/volumes.properties [INSTALLER_DIR]/config/volumes.properties

This will configure the volumes location in the new kiuwan-cluster.

Then copy the old user-content folder to the new kiuwan-cluster user-content folder:

cp -r [INSTALLER_DIR_OLD]/user-content [INSTALLER_DIR]/user-content

This will keep track of the latest license and certificates you configured with the previous kiuwan-cluster:

Step 5: check specific upgrade steps

First, identify which Kiuwan On-Premises version you have currently installed. Refer to Checking for updates section for details on how to check it.

The Specific upgrade notes section shows which versions need special upgrade steps.

If your current Kiuwan On-Premises core version needs a special upgrade process, follow the specific upgrade steps for your current Kiuwan On-Premises core version shown in the Specific upgrade notes section.

Step 6: run the upgrade process

NOTE: you should IGNORE this step if you come from a specific upgrade process.

If your current Kiuwan On-Premises core version is not listed in the Specific upgrade notes section, change the directory to [INSTALLER_DIR] and execute this command:

sudo ./update-full.sh

This will run the upgrade process in full mode.

Step 7: load balancer manual configuration (optional)

Kiuwan On-Premises installation tool will not update automatically your load balancer configuration, so changes in this file must be made manually. Refer to the Specific upgrade notes section for information on what changes have been made in this element if you want to keep your installation up to date with the latests features added in the load balancer configuration.

In case you are running the default configuration, you can safely overwrite your configuration, but REMEMBER TO UPDATE "kiuwanDomain" variable to point to your specific Kiuwan On-Premises domain:

cp ./volumes/config-shared/ApacheLoadBalancer/conf/httpd.conf [VOLUMES_DIR]/config-shared/ApacheLoadBalancer/conf/httpd.conf

Once the file has been overwritten, edit it and change this line in [VOLUMES_DIR]/config-shared/ApacheLoadBalancer/conf/httpd.conf:

Define kiuwanDomain kiuwan.onpremise.local

It should point to your specific domain.

Once the configuration changes have been made, you should restart the apacheloadbalancer container:

cd [INSTALLER_DIR]/docker
sudo ./stop-infrastructure.sh apacheloadbalancer
sudo ./start-infrastructure.sh apacheloadbalancer

In case you have externalized the Apache load balancer service, remember to restart it after modifying its configuration.

Checking your Kiuwan On-Premises clients installations after upgrading

Once the update process is finished, all the published clients in your Kiuwan On-Premises installation will be ready to be downloaded. Check the specific client guide to see how to upgrade each client installation:

• Kiuwan Local Analyzer: upgrades automatically when started whenever your Kiuwan On-Premises servers provide a new version to download.
• Kiuwan Engine: upgrades automatically from Kiuwan Local Analyzer, as long as your Kiuwan On-Premises servers provide a new version and your engine is not frozen (see Engine documentation for more information on this topic).
• Kiuwan for developers:
  • Eclipse: check Kiuwan for Developers for Eclipse-based IDEs user guide.
  • JetBrains: check Kiuwan for Developers for JetBrains user guide.
  • Microsoft Visual Studio: check Kiuwan for Developers for Microsoft Visual Studio user guide.
  • Microsoft Visual Studio Code: check Kiuwan for Developers for Microsoft Visual Studio Code user guide.
• Kiuwan Jenkins plugin: check Jenkins plugin user guide.
• Kiuwan TFS extension: check Microsoft TFS-Azure DevOps Extension user guide.

Specific upgrade notes

This section provides information that you may need to follow in case you are upgrading one of these specific versions (see Checking for updates section if you want to check which version is installed in your company):

Upgrading from Kiuwan On-Premises 2.8.1910.1

If you have currently installed Kiuwan On-Premises version 2.8.1910.1, you will need to follow this guide in order to adapt your Kiuwan On-Premises infrastructure to the latest version.

Due to changes in how Redis Cluster is created through the installation process, in order to keep your installation up to date with the latest infrastructure you will need to follow a different approach to perform a full upgrade from this version.

You will need both the kiuwan-cluster version you used to install 2.8.1910.1 and the latest available kiuwan-cluster (that can be downloaded here https://static.kiuwan.com/download/onpremise/kiuwan-cluster.tar.gz). We will refer to this locations:

• [INSTALLER_DIR_OLD]: where the old kiuwan-cluster version was untared.
• [INSTALLER_DIR]: where the new kiuwan-cluster version has been untared.

Note that if you are using AWS elasticache service to run Redis Cluster services you can ignore this process and follow the standard upgrade process.

Step 1: wait for all enqueued analyses to end

Step 2: stop kiuwan services

Change the current directory to the old kiuwan-cluster docker scripts and stop all the Kiuwan On-Premises services:

cd [INSTALLER_DIR_OLD]/docker
sudo ./stop-kiuwan.sh

This will stop all Kiuwan frontal, analyzer and schedulers containers currently running.

Step 3: update your current configuration

In order to update the current Kiuwan On-Premises clients and your volumes global configuration file, you should run the update script located in the new kiuwan-cluster:

cd [INSTALLER_DIR]/docker
sudo ./update.sh

Step 4: stop remaining containers and prune

Pruning containers is needed to safely upgrade from this version. To do so, run the uninstall.sh script from the new kiuwan-cluster installation directory.

Note that this step will NOT remove any data from your current installation:

cd [INSTALLER_DIR]
sudo ./uninstall.sh

Step 5: clean Redis cluster data

Redis Cluster current data must be cleaned up in order to start a new fresh cluster. Run the following command:

sudo rm -rf [VOLUMES_DIR]/data-local/Redis/data

Step 6: update Redis cluster node information

Redis Cluster default configuration has been changed in the following versions of Kiuwan On-Premises. If you are running the provided service you will need to update the Redis Cluster nodes locations.

Edit the global configuration file:

sudo vim [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties

You must change properties "redis.cache.nodes" and "redis.store.nodes" to these values:

redis.cache.nodes=172.17.0.1:6379,172.17.0.1:6380,172.17.0.1:6381,172.17.0.1:6382,172.17.0.1:6383,172.17.0.1:6384
redis.store.nodes=172.17.0.1:6379,172.17.0.1:6380,172.17.0.1:6381,172.17.0.1:6382,172.17.0.1:6383,172.17.0.1:6384

If you need to update any other configuration property, you can modify now any other configuration option. Changes will be taken into account.

Step 8: run the install script for the new version

Running the installation script will recreate the new Redis Cluster and start all needed services:

cd [INSTALL_DIR]
sudo ./install.sh

Step 9: continue with full upgrade steps

You can now continue with the standard upgrade process.