Version:

Upgrade

Upgrading to Kinetica 7.1 is facilitated through the use of KAgent. KAgent 7.1 provides the ability to upgrade existing Kinetica clusters managed by KAgent 7.0 or clusters that are not managed at all.

Upgrading requires the system be Kinetica 7.0.11 or newer. If running Kinetica 6.2 or a 7.0 version prior to that, refer to the Kinetica 7.0 Upgrade instructions for details on upgrading to a 7.0.11 or newer version first, and then refer back to this guide to complete the upgrade to version 7.1.

Migration Guide

See Migrating to Kinetica 7.1 for considerations that should be made before deciding to upgrade.

Pre-Upgrade Actions

Before upgrading to Kinetica 7.1 perform the following checks & tasks to ensure the system is ready to be upgraded.

Checks

  • Ensure that the system being upgraded is Kinetica 7.0.11 or later.

  • Ensure that 8GB of disk space is available on the directory mount used for installation on each node.

  • Ensure that there is a shared file system used by all nodes for persistence of database objects if cluster resiliency is to be activated in the upgraded system.

    Important

    Cluster resiliency can only be enabled within a cluster during the upgrade process--it cannot be turned on afterwards. However, a new installation can always be configured with cluster resiliency and the data from an existing system migrated to it, using either cloning or backup/restore.

  • If performing an offline upgrade, ensure that all installation packages are available to the machine initiating the upgrade (the one that will log into KAgent and kick off the installation).

Tasks

  • Back up data & configuration files.

  • If AAW is being used, terminate all ingests and deployed models.

  • Identify hosts on which etcd, a new Kinetica 7.1 configuration management component, will be installed. Ensure that port 9049 is open on any hosts targeted for etcd installation.

    • If HA is already enabled across the existing clusters, it is recommended that etcd be co-located with the existing RabbitMQ hosts.
    • If HA is not enabled, one or more hosts should be targeted for etcd installation.

    Important

    An odd number of etcd instances must be associated with each KAgent instance, regardless of how many clusters and/or rings are being managed by that KAgent. KAgent will verify, during each cluster upgrade, that the total number of etcd instances known to that KAgent remains odd.

    For example, given a KAgent managing 3 rings of 2 clusters each:

    • The first cluster of the first ring can be upgraded with 1 etcd node, bringing the total etcd instances managed by that KAgent to 1.
    • The second cluster of the first ring and the first cluster of the second ring can be upgraded with no etcd nodes, leaving the total etcd instances managed by KAgent at 1.
    • The second cluster of the second ring can be upgraded with 2 etcd nodes, bringing the total etcd instances managed by that KAgent to 3.
    • The first cluster of the third ring can be upgraded with no etcd nodes, leaving the total etcd instances managed by KAgent at 3.
    • The second cluster of the third ring can lastly be upgraded with 2 etcd nodes, bringing the final total of etcd instances managed by KAgent to 5.

    Even though etcd instances must be odd per KAgent across all clusters & rings, the number must remain odd after each individual cluster is upgraded.

Upgrade Actions

The only path for upgrading Kinetica 7.0 is the Standard Upgrade, which is for upgrading existing clusters in place; can also be used to upgrade Azure clusters where cluster resiliency is not needed.

Standard Upgrade

If upgrading an on-premise Kinetica ring or one hosted in AWS or GCP, the ring can be upgraded in place. This method can also be used to upgrade an Azure ring if not intending to use the cluster resiliency feature.

The standard upgrade path is dependent upon whether the Kinetica 7.0 cluster is currently being managed by KAgent.

Managed Cluster Upgrade

