Agent Overview

The Kinetic Agent is a lightweight web application that provides a way to integrate systems across network boundaries securely with the Kinetic Platform, allowing simple and secure connections between customer enterprise LANs and Kinetic's hosted solution. The Agent can run all Kinetic Platform plugins (including bridge adapters, file adapters, and task handlers) independently from where the Kinetic Platform is hosted, enabling hybrid-cloud integrations for solutions built on the Platform.

How it Works

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

Security Considerations

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

Kinetic plugins typically require the connection information for the connecting resource (server address, username, password, and so on) after being installed. All connection information persists locally within the Agent’s environment.

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

Installation

Prerequisites

Hardware Requirements

The Kinetic Agent can be optionally configured for high availability. If this is a requirement, a minimum of 2 web servers will be needed, along with a load balancer to coordinate traffic between them.

Load Balancer

Kinetic Data recommends that all production environments be configured with more than one Kinetic Agent for redundancy. A load balancer will need to be configured 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 on the Tomcat website.

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 the plugin documentation for specific plugin software requirements.

Network Requirements

Firewall Rules

A firewall rule must created to allow traffic from the Kinetic Platform to whatever port the Kinetic Agent is running on. It is strongly recommended that the server hosting the Kinetic Agent be configured using SSL.

If the Kinetic Platform is hosted by Kinetic Data on kinops.io, the following IP addresses should be allowed 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 are being added as integrations within the Kinetic Platform.

Network/Shared Drive

If multiple Kinetic Agent web servers are required for high availability or capacity, a network drive will need to be provisioned 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 environment variables on the server. Be sure to restart the Tomcat web server after making any configuration variable changes but before continuing with the installation.

Data Directory

The Data Directory contains all plugins and plugin configurations. By default, this directory is located at <TOMCAT HOME>/webapps/kinetic-agent. If you're running multiple Agents, the directory must be moved to a location outside the Tomcat context. Kinetic also recommends doing this when running a single Agent.

If multiple Kinetic Agent web servers are configured, this data directory should be set to the network or shared drive that was provisioned with the web server.

You can set the Data Directory as a Java Option using Tomcat or as an environment variable. If you do not set a location, the default path is used.

Signing Secret

The Kinetic Agent uses a pre-shared secret you create to encrypt management and plugin execution traffic between the Kinetic Platform and the locally installed agent. The signing secret can be a list of comma-separated values to enable highly available blue-green rotation of secrets. The secret can be set as a Java Option in Tomcat or using an environment variable.

Configurator Username/Password

The Kinetic Agent provides an admin interface for locally managing plugins configured in the Agent. This interface is secured using a configurator username and password, which should be set in Tomcat (if using a Java Option) or as an environment variable.

Copy Software Package to Server

After downloading the Kinetic Agent, 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 the Tomcat Web Server using the kinetic-agent context (ie, https://webserver.acme.com/kinetic-agent) and logging 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, follow these steps to configure the Agent for use with a Kinetic Platform space:

1. Login to the Kinetic Platform Administration Console, and navigate to Space > Configuration > Plugins > Agents.

2. Click Add Custom Agent.

3. In the New Custom Agent modal, enter the following information:
   a. Agent Slug: An arbitrary identifier for the agent.
   b. Agent URL: The URL to the local agent or load balancer (if multiple Agents were installed).
   c. Agent Secret: The signing secret configured during installation.

4. Click Save.

5. From the Agent List view, select the checkbox next to the agent you just configured to verify connectivity.

   

Configuring the Agent for Handler Execution

In order to execute Handler Plugins using the Kinetic Agent, they must be downloaded, placed inside the Data Directory within the Kinetic Agent, and then configured with connection information.

Download and Import Handlers

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

First, Create a folder called “handlers” within the data directory that was configured in the Procedure section of the Agent install guide. The handlers folder should be a peer/sibling to logs, temp, config as seen in the image below.

Next, place any handlers that need to be added to the Agent inside the newly created handlers directory as seen in the image below. The handlers must be extracted/unzipped before moving them to this location.

Finally, restart Tomcat on each Kinetic Agent web server to pick up the newly added handlers.

Configure an Integration User

A user must be created within the Kinetic Platform to authenticate the “Agent Handler Execute” handler configured in the next step. The integration user must be a spaceAdmin. It is best practice for each Agent to have an integration user.

Configure the “Agent Handler Execute” handler

To execute a handler installed on a local agent, you must configure the Platform's workflow system to call the local agent. Follow these steps to do this:

1. Download the kinetic_agent_handler_execute_v3 handler and open the Platform Console.
2. Navigate to Space > Plugins > Handlers and click Import Handler.

3. Select the handler you want to upload and click Import.
4. Clicking on the newly imported Handler and enter the following connection details:

• api_server: The Kinetic Platform URL (for example, https://my-space.kinetic-platform-location.com).
• api_username: The integration username you set in the previous step.
• api_password: The integration user password you set in the previous step.

5. Add the Handler to a category to make it visible in the Workflow Builder.

Usage

Using an Agent Handler

Configure Agent Handler Instance

Follow these steps to create a new agent handler instance:

1. From the Platform Console, navigate to Space > Plugins > Agent Handlers.
2. Click New Agent Handler.
3. Select which Agent you would like to use to configure the handler.
4. Select which handler you’d like to configure.
5. Click * Next . You'll be prompted any configuration information that the agent handler requires. This is typically connection information like API location, username, and password.

Test Agent Handler Connection Information

Follow these steps to test the configured Agent handle:

1. Navigate to Space > Plugins > Agent Handlers.
2. Ensure this list is filtered by the correct agent slug, then click Test. The test provides example parameter values and ensures connectivity and results.
3. Note the names of the parameters displayed on this tab, as they will be needed in a future step when configuring a workflow to execute this handler.

Configure Agent Handler Execute node within a Workflow

Agent handlers executions can be initiated from workflows on the Kinetic Platform. The 'kinetic_agent_handler_execute' handler must be configured inside a workflow process to call an agent handler. Follow tthesehis steps to complete the configuration:

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 and search for the “Kinetic Agent Handler Execute” handler (if the handler isn’t in the list, make sure it was put into a category in the “Configure the “Agent Handler Execute” step
3. After giving the node a name, configure its parameters as follows:
   a. Agent Slug: The agent slug you configured in the Connecting the Agent to a Space step.
   b. Handler Slug: The handler slug you configured in the Configure Agent Handler Instance step.
   c. Parameters: A JSON map of the parameters and their values. The parameter keys can be found on the Test tab of the Agent Handlers setup page as described in the "Test Agent Handler Connection Information" section.

After configuring the Agent Handler Execute node, the tree or routine is ready to run and test.

Configuring an Agent Bridge

Agent bridges are configured the same way as system-configured bridges. Follow these steps to configure ana agent bridge:

1. In the Platform 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 for configuring any “system” bridges.

Once a bridge adapter instance has been configured, you can associate it with a new or existing model.

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, the following steps should be taken.

1. Log onto the server(s) hosting the local Kinetic Agent instance.
2. Append a new signing secret to the existing secret, separated by a comma.
3. Restart Tomcat to pick up the new signing secret.
4. To update the Agent Platform Component, follow the steps in the "Connecting the Agent to a Space" section of this guide.
5. After validating the connection, remove the previous signing secret and restart Tomcat.

Logging

To view log files, navigate to the Data Directory on the Agent server and open the "logs" folder.