Agent Overview

The Kinetic Agent is a lightweight web application that provides a way to securely integrate systems with the Kinetic Platform across network boundaries. The Agent is capable of running all Kinetic Platform plugins (including bridge adapters, file adapters, and task handlers) independently from the Kinetic Platform's host location, enabling hybrid-cloud integrations for solutions built on the platform.

How it Works

In a typical configuration, the Kinetic Agent is installed onto a web server (or series of web servers for high availability) within a DMZ. A firewall rule is then created, allowing inbound traffic from the remote Kinetic Platform instance to access the Agent over HTTP(S). Network policies are then configured between the DMZ and the local network for each integration required.

Security Considerations

By default, the Agent is configured not to allow any plugins (untrusted code) to be remotely uploaded. This enables local security teams and administrators to scan and install only trusted plugins that are required for an implementation.

Kinetic Plugins typically require connection information (server address, username, password, etc.) for the connecting resource after installation. All connection information persists locally within the Agent’s environment.

Remote administration of the Agent from the Kinetic Platform's Space Administration Interface is secured using a shared secret that is configured when the Agent is installed. This secret can be rotated using blue-green deployments on a regular basis in line with local security standards.

Installation

Prerequisites

Hardware Requirements

The Kinetic Agent can be optionally configured for high availability. A minimum of 2 Web Servers is needed along with a load balancer coordinating traffic between them.

Load Balancer

Kinetic Data recommends that all production environments be configured with more than one Kinetic Agent for redundancy. You will need to configure a load balancer according to your company security standards to distribute traffic between each Kinetic Agent web server.

Software Requirements

Apache Tomcat

The Kinetic Agent requires a Web Server configured with Apache Tomcat version 8 or later. Instructions for installing Apache Tomcat and its dependencies can be found at https://tomcat.apache.org/

Plugin-Specific Software Requirements

In some rare cases, plugins require additional software to be installed on the server. Examples include plugins that make direct command line calls. See plugin documentation for specific plugin software requirements.

Network Requirements

Firewall Rules

You will need to create a firewall rule that allows traffic from the Kinetic Platform to whatever port the Kinetic Agent is running on. Kinetic Data strongly recommends that the server hosting the Kinetic Agent be configured using SSL.

If the Kinetic Platform is hosted by Kinetic Data on kinops.io, allow the following IP addresses for inbound/outbound traffic:

• 52.22.66.56
• 174.129.162.107
• 3.211.40.196
• 3.216.128.34
• 18.232.11.239

Additional network rules may need to be configured between the Kinetic Agent(s) running in the DMZ and services running within the Enterprise LAN that were added as integrations within the Kinetic Platform.

Network/Shared Drive

If multiple Kinetic Agent web servers are required for high availability or capacity, you will need to provision a network drive on each Kinetic Agent web server to coordinate configuration changes between each Agent host.

Install Procedure

Configuration Variables

The Kinetic Agent requires two configuration variables to run securely and reliably. These variables can be set via Java system properties or via environment variables on the server.

Note: Be sure to restart the Tomcat web server after making any configuration variable changes and before continuing with the installation.

Data Directory

The Data Directory contains all plugins and plugin configurations. By default, this directory is located within the Kinetic Agent web application /webapps/WEB-INF/config.

Important: If running multiple Kinetic Agent web servers, this directory must be set to a location outside of the Tomcat context. Kinetic Data strongly recommends setting the directory in the same manner for single Agents as well.

If you are configuring multiple Kinetic Agent web servers, set this data directory to the Network/Shared drive that was provisioned with the web server. The Data Directory can be set one of the following two ways:

Signing Secret

The Kinetic Agent uses a pre-shared secret to encrypt management and plugin execution traffic between the Kinetic Platform and the on-prem agent. The Signing Secret can be a list of comma separated values to enable highly available blue-green rotation of secrets.

Configurator Username/Password

The Kinetic Agent provides an admin interface for locally managing plugins configured in the Kinetic Agent. This admin interface is secured using a Configurator Username/Password that should be set using the following instructions:

Copy Software Package to Server

After downloading the Kinetic Agent zip file, unzip it and place the kinetic-agent.war file into the /webapps directory on each Kinetic Agent Web server. Within a few seconds (or after restarting Tomcat if auto-deployment is disabled in your Tomcat configuration), you should be able to access the Kinetic Agent web server by navigating to the Tomcat Web Server using the kinetic-agent context (for example, https://webserver.acme.com/kinetic-agent) and log in using the configurator username and password set in the previous step.

Post-Installation

Connecting the Agent to a Space

Once the Kinetic Agent has been installed, you can configure it can within a Kinetic Platform Space.

1. Log in to the Kinetic Platform Administration Console.
2. Navigate to Space > Settings > Platform Components > Agents.
3. Click Add Agent and enter the following required information:
   1. Agent Slug: An arbitrary identifier for the agent (ie, acme-on-prem-agent)
   2. Agent URL: The URL to the local agent (or load balancer if multiple Agents were installed)
   3. Agent Secret: The Signing Secret configured in the Installation section.
4. Click Save.
5. From the Agent List view, select the check box next to the newly configured agent to verify connectivity.

Configuring the Agent for Handler Execution

In order to execute Handler Plugins using the Kinetic Agent, you will need to be download the plugins, place them inside the Kinetic Agent Data Directory, and then configured the handlers with connection information.

Download and Import Handlers

The first step for Hander usage in the Kinetic Agent is to download or package any relevant handlers to one of the Kinetic Agent servers.

1. Create a folder called “handlers” in the data directory. The handlers folder should be a peer/sibling to logs, temp, config as seen in the image below.
   
2. Extract/unzip any handlers you want to add to the Agent.
3. Place the extracted handlers in separate folders inside the newly created "handlers" directory as shown in the image below.
   
4. Restart Tomcat on each Kinetic Agent web server to pick up the newly added handlers.

Configure an Integration User

You must create an integration user with spaceAdmin privileges in the Kinetic Platform to authenticate the “Agent Handler Execute” handler (configured in the next step).

Note: Kinetic Data recommends that each Agent web server have its own integration user as a best practice.

Configure the “Agent Handler Execute” handler

In order to execute a Handler installed on a local (on-premise) Agent, you must configure a handler in the Kinetic Platform’s Workflow system to call the local (on-premise) Agent.

1. Download the kineticagenthandlerexecutev3 handler.
2. Navigate to Space > Plugins > Handlers, click Import Handler, and select the kineticagenthandlerexecutev3 handler to upload it.

3. Click the handler name to display the handler details.
4. Enter the following configuration information:
   1. api_server: The Kinetic Platform URL (for example, https://my-space.kinetic-platform-location.com)
   2. api_username: The integration user username you configured previously.
   3. api_password: The integration user password you configured previously.
5. Add the Handler to a category so that it becomes visible in the Workflow Builder.

Using an Agent Handler

Configure Agent Handler Instance

1. Navigate to the Kinetic Platform Space Administration Consoles.
2. Click Space > Plugins > Agent Handlers.
3. Click New Agent Handler to begin configuring a handler that was installed on the local Agent.
4. You will be prompted to select which Agent you would like to configure the handler on (acme-on-prem-agent) as well as which handler you’d like to configure. A list of handlers that have been installed on the local Agent will be displayed in the Select a Handler drop-down list.

5. Click Next. You will be prompted to enter any configuration information required by the agent. This is typically connection information like API location, username, and password.

Test Agent Handler Connection Information

Once an Agent Handler has been configured, you can test it.

1. Navigate to Space > Plugins > Agent Handlers. Make sure this list is filtered by the correct agent-slug.
2. Click Test
3. Enter example parameter values and review the results to ensure connectivity.

Note: It’s helpful to jot down the names of the parameters displayed on the Test tab, you will need them when configuring a workflow to execute this handler.

Configure Agent Handler Execute node within a Workflow

You can initiate execution of Agent Handlers from workflows on the Kinetic Platform. To call an Agent Handler, the "kinetic_agent_handler_execute" handler must be configured inside of a workflow process.

1. Open the workflow builder using a new or existing Tree or Routine that you would like to call an Agent Handler from.
2. Click the + button to add a new task to the workflow.
3. Search for the “Kinetic Agent Handler Execute” handler. If the handler isn’t in the list, make sure it was added to a category in the “Configure the “Agent Handler Execute” section.
4. After giving the node a name, configure its parameters as follows:
   1. Agent Slug: The slug of the agent configured in the "Connecting the Agent to a Space" section.
   2. Handler Slug: The slug of the handler configured in the "Configure Agent Handler Instance" section
   3. Parameters: A JSON map of the parameters and their values. You can find the parameter keys on the Test tab of the Agent Handlers setup page as described in the "Test Agent Handler Connection Information" section.

Once the Agent Handler Execute node has been configured, the tree or routine is ready to be run and tested.

Configuring an Agent Bridge

Agent Bridges are configured the same way as system-configured bridges.

1. In the Space Administration Console, navigate to Space > Plugins > Bridges.
2. Click New Bridge.
3. Choose the appropriate Agent and Adapter Class.

The subsequent setup pages are the same as those used when configuring system bridges.

Once a Bridge Adapter instance has been configured, you can associate a Model to the instance by creating a new Model or modifying an existing one. Select the appropriate Agent Slug and the Bridge Slug you configured in the previous section.

Administration

Rotating Agent Secrets

Kinetic Agent Administrators can rotate the pre-shared Agent secret to conform to corporate security best practices. To rotate a secret, complete the following steps:

1. Log on to the server hosting the local Kinetic Agent instance.
2. Append a new Signing Secret to the existing secret, separating the two with a comma.
3. Restart Tomcat to pick up the new Signing Secret.
4. Update the Agent Platform Component by following the steps in the "Connecting the Agent to a Space" section.
5. Once you have validated the connection, remove the previous Signing Secret and restart Tomcat.

Logging

Log files are located in the "logs" folder of the Data Directory location on the Agent Server.