If the cluster to upgrade is already managed by KAgent 7.0, upgrade KAgent to version 7.1, and then upgrade the cluster.

  1. Upgrade KAgent.

    KAgent can be upgraded in place, whether it resides on a server inside or outside the cluster. After copying the KAgent package to the server hosting KAgent, upgrade the package using the standard procedures for a local package:

    1. Stop the current KAgent process:

      service kagent stop
      
    2. Upgrade the KAgent application based on host operating system:

      • RHEL

        sudo yum upgrade ./kagent-<version>.<architecture>.rpm
        
      • Debian/Ubuntu

        sudo apt upgrade ./kagent-<version>.<architecture>.deb
        

    This upgrades the package in the directory /opt/gpudb/kagent and starts the kagent_ui service.

  2. Start KAgent.

    ../_images/kagent_start.png

    To access the KAgent UI:

    1. Ensure the KAgent service is started:

      service kagent_ui status
      
    2. Browse to the KAgent application using IP or host name:

      http://<kagent-host>:8081/kagent
      
    3. If KAgent is associated with one or more Kinetica clusters, log in using the credentials for that cluster. If KAgent has not been associated with any clusters yet, the application will load without prompting.

  3. Click Upgrade Ring.

  4. For each ring to upgrade, click Upgrade on that ring, and follow these steps to upgrade the ring:

    1. Confirm that all tasks under Tasks have been performed, then check the checkboxes and click Start.
    2. Identify hosts on which etcd will be installed, then click Next.
    3. If performing an offline upgrade, upload all the Kinetica 7.1 install packages. When done, or if performing an online upgrade, click Next.
    4. Click Upgrade and then click Yes to begin the Kinetica 7.1 upgrade process.
    5. Click Close when the upgrade is complete.

Unmanaged Cluster Upgrade

If the cluster to upgrade is not managed by KAgent 7.0, install KAgent 7.1, add the cluster, and upgrade it to 7.1.

  1. Install KAgent.

    KAgent can be deployed as a RHEL or Debian/Ubuntu installation package on any server inside or outside the cluster. After copying the KAgent package to the target server, deploy it using the standard procedures for a local package:

    • On RHEL:

      sudo yum install ./kagent-<version>.<architecture>.rpm
      
    • On Debian/Ubuntu:

      sudo apt install ./kagent-<version>.<architecture>.deb
      

    This installs the package to the directory /opt/gpudb/kagent and registers and starts the kagent_ui service. KAgent will open port 8081 on the local firewall (if enabled).

  2. Start KAgent.

    ../_images/kagent_start.png

    To access the KAgent UI:

    1. Ensure the KAgent service is started:

      service kagent_ui status
      
    2. Browse to the KAgent application using IP or host name:

      http://<kagent-host>:8081/kagent
      
    3. If KAgent is associated with one or more Kinetica clusters, log in using the credentials for that cluster. If KAgent has not been associated with any clusters yet, the application will load without prompting.

  3. Add the cluster to upgrade to KAgent, choosing the on-premise deployment method, regardless of the way in which the cluster is actually provisioned.

  4. For each additional cluster to upgrade:

    1. Click + Cluster
    2. Add the cluster to upgrade to KAgent, choosing the on-premise deployment method
  5. Click Rings at the top of the page.

  6. Click Upgrade on the ring to upgrade to Kinetica 7.1

  7. If performing an offline upgrade, upload all the Kinetica 7.1 install packages. When done, or if performing an online upgrade, click Upgrade and then click Yes to begin the Kinetica 7.1 upgrade process.

Post-Upgrade Actions

Upgrading Database Clients

All native API clients and ODBC/JDBC drivers will need to be updated to be compatible with the database.

Native APIs

The instructions for upgrading to the latest APIs can be found in their respective manuals:

ODBC/JDBC

ODBC & JDBC drivers and related configuration will need to be updated.

Note

If using the Windows ODBC driver, be sure to remove older versions of the driver before installing new ones.

Remove Previous Windows ODBC Drivers

To remove the old drivers:

  1. Launch ODBC Data Source Administrator (64-bit or 32-bit, as needed).
  2. Select any entry with a Driver name of Kinetica ODBC Driver.
  3. Optionally, click the Configure button to open up the driver properties window and record any settings that could be reused with the new driver (username, SSL Certificate path, etc.).
  4. Click the Remove button.
  5. Click the Yes button to confirm the removal.
  6. Repeat this process until all older drivers have been removed.
Install New ODBC/JDBC Drivers

The latest ODBC & JDBC clients and related configuration can be found here:

Note

The database connection parameter values have changed, so be sure to update both the ODBC/JDBC clients and their configurations.