Version:

Upgrading Kinetica with KAgent (On Premise)

Any version of Kinetica can be upgraded to the latest version using KAgent. KAgent will manage upgrading every node in a cluster as well as any configuration file merging.

Warning

See the Migrating to Kinetica 7.0 for considerations that should be made before upgrading.

Back Up

  1. Stop Kinetica from the head node:

    service gpudb_host_manager stop
    
  2. Verify that Kinetica is stopped:

    service gpudb_host_manager status
    
  3. On the head node, create a backup file (.bak) or a tar file (.tar.gz) for all important configuration files and directories, including:

    • All persist directories--the default being /opt/gpudb/persist-- defined in the gpudb.conf file (backing up these directories is optional, especially if the disk space is not available)
    • Everything in the /opt/gpudb/core/etc directory
    • Everything in the /opt/gpudb/httpd/conf directory
    • Everything in the /opt/gpudb/connectors directory
    • The /opt/gpudb/tomcat/conf/catalina.properties file
    • The /opt/gpudb/tomcat/webapps/gadmin/WEB-INF/classes/gaia.properties file
  4. On the head node, follow the instructions for upgrading Kinetica under Reveal, if any custom slice types have been created in the environment being upgraded. These instructions will contain steps to be followed both before and after the upgrade is applied.

  5. On the worker nodes, create a backup file (.bak) or a tar file (.tar.gz) for all persist directories--the default being /opt/gpudb/persist-- defined in the gpudb.conf file (backing up these directories is optional, especially if the disk space is not available)

KAgent Installation

Before upgrading the database, KAgent must be installed on one of the nodes of the existing cluster or any other external server.

Important

If KAgent is already installed, skip to KAgent Upgrade

Installation of KAgent involves the deployment of the installation package. Once installed, a user interface or command line interface is available to help install Kinetica.

KAgent can be deployed on any server inside or outside the cluster. Deploy the package 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).

Kinetica Upgrade

Upgrading Kinetica using KAgent involves adding the existing cluster to KAgent and then deploying the updated package via either a browser-based UI or console-driven CLI.

KAgent UI

After installing KAgent, the KAgent UI displays an overview page as well as access to KAgent adminstration tools, cluster setup, and cluster components.

  • Click Rings to view the rings for the cluster; click Add Ring to begin the ring setup process (High Availability)
  • Click Add Cluster to jump to the cluster setup process.
  • Click Jobs to view completed and active KAgent jobs.
  • Click Logs to view KAgent logs.
  • Click console to view the console.

To access the KAgent UI and begin setting up a cluster:

  1. Ensure the KAgent service is started:

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

    http://<kagent-host>:8081/kagent
    
  3. Click Add New or Existing Cluster.

    Note

    Once in the setup process, click Clusters to exit setup and return to the start; click Logs to view KAgent logs; click Console to open the console log.

../_images/kagent_start.png

Cluster

Note

The license key can be the existing Kinetica license key or a new license key. Contact Support (support@kinetica.com) for any questions.

  1. Enter a name for the cluster. The name cannot contain spaces or underscores.

  2. For the Variant, select either CUDA (GPU) or Intel (CPU-only) depending on the package variant that's already installed on the current cluster you want to upgrade.

    Tip

    Use one of the following commands to determine the Kinetica package that is already on the machine:

    # RHEL
    rpm -qa | grep 'gpudb'
    
    # Ubuntu
    apt list --installed | grep 'gpudb'
    
  3. For the Install Mode, select either Online (upgrade from the online Kinetica repository) or Offline (upgrade from uploaded packages). If Offline is selected, click Upload Packages, then upload a package file for each component or driver desired for the upgrade.

    Important

    If performing an offline upgrade, all necessary dependencies will need to be installed prior to cluster setup.

    ../_images/kagent_upload_package.png
  4. Enter the license key.

  5. Optionally, select to install Graph if a node should have the graph server installed on it during the upgrade. See Network Graphs Solver Concepts for more information.

  6. Optionally, select to install KAgent if an additional node should also have KAgent installed on it during the upgrade. See Nodes for more information.

  7. Optionally, select to install AAW during the upgrade. If AAW (Active Analytics Workbench) is selected, select a K8 Setup:

    • Automatic -- KAgent will install Kubernetes / KubeCTL and upload a default configuration file.
    • Custom -- Upload a configuration file for an already existing Kubernetes installation. Note that AAW requires Kubernetes; see Active Analytics Workbench (AAW) Overview for more information.
  8. If the Variant is set to CUDA, select Automatically install Nvidia driver. This will automatically configure the server(s) for an Nvidia GPU driver and install the most compatible driver.

  9. Click Next.

../_images/kagent_cluster.png

Deployment

  1. Select the On Premise deployment provider, and click Next.

    Important

    If clearing the Open Firewall Ports checkbox, the firewall then must be configured manually to allow the required ports listed in the default ports table. Consult Firewall Settings for tips on configuring the firewall.

../_images/kagent_deployment.png

Security

  1. Enter and confirm the existing Admin Password. This is the password used to access Reveal, Active Analytics Workbench (AAW), and GAdmin as the default Admin user.

    Important

    The password provided here must match the existing cluster's admin password.

  2. Select an SSL Mode that best aligns with the existing cluster's SSL configuration:

    • Cert/key setup not required -- Kinetica will not require SSL certificate/key creation/upload but there will be no updates to security configuration settings
    • User-provided cert/key per node -- user must upload an SSL certificate and key for each node; Kinetica copies the cert/key pair to /opt/gpudb/certs, enables HTTPD, and configures HTTPD to use HTTPS
    • Generate self-signed cert/key per node -- KAgent generates a self-signed certificate and key for each node and places it in /opt/gpudb/certs, enables HTTPD, and configures HTTPD to use HTTPS
  3. Select the current Authentication type used for the existing cluster and fill the fields as necessary:

    • None -- no authentication or authorization
    • LDAP -- configures Kinetica to authenticate via LDAP; requires authentication to connect to the database, enables authorization, enables external authentication, automatically creates users in the database for LDAP users, and automatically grants roles in the database to LDAP users
    • Active Directory -- configures Kinetica to authenticate via Microsoft Active Directory; requires authentication to connect to the database, enables authorization, enables external authentication, automatically creates users in the database for Active Directory users, and automatically grants roles in the database to Active Directory users
    • Kerberos -- configures Kinetica to authenticate via Kerberos; requires authentication to connect to the database, enables authorization, enables external authentication, automatically creates users in the database for Kerberos users, and automatically grants roles in the database to Kerberos users
  4. Click Next.

../_images/kagent_security.png

Nodes

  1. Click Add New Node until the number of nodes in KAgent matches the number of nodes in the current cluster.

  2. Input the Hostname, Internal IP, and External IP for each existing node into KAgent.

  3. Optionally, if the User-provided cert/key per node SSL Mode was selected, click the lock icon in the SSL column and upload the SSL cert and key for each node.

  4. Select if each node should have the Core package installed. The Core package contains access to the database and its core components and functionality. Note that if the core package is installed on a node, that node cannot be designated as the Head Node.

  5. For the existing head node host, designate it as the head node in KAgent by selecting the Head Node radio button next to it.

  6. Optionally, if the Graph package was selected for install in Cluster, select the desired node for the Graph node using the corresponding radio button. The graph node hosts the graph server. The graph node does not need to have the Core package enabled.

  7. Optionally, if opting to install KAgent and/or AAW, select the desired node to host these services. The KAgent and/or AAW node(s) do not need to have the Core package enabled.

    Note

    All services and privileges (Head, Graph, AAW, KAgent) can exist on a single node if desired, assuming there are enough resources to handle it.

  8. Select if each node should have Rabbit (RabbitMQ) installed. Ensure at least one node will have RabbitMQ installed if enabling High Availability (HA) for the cluster; select 2 or more nodes to have RabbitMQ installed for redundant queues.

  9. Click Next.

  10. Confirm which IP address KAgent should use to connect to the cluster: Internal or Public.

../_images/kagent_nodes.png

Credentials

  1. For the Server SSH Credentials, enter the username and password or upload the SSH private key used to access the node(s).
  2. Optionally, enter the sudo password.
  3. Click Verify.
../_images/kagent_credentials.png

The console will appear showing the log of KAgent interactions as KAgent attempts to access the cluster with the provided credentials and also retrieve information on the hosts, including Kinetica version and configuration (if installed), hostname and IP addresses, OS type, and Nvidia information.

Upgrade

Existing cluster version information will be detected and the Add Only + and Upgrade buttons will be activated.

  1. Review the Upgrade Summary to ensure there are no validation errors in the information.

  2. Click Upgrade. The upgrade may take a while as KAgent deploys an updated package on each node in the cluster.

    Important

    If Automatic Kubernetes (K8) installation was selected, KAgent will request permission to disable SELinux on the nodes. Kubernetes cannot be installed otherwise. Click I Agree to continue with the upgrade; click No to stop the upgrade and manually disable SELinux.

    ../_images/kagent_selinux_permission.png

After a successful upgrade, if KAgent was also installed on a separate node, one can be redirected to the KAgent on that cluster node. If KAgent was not installed, one can be redirected to GAdmin.

Tip

GAdmin can always be found by browsing to the head node, using IP or host name:

http://<head-node-host>:8080/

KAgent can always be found by browsing to the node hosting it, using IP or host name:

http://<kagent-host>:8081/
../_images/kagent_upgrade.png

KAgent Upgrade

Important

If Kinetica and KAgent are already the latest version, skip to Upgrading Database Clients.

If Kinetica and KAgent are already installed, you can use the cluster upgrade functionality available in the KAgent cluster management interface. First, KAgent should be upgraded to the latest version:

# RHEL
yum update kagent-<version>-0.x86_64

# Ubuntu
apt-get install kagent-<version>-0.x86_64

Cluster Upgrade

Once KAgent is upgraded to the latest version, the KAgent cluster management interface can be used to upgrade a given cluster:

  1. Login to KAgent (http://<kagent-host>:8081).

  2. Next to the cluster that should be upgraded, click Manage.

  3. Click the Upgrade tab. KAgent will pull a list of versions available in the public Kinetica repository.

    ../_images/kagent_cluster_upgrade.png
  4. Select the desired version. It's recommended the latest version be selected.

  5. Click Upgrade. The upgrade may take a while as KAgent deploys an updated package on each node in the cluster.

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.

Validation

To validate that Kinetica has been installed and started properly, you can perform the following tests.

Curl Test

To ensure that Kinetica has started (you may have to wait a moment while the system initializes), you can run curl on the head node to check if the server is responding and port is available with respect to any running firewalls:

$ curl localhost:9191
Kinetica is running!

API Test

You can also run a test to ensure that the API is responding properly. There is an admin simulator project in Python provided with the Python API, which pulls statistics from the Kinetica instance. Running this on the head node, you should see:

$ /opt/gpudb/bin/gpudb_python /opt/gpudb/kitools/gadmin_sim.py
Collection 'SYSTEM' child tables: 1 total elements: 1 total objects: 1
|
 --------Table 'ITER' elements: 1 objects: 1 ttl: -1 remaining ttl: -1 type id: UNSET_TYPE_ID label: ''
**********************
Total tables:              1
Total top-level tables:    0
Total collections:         1
Total number of elements:  1
Total number of objects:   1

GAdmin Status Check

The administrative interface itself can be used to validate that the system is functioning properly. Simply log into GAdmin. Browse to Dashboard to view the status of the overall system and Ranks to view the status breakdown by rank.

Ingest/Read Check

After verifying Kinetica has started and its components work, you should confirm ingesting and reading data works as expected.

  1. Navigate to the Demo tab on the Cluster page.
  2. Click Load Sample Data under the NYC Taxi section. Confirm the data loading.
  3. Once the data is finished loading, click View Loaded Data. The data should be available in the nyctaxi table located in the MASTER collection.

If Reveal is enabled:

  1. Navigate to:

    http://<head-node-ip-address>:8088/
    
  2. Log into Reveal and change the administration account's default password.

  3. Click NYC Taxi under Dashboards. The default NYC Taxi dashboard should load.

Logging

The best way to troubleshoot any issues is by searching through the available logs. For more information on changing the format of the logs, see Custom Logging. Each component in Kinetica has its own log, the location of which is detailed below:

Component Log Location
Active Analytics Workbench (AAW) (API) /opt/gpudb/kml/logs/
Active Analytics Workbench (AAW) (UI) /opt/gpudb/kml/ui/logs/
GAdmin (Tomcat) /opt/gpudb/tomcat/logs/
Graph Server /opt/gpudb/graph/logs/
KAgent (Service) /opt/gpudb/kagent/logs/
KAgent (UI) /opt/gpudb/kagent/ui/logs/
Kinetica system logs /opt/gpudb/core/logs
Reveal /opt/gpudb/connector/reveal/logs/
SQL Engine /opt/gpudb/sql/logs/
Stats Server /opt/gpudb/stats/logs/
Text Server /opt/gpudb/text/logs/