Migrating PostgreSQL repositories

Migrating from Bundled PostgreSQL 13 to the installed PostgreSQL 16

Perform the following manual steps after completing both Kyvos Manager and Kyvos upgrades.

1. Pre-Migration Checks

   1. If Kyvos Manager and Kyvos are using heterogeneous repositories (e.g., one external and one bundled):

      • The component using an external repository must first be moved to a bundled repository.

      • For the Kyvos repository, switch to the bundled repository for migration.

      • For Kyvos Manager repository, perform the migration manually, including updating the jdbc.properties file.

   2. Disable PostgreSQL Component HA (High Availability) by removing all Standby PostgreSQL roles if HA is enabled in the cluster.

   3. Migrate PostgreSQL Role and ensure the PostgreSQL master role is present on the Kyvos Manager node.

   4. Reset Repository Passwords from the Kyvos Manager. Reset both Kyvos Manager repository and Kyvos repository passwords to their default values (if not already set to defaults).

2. Stop Services

   1. Stop cluster services from the Kyvos Manager.

   2. Stop the Kyvos Manager service.

3. Export existing Database Dumps

   1. From the node where the bundled PostgreSQL service is running (default: KM node), export separate database dumps for:

      1. Kyvos Manager database: kmrepo

      2. Kyvos databases: delverepo and usagerepo

4. Install PostgreSQL 16

   1. Stop the bundled PostgreSQL service on the node.

   2. Install PostgreSQL 16 on the same node (default: KM node) by running the installation shell configure-postgres16.sh script. You must execute this script using sudo or root privileges. This script automatically starts the PostgreSQL 16 service. Ensure the bundled PostgreSQL service is stopped before running the installation script and verify that the new PostgreSQL 16 service is running successfully

   3. Verify that the database names, usernames, passwords, and ports for the new PostgreSQL 16 service match those used in the bundled PostgreSQL setup.

5. Import Database Dumps: Import the previously exported kmrepo, delverepo, and usagerepo dumps into the installed PostgreSQL 16 databases.

6. TLS Configuration (If Applicable): If TLS is enabled in the deployed cluster using the bundled PostgreSQL, perform the following steps:

   1. Copy the certificate files server.crt and server.key from <bundled_pg_base_path>/postgres/data/ to <installed_pg_data_dir> to the data directory of the installed PostgreSQL.

   2. Change ownership using sudo chown postgres:postgres /var/lib/pgsql/data/<file-name>.

   3. Enable SSL in postgresql.conf: ssl=on

   4. Update the following properties in postgresql.conf:

      ssl_cert_file = '<certificate_file_name>' ssl_key_file = '<key_file_name>'

   5. Restart the installed PostgreSQL 16 service after making the above changes.

7. Update the Kyvos Manager jdbc.properties file with:

   installedRepo=true repoInstallationDataDirPathPrefix=/var/lib/pgsql

8. On the KM node, modify the file <KYVOS_INSTALL_PATH>/kyvosmanageragent/conf/services/Kyvos.xml In the file, change <type>pid</type> to <type>ps</type> for the PostgreSQL service.

9. Start Kyvos Manager.

10. Update POSTGRESS_INSTALLATION_TYPE=INSTALLED in kyvos-pg-back.sh located at kyvos/postgres/bin (ideally on each node, at least on KM node)

    (Apply on all nodes, at least on the KM node.)

11. Update postgres version as 16.9 in DemoDBRepository.xml

12. Push the following snapshots:

    • BI Connection configuration

    • Kyvos Manager data

    • disaster-recovery.sh

13. Optional: Change Repository Passwords: If required, update the repository passwords for both Kyvos Manager and Kyvos repositories (from their default values set in Step 1) through the Kyvos Manager.

Migrating from Installed PostgreSQL 16 to Bundled PostgreSQL 13

The following procedure describes the steps required to migrate Kyvos Manager (KM) and Kyvos repositories from an installed PostgreSQL 16 service to the bundled PostgreSQL 13 service.

