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.
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:
|Kiuwan Core||Kiuwan On-Premises itself. This is the image version of your Kiuwan containers (front, analyzer and scheduler nodes).|
|Kiuwan Clients||Kiuwan On-Premises clients. These are the clients provided along with your current Kiuwan On-Premises installation. Sometimes clients may be updated without the need of a full Kiuwan On-Premises upgrade that includes Kiuwan Core. See Upgrade: clients only mode section for more information.|
|Installed version||This column shows the version name of the current installed versions (both for Kiuwan core and clients).|
|Last available version||This column shows the latest available version of Kiuwan core and clients.|
|Status||When a new version is detected this column will indicate that an upgrade is available.|
|Minimum Kiuwan On-Premises version needed to upgrade clients||If your current Kiuwan Core version is less than this version, new versions of Kiuwan On-Premises clients will not be available for your installation anymore. If you want to upgrade, it is mandatory to perform a full upgrade. See Upgrade: full mode section for more information.|
You can also check your current Kiuwan On-Premises core version by running this command on a Kiuwan front instance host:
You can upgrade only Kiuwan On-Premises clients or perform a full upgrade to your Kiuwan On-Premises installation.
Both clients only and full modes will update changes made in the current configuration that have not been already applied, but keep in mind that new configuration properties will only be available after performing a full upgrade. Default configuration values will be used when starting a new version of Kiuwan services.
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.
Do not mix up what a Kiuwan On-Premises client version is. These are different concepts:
Kiuwan On-Premises clients are those Kiuwan products that your Kiuwan On-Premises servers will provide to your users:
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:
Choose this upgrade mode when:
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 can directly update your Kiuwan On-Premises installation guide from any version to the latest available version.
Either if you are upgrading only clients or performing a full upgrade, your must follow these steps before starting the upgrade process.
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:
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:
Locate the key "kiuwan.clients.update" at the end of the file and make sure it is set to true:
When the flag is set to true, all Kiuwan clients will be updated as long as a new version is available.
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:
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.
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.
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:
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:
Once the upgrade is finished, all services will be automatically restarted and you will be able to access Kiuwan On-Premises after a while.
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, your folders will look like this:
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:
This will download the latest available installation tool to the current directory.
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:
This folder will be referred to as [INSTALLER_DIR] throughout the following steps.
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]
This will keep track of the latest license and certificates you configured with the previous kiuwan-cluster:
This step is needed just in case you installed your old Kiuwan On-Premises version not meeting the needed minimum requirements for the needed tools (check Installation requirements section for a complete list of required tools).
In order for the upgrade process to work, the minimum tool versions requirements must be met.
Run the following script and check the "Checking commands" section:
cd [INSTALLER_DIR] sudo ./check-prerequisites.sh
In case you see that the command versions requirements are not met (either because a command is not available or because its version is not supported), please update your system until the marked requirements are met.
|You need only to check the "Checking command" section. It is OK if you see that some of the ports or the docker network are in use, as at this point your Kiuwan On-Premises services should be still running.|
You can run the check-prerequisites tool as many times as needed.
Do not continue to the next step until all TOOL VERSIONS requirements are met or your Kiuwan On-Premises installation stability could be compromised.
First, identify which Kiuwan On-Premises version you have currently installed. Refer to Checking for new versions section for details on how to check it.
The Specific version upgrade notes page 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 version upgrade notes page.
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 version upgrade notes page, change the directory to [INSTALLER_DIR] and execute this command:
This will run the upgrade process in full mode.
Kiuwan On-Premises installation tool will not update automatically your load balancer configuration, so changes in this file must be made manually. Refer to thepage 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.
|Note that this is an optional step. If you are happy with your current configuration or you want to mantain your own custom configuration, you can safely ignore it.|
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.
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: