Applies to: 
Kyvos Enterprise Kyvos Cloud (SaaS on AWS) 
Kyvos AWS Marketplace
Kyvos Azure Marketplace Kyvos GCP Marketplace Kyvos Single Node Installation (Kyvos SNI)
This section provides information to upgrade and rollback Kyvos Manager.
Note
From the Kyvos 2023.1 release onwards, the Derby repository will no longer be supported for Kyvos Manager. The only supported repository will be Postgres (either bundled or external).
In a fresh deployment using the Kyvos 2023.1 release, Postgres will be used as the default repository for Kyvos Manager. However, in cases where older releases were used to deploy the cluster, an upgrade will be mandatory to migrate from Derby to Postgres as the repository for Kyvos Manager.
If your environment has enhanced security, the managed identity must be granted 'joinViaServiceEndpoint/action' permission with the scope set to the virtual network in which Kyvos is running.
Pre-upgrade verification
Important for RHEL 8.6 and TLS
Please make sure you have moved or renamed the openssl.cnf file placed at /etc/pki/tls/ location only on Kyvos Manager and the node where Postgres Service is running to another location.
Creating backup
To upgrade the Kyvos Manager to a newer version, you must first create a backup of your existing Kyvos Manager environment.
To create a backup for the Kyvos Manager data, perform the following steps.
Log in to Kyvos Manager machine through the terminal.
Navigate to the Kyvos Manager installation path.
Stop the Kyvos Manager process using the command:
./kyvosmanager/bin/stop-km.shIdentify the location for the used kyvosmanagerdata folder. For this, check the value of KM_DATA_DIR in the set env.sh file in the bin folder.
This folder contains the Kyvos Manager data including the repository.Go to parent folder of the kyvosmanagerdata folder and run the command.
tar -zcvf file_name.tar.gz kyvosmanagerdata
Here file_name is the user backup file name for the Kyvos Manager.Copy the backup file to the local machine.
Rename your current repo folder at the kyvosmanagerdata/server location, such as repo_<oldversion number>. For example, you can name it repo_2020.5.
Upgrade Kyvos Manager from the portal
On the navigation pane, click Application Update > Upgrade.
On the Upgrade Kyvos Manager page, provide the information as:
To see upgrade history, click the Actions menu (...) and select the View History option.
Manually upgrading Kyvos Manager
To upgrade Kyvos to a new version, perform the following steps.
If not stopped already, stop Kyvos Manager from the terminal using the following command.
./kyvosmanager/bin/stop-km.sh
Copy the new Kyvos Manager setup on the machine parallel to the older version of Kyvos Manager is installed.
For this:Log in to the machine using the credentials of the user, which were used for installing the previous version.
Download the setup from the FTP site to the location where you need to install it. For example, /data/kyvosXXXX.YY/
For the older version of Kyvos Manager, we assume:
Installation directory is located at /data/kyvos
Kyvos Manager home directory is located at /data/kyvos/kyvosmanager
Data directory is located at /data/kyvos/kyvosmanagerdata
Extract the Kyvos Manager bundle using the following command:
tar -xvf KyvosManager<version>_ux64.tar.gz
You will get a folder named kyvosmanager_war.Make the following configurations in the setenv.sh file located at $KM_HOME/kyvosmanager_war/kyvosmanager/bin/
Set absolute paths for the following variables, as shown in the examples.
KM_BASE_DIR: Should point to the kyvosmanager_war folder.
KM_DATA_DIR: Should point to kyvosmanagerdata folder of the older installation.
Example: KM_DATA_DIR=/data/kyvosmanager_war/kyvosmanagerdata/JRE_HOME: Should point to the JRE folder in the kayvosmanager_war folder.
Example: /data/kyvosmanager_war/jre/
Copy all the contents of the kyvosmanager_war/kyvosmanagerdata/server/repo/ folder to the KM_DATA_DIR/server/ location.
Ensure that you copy ALL the contents of the repo folder i.e., the Kyvos bundle and the metadata.Kyvos folder.
Merge the contents of your existing conf/kyvosanager.properties file to the conf/kyvosanager.properties of the new version.
Copy the contents of the kyvosmanager_war/kyvosmanagerdata/server/repo/ folder to the KM_DATA_DIR/server/ location.
Start Kyvos Manager from the terminal using the command:
cd
kyvosmanager_war/kyvosmanager/bin
./start-km.sh
Login to Kyvos Manager and check the version from the About page to verify a successful upgrade.
The Kyvos Manager cluster dashboard displays a warning message, prompting you to upgrade your Kyvos version. Click Upgrade. Now you can upgrade Kyvos .
Kyvos Manager Tomcat Server logs
From Kyvos 2023.3 onwards, logs of Kyvos Manager Tomcat Server will be located in the kyvosmanagerdata/server/tomcatLogs path.
Note
Kyvos Manager Tomcat Server logs will be generated in the kyvosmanagerdata/server/tomcatLogs location even after upgrading the Kyvos Manager version.
Upgrade Kyvos Manager in Azure
Note
Applicable only when current Kyvos Manager is using the Single server.
For Kyvos Manager, ensure that you use ARM template (FlexibleServerKyvosManagerRepository and FlexibleServerKyvosRepository) for the Flexible Server instance creation. You can also refer to the https://kyvosdocumentation.atlassian.net/wiki/spaces/KD20242/pages/69408878/Creating+ARM+Template+for+Automated+Azure+Deployment#FlexibleServer section.
Any user running in Kyvos Manager build before 2023.1 first needs to upgrade to any version, such as 2023.1, lower than 2023.5 so that the Kyvos Manager database Derby first gets migrated to Postgres as the Kyvos Manager repository.
First you need to upgrade both Kyvos Manager and Kyvos. After upgrading them, you need to migrate repository from Single Server to Flexible Server.
Important
Using the same external repository instance is not recommended/certified for Kyvos Manager & Kyvos both. Cluster scheduling with non-shared repo will cause the DB instance to go down; thus, the Kyvos Manager will not work properly.
If the same repository instance is used, then the database for Kyvos Manager and Kyvos must be different.
The default database name for:Kyvos is delverepo.
Kyvos Manager is kmrepo.
If any time the same external repository instance gets configured in Kyvos Manager and Kyvos. In that case, ensure that on the Switch Repository page of Kyvos Manager, the Shared repository is checked and configuration is saved.
Post-upgrade steps
Redeploying Zookeeper
Important
To upgrade to the latest version of Zookeeper, switching to managed Zookeeper is mandatory.
After redeploying Managed Zookeeper, you must restart Kyvos services.
If you are upgrading both Kyvos Manager and Kyvos using either the single click upgrade or the All components upgrade, you must redeploy Zookeeper after upgrading Kyvos Manager.
If you're currently using the default Zookeeper on the Kyvos Manager node, you'll need to redeploy the ZooKeeper. This applies to any cluster deployed before the managed Zookeeper implementation and still uses the default Zookeeper on the Kyvos Manager node.
When upgrading to a release where the supported version of Managed Zookeeper is changing, an undeploy/deploy activity for Managed Zookeeper will be required post-upgrade.
From Kyvos Release | To any Kyvos Release up to | Supported Managed Zookeeper version |
2021.2 | 2023.1.x | 3.6.1 |
2023.2 | 2024.1.2 | 3.7.1 |
2024.1.3 | Till Date (i.e. 2024.2) | 3.8.4 |
This is a one-time activity that is required only when upgrading from a prior release using older Managed ZooKeeper version to a Kyvos release which is using the newer version of Managed Zookeeper. For example, if you upgrade from release prior to Kyvos 2023.2 to a release up to Kyvos 2024.1.2 (i.e., when Zookeeper version 3.6.1 was in use and now 3.7.1 is supported).
You must redeploy the Zookeeper using the Zookeeper configuration page in Kyvos Manager to switch to the latest version of Zookeeper. This is necessary for cloud deployments (AWS, GCP, and Azure) and on-prem deployments to remove the previous version of Zookeeper.
Upgrading Zookeeper version
Log onto the Kyvos Manager and navigate to Kyvos and Ecosystem > Zookeeper.
Here, select the External option and click the Save It will undeploy Zookeeper.
Once Zookeeper undeployment is complete, select the Managed by Kyvos option and click the Save This will trigger the deploy Zookeeper operation.
Once Zookeeper deployment is complete, restart all Kyvos services from the Dashboard.
Switching to the previous version of Zookeeper
To access the previous version of the Zookeeper, perform the following steps.
Add the previous Zookeeper version bundle to the Kyvos Manager repository at kyvosmanagerdata/server/repo/ .
Take a backup of the new version 3.7.1 bundle of Zookeeper at a different location outside the Kyvos Manager repo. This bundle will be necessary for switching to the new version 3.7.1 of Zookeeper.
Update the previous version bundle name in the supportedBundles present in the kyvosmanagerdata/server/repo/metadata.Kyvos/zookeeper.json file by deleting the new zookeeper version bundle name and then redeploy the Zookeeper to restore managed Zookeeper to version 3.6.1.
For example, to switch to Zookeeper version 3.6.1, before uninstalling the Zookeeper, a key having a value like supportedBundles : [zookeeper-3.7.1.tar.gz] must be updated with supportedBundles : [zookeeper-3.6.1.tar.gz]
Switching to the default non-managed version of Zookeeper
To restore the default non-managed version of Zookeeper on the Kyvos Manager node, which was removed during the uninstallation of Managed Zookeeper, you will need to manually install Zookeeper on the Kyvos Manager node.
Upgrade Graviton JRE for AWS cluster
To upgrade the Graviton JRE version, perform the following post-upgrade steps.
Create a fresh automated Graviton-based AWS cluster on the Kyvos 2023.1.1 release that contains Kyvos Manager JRE version as Corretto-8.362.08.1
Upgrade Kyvos Manager to Kyvos 2023.2, which contains Kyvos Manager JRE version as Corretto-17.0.7.7.1.
Execute the following command to download the JRE 17.0.7.7.1
curl -o manual_node_creation_graviton_prereq.tar.gz https://s3.amazonaws.com/us-east-1.kyvos/2023.2/latest/prereq/manual_node_creation_graviton_prereq.tar.gzDelete the JRE that is already existing in the following path:
For example, /data/kyvos/installs/kyvosmanager_releases/KyvosManager2023.2War_ux64/kyvosmanager_war/jre/Untar the downloaded tar file and place it on the following path of the Kyvos Manager node:
For example, /data/kyvos/installs/kyvosmanager_releases/KyvosManager2023.2War_ux64/kyvosmanager_war/jre/Start the Kyvos Manager services from the following path.
For example, /data/kyvos/installs/kyvosmanager_releases/KyvosManager2023.2War_ux64/kyvosmanager_war/kyvosmanager/binAfter completing the steps, the Kyvos Manager application will be up and running.
Rollback Kyvos Manager
You can only roll back to an older version of the Kyvos Manager using manual steps, as there is no rollback option for the Kyvos Manager on the UI.
Important
From Kyvos 2024.2 onwards, If Kyvos Reporting Service is deployed and you want to roll back the Kyvos Manager release earlier to 2024.2, then before performing Kyvos Manager rollback, you must remove Kyvos Reporting Service.
From Kyvos 2023.3 onwards, logs of Kyvos Manager Tomcat Server will be generated in the kyvosmanagerdata/server/tomcatLogs path. If you rollback Kyvos Manager to an older version, logs will be generated inside the kyvosmanager_war/kyvosmanager/logs/ folder of the Kyvos Manager on which the rollback was performed.
In case of a Rollback, the previous state of Kyvos Manager is restored. In case you made any changes that you need in the previous state, you need to perform them again.
To roll back to a previous version, perform the following steps.
Create a backup for the Kyvos Manager data, and perform the following steps.
Log in to the Kyvos Manager machine through the terminal.
Navigate to the Kyvos Manager installation path.
Stop the Kyvos Manager process using the command:
./kyvosmanager_war/kyvosmanager/bin/stop-km.shIdentify the location for the used kyvosmanagerdata folder. For this, check the value of KM_DATA_DIR in the set env.sh file in the bin folder.
This folder contains the Kyvos Manager data, including the repository.Go to the parent folder of the kyvosmanagerdata folder and run the command.
tar -zcvf file_name.tar.gz kyvosmanagerdata
Here file_name is the user backup file name for the Kyvos Manager.Copy the backup file to the local machine.
Rename your current repo folder at the kyvosmanagerdata/server location, such as repo_<current version number>. For example, you can rename it repo_2022.1
Locate the version to which you want to roll back (for example, 2021.1), and rename its repo folder (such as repo_2021.1) to repo.
Locate the build folder of the Kyvos Manager version to which you want to roll back (for example, 2021.1), and verify the correct value of KM_DATA_DIR in the set env.sh file in the bin folder.
Start the required version of Kyvos Manager using the command:
./kyvosmanager_war/kyvosmanager/bin/start-km.sh
Note
If your cluster node password was updated or the encryption algorithm changed using Kyvos Manager 2021.2 onwards, then on rollback of Kyvos Manager to any build previous to version 2021.2, you need to reconfigure the c luster node password.
Kyvos Manager Rollback to previous releases not supporting Flexible Server
Kyvos Manager rollback to earlier releases (prior to the Kyvos 2023.5 releases that are not supporting Flexible server) when Kyvos Manager using external repository.
It could be:
Kyvos Manager rollback to a release supporting Bundled Postgres: To migrate from external repository to bundled Postgres, see the https://kyvosdocumentation.atlassian.net/wiki/spaces/KD20242/pages/69412793/Configuring+jdbc.properties+for+Kyvos+Manager#External-Repository-to-Bundles-Postgres section.
Kyvos Manager rollback to a release supporting Azure Single Server: To migrate from Flexible Server to Single Server, see the https://kyvosdocumentation.atlassian.net/wiki/spaces/KD20242/pages/69412793/Configuring+jdbc.properties+for+Kyvos+Manager#Flexible-Server-to-Single-Server section.
Post-rollback steps
If you have rolled back from 2022.1 or above, and you updated the password or encryption algorithm (feature introduced in version 2022.1), then you need to reconfigure the c luster node password on to the previous Kyvos Manager release.
Note
If rollback is done to a version before Kyvos 2021.3, then the AWS functions will not be rolled back. You need to manually perform the rollback for these.
Manual steps required to roll back to the previous version:
Go to Lambda.
Click on the Function in which you want to update the lambda JAR.
Go to Code source.
Upload kyvoslambda.jar, available at your S3 location for the installation folder. Alternatively, provide the path of the JAR file, such as s3://us-east-1.kyvos/2021.2/latest/
Performing skip upgrade of Kyvos Manager
From Kyvos 2024.1 onwards, there are manual steps required when performing skip upgrade of Kyvos Manager. This is only necessary when upgrading Kyvos Manager from a release earlier than 2023.1 (i.e. when the Kyvos Manager build uses Derby as the repository) to any release 2024.1 or later.
To perform skip upgrade of Kyvos Manager for the previous releases, perform the following steps.
After the Kyvos Manager upgrade (from release earlier to 2023.1) to any release 2024.1 or onwards, a new version of Kyvos Manager will not start.
Note
The login page will not appear and the following error message will be displayed.
Stop the new version of Kyvos Manager from its current home path using bin/stop-km.sh.
Copy the existing Derby jar from the earlier running version of Kyvos Manager from path kyvosmanager/webapps/kyvosmanager/WEB-INF/lib/ to the latest running version of Kyvos Manager at the same path.
Start the latest Kyvos Manager using the start-km.sh command.
After logging in, you will be redirected to the Kyvos Manager repository database migration to perform the Kyvos Manager database migration from Derby to Postgres.
Once the database migration is completed, ensure that Kyvos Manager is restarted.
Note
You don't need to manually remove the Derby jar from the latest kyvosmanager/webapps/kyvosmanager/WEB-INF/lib/ folder. This is because it's automatically migrated after the database migration. Moreover, the Derby jar has vulnerabilities, therefore Kyvos Manager will delete it from the lib folder.