1. Stop Cluster Services

   1. From the Kyvos Manager UI, stop all cluster services.

   2. If not already set, change the KM repository and Kyvos repository passwords to their default values using the Kyvos Manager UI.

   3. Stop the Kyvos Manager service.

2. Export Database Dumps.

3. From the Kyvos Manager node (where the installed PostgreSQL 16 service is running), export separate database dumps for:

   • Kyvos Manager repository (kmrepo)

   • Kyvos repositories (delverepo and usagerepo)

4. Use the pg_dump command with a PostgreSQL version up to 16.9 to create the dumps.
   Note: Do not use pg_dump version 16.10 or above, as it introduces unsupported entries (\restrict and \unrestrict) in the dump file. If such entries exist, remove them manually before proceeding.

5. Stop Installed PostgreSQL and Start Bundled PostgreSQL

   1. Stop the installed PostgreSQL 16 service on the KM node.

   2. Start the bundled PostgreSQL 13 service on the KM node.

6. Verify Repository Configuration: Ensure that the following parameters for bundled PostgreSQL match those of the installed PostgreSQL service for all repositories (kmrepo, delverepo, etc.):

   1. Username

   2. Password

   3. Port

   4. Database name
      If any of these values differ, update them to match the configuration of the installed PostgreSQL instance.

7. Modify Dump Files for Compatibility: Before importing, modify the exported dump files to ensure PostgreSQL 13 compatibility. See the Refer to the Switch Repository Dump section in the Kyvos documentation for detailed instructions on compatible dump preparation.

8. Remove unsupported parameters such as: LOCALE_PROVIDER = libc

9. Import the modified Kyvos Manager and Kyvos database dumps into the respective databases of the bundled PostgreSQL 13 service.

10. TLS Configuration (If Applicable): If TLS is enabled in the deployed cluster using the installed PostgreSQL, perform the following steps to reconfigure TLS for the bundled PostgreSQL:

    1. Copy the certificate files server.crt and server.key from <installed_pg_data_dir> to <bundled_pg_base_path>/postgres/data/ to reconfigure TLS for the bundled PostgreSQL:

    2. Change ownership of these files to the Kyvos cluster deployment user using sudo chown <kyvos_user>:<kyvos_user> <file_name>

    3. Enable SSL in the bundled PostgreSQL configuration file (postgresql.conf)

    4. Update the following properties in postgresql.conf:

       ssl_cert_file = '<certificate_file_name>' ssl_key_file = '<key_file_name>'

11. Restart the bundled PostgreSQL service after making the above changes.

12. Update the Kyvos Manager jdbc.properties file as follows: installedRepo=false

13. Ensure all bundled PostgreSQL group-related properties are correctly updated, particularly: homePathBundledRepo=/data/kyvos/app/postgres/

1. On the KM node, update the <KYVOS_INSTALL_PATH>/kyvosmanageragent/conf/services/Kyvos.xml file. In the file, change <type>ps</type> to <type>pid</type> for the PostgreSQL service. If the parameter pidFile is not already present, add it under the PostgreSQL service section:

   <param> <name>pidFile</name> <value>/data/kyvos/app/kyvos/postgres/data/postmaster.pid</value> </param>

   Here, <KYVOS_INSTALL_PATH> is /data/kyvos/app/.

2. Stop the bundled PostgreSQL service if it is already running, to ensure clean configuration reload.

3. Start the Kyvos Manager service.

4. In the kyvos/postgres/bin/kyvos-pg-back.sh file, update the parameter, POSTGRESS_INSTALLATION_TYPE=BUNDLED. Apply on all nodes, or at least on the Kyvos Manager node.

5. In the DemoDBRepository.xml file, update the PostgreSQL version to 13.

6. Push the following snapshots from Kyvos Manager:

   • BI Connection configuration

   • Kyvos Manager data

   • disaster-recovery.sh

7. Post-Migration Step: If required, update the Kyvos Manager repository and Kyvos repository passwords from their default values (set earlier in Step 1) using the Kyvos Manager.