Adding a Cluster to KAgent

If you have an existing on premise Kinetica cluster that is not managed by KAgent, you can add it to KAgent without upgrading it. This is particularly useful in the following scenarios:

  • Not all administrative and normal users have direct server-level access to the nodes in the cluster, and they would like to individually manage all relevant services
  • Not all administrative users have direct server-level access, and they would like to schedule and manage backups and snapshots and restore from snapshots if necessary
  • Users would like to keep track of the valid Kubernetes Docker registries for use with the Active Analytics Workbench (AAW)

The cluster addition process using KAgent involves adding key information about your cluster to KAgent, including deployment type, security information, node information, and current Kinetica-related packages/services installed.


Any services (graph, AAW, RabbitMQ, etc.) and/or nodes in the existing cluster that are not noted during the cluster setup process will not be automatically picked up by KAgent and thus cannot be managed by KAgent. Any services not already installed cannot be installed during this process; likewise, additional nodes cannot be added to the cluster during this process.


Before beginning, make sure KAgent is installed.


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:

  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.

  4. Click Add New or Existing Cluster.




The license key can be the existing Kinetica license key or a new license key. Contact Support ( for any questions.

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

  2. Optionally, select one or more of the following packages:

    • Select Core if node(s) in the cluster have the core database functionality installed on them.

    • Select Etcd if node(s) in the cluster have etcd installed on them.


      The etcd package is required for the following:

    • Select Graph if a node in the cluster has the graph server installed on it. See Network Graphs & Solvers Concepts for more information.

    • Optionally, select AAW (Active Analytics Workbench) if a node has AAW installed on it. See Active Analytics Workbench for more information.

    • Optionally, select KAgent if another node in the cluster has KAgent installed on it. See KAgent for more information.

    • Optionally, select HA if the cluster is currently in a ring. Review High Availability Architecture and High Availability Configuration & Management for more information.

  3. For the Install Mode, select Online (install directly from the online Kinetica repository).

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


    Use the following command to determine the Kinetica package that is already on the machine:

    # RHEL
    rpm -qa | grep 'gpudb'
    # Ubuntu
    apt list --installed | grep 'gpudb'
  5. Enter the license key.

  6. Optionally, provide an external files directory for use with external tables to override the default external files directory parameter value.

  7. If AAW is selected, select the Custom type for K8 Setup (Kubernetes should already exist and KAgent will not install anything during this process). Upload a configuration file for an already existing Kubernetes installation and provide a public IP address for the server hosting the Kubernetes installation. Note that AAW requires Kubernetes; see Active Analytics Workbench (AAW) Overview for more information.

  8. Click Next.



KAgent does not support multiple installations of Kinetica with differing deployment types, e.g., an On Premise cluster and a Microsoft Azure cluster cannot exist in the same instance of KAgent.


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


    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 Adjust Firewall for tips on configuring the firewall.



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


    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.



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

  2. Input a custom Label (hostname is suggested), the Internal IP, and the External IP for each existing node into KAgent.

  3. If the User-provided cert/key per node SSL Mode was selected in Security, an SSL column will be added to the configuration page--click the lock icon in the SSL column to open the SSL Certificate/Key window, where the SSL cert and key, along with an optional public hostname, can be provided. Repeat this for each node.

  4. Select each node that has the Core package installed.

  5. Select each node that has the Etcd package installed.

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

  7. If the Graph package was selected for install in Cluster and existing node(s) hosts a graph server, designate it as a Graph node using the corresponding radio button. The graph node(s) hosts the graph server. The graph node does not need to have the Core package enabled.

  8. If the AAW package was selected for install in Cluster, set the number of reserved GPUs for AAW to use for each node. The AAW service co-exists with the head node. Note that the AAW package is automatically installed on every node with the Core package enabled. If enabling cluster resiliency, consult the head node failover section for information on how cluster resiliency works with AAW.


    Some features of AAW require GPUs to work or have increased performance. Review the AAW documentation for more information.

  9. If the RabbitMQ package was selected for install in Cluster because a High Availability setup is already enabled, select the node(s) that have RabbitMQ installed.

  10. If the cluster was configured for cluster resiliency, select each node that is a spare.

  11. Click Next.

  12. If a node was marked as a spare, confirm that the system already has the required distributed/shared file system installed, then click OK.

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



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

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.


If the configuration you have selected does not match the current configuration on the cluster you're trying to upgrade, KAgent will list the errors and provide the opportunity to fix the configuration manually or automatically.


Add Cluster

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

  1. Review the Add Summary to ensure there are no validation errors in the information.
  2. Click Add Only +. KAgent will open a window displaying the progress of the cluster addition.

After a successful cluster addition, you'll be returned to the KAgent home page and also will be offered to be redirected to GAdmin on the head node. Review KAgent for more information on using KAgent.


After the addition, the cluster will be added to KAgent and you'll be logged into KAgent as the admin user for the cluster. After this session is over (via either logging out or session timeout), you'll be required to log into KAgent every time you want to access KAgent features. See Logging In / Out for more information.