Installing the Agent for Apache Kafka

This topic guides you through the installation of the Apache Kafka Agent in an AE system without using authentication. If you want to use one of the authentications methods available, you need to follow additional installation steps. For more information, see Agent Authentication in the Automic Automation documentation.

Connecting to the Automation Engine

The Automation Engine and the Agent communicate using TLS/SSL, which requires using trusted certificates to prove the identity of the respective communication partner. Make sure you are familiar with the TLS/SSL and certificate implementation before installing the Agent. For more information, see TLS/SSL Considerations for Automic Automation in the Automic Automation documentation.

When the Agent communicates with an on-premises Automic Automation environment, the Agent establishes a connection with the Java communication process (JCP).

When you use certificates signed by a CA, the certificates are stored in the respective Java trust store by default. In this case, you only have to check that the root certificates already are in the respective store. If you do not want to use the default locations for the Agent, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

When the Agent communicates with the Automic Automation Kubernetes Edition, it establishes a connection to an ingress / HTTPS load balancer. Make sure that the address of the load balancer is defined on both sides: the Automation Engine and the Agent and that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to AWI, the JCP and REST Processes Using an Ingress in the Automic Automation documentation.

Java Runtime Environment (JRE)

On the admin and/or user computer where the Agent is installed, install the Java Runtime Environment (JRE). For a list of compatible java versions, see compatibility matrix.

If you have JRE installed, you can ignore this step.

Use the following command to check the version of the current Java virtual machine (VM):

java -version

If several JRE or Java SDK Versions are installed on the computer, make sure that the order of the directories is correct in the %PATH% or $PATH settings since the first JRE that is found in the list of directories is used.

You can download the required JRE from https://www.oracle.com/java/technologies/.

Installing the Agent

The installation of the Apache Kafka Agent is exactly the same for Windows and for UNIX platforms.

1. If you have not already done so, install the Java Runtime Environment (JRE).

2. Download the Apache Kafka installation package from https://marketplace.automic.com/. It is called Integration.Kafka_Agent_<version>+build.<build number>.zip.

3. Unzip Integration.Kafka_Agent_<version>+build.<build number>.zip to the location where you want to install the Agent, for example to a kafka folder.

   The installation package has an Agents\kafka\bin directory with the following content:

   • lib

   • ecc-ae-sheet-ra-kafka.jar

     Contains the AWI panels.

   • uc.msl

     Message library

   • ucxjcitx.unix.ini

     Agent configuration file for UNIX

   • ucxjcitx.win.ini

     Agent configuration file for Windows

   • ucxjkafka.jar

   Note:

   The content of the two INI files is identical except for the slashes (for Windows) and backslashes (for UNIX).

4. Rename the supplied INI file by removing the OS-specific string:

   • If you are installing the Agent on a Windows platform, rename ucxjcitx.win.ini to ucxjcitx.ini.

   • If you are installing the Agent on a UNIX platform, rename ucxjcitx.unix.ini to ucxjcitx.ini.

5. Adjust the INI file to your environment.

   • When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default. In this case, you only have to check that the root certificates already are in the respective store.

     If you do not want to use the default location for this component, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

     For more information, see Securing Connections to the AE (TLS/SSL) in the Automic Automation documentation.

   • name

     Name of the Agent object.

     Maximum length: 32 characters

     Allowed characters: "A-Z", "0-9", "_", ".", "$", "@", "-" and "#".

     Hyphens ("-") are only allowed in Agent names. They must not be used in the names of any other objects.

   • system

     Automation Engine system name. This entry must be identical to the entry in the .ini file of the Automation Engine server.

   • ra

     Used for additional trace. Before starting a newly installed or upgraded Agent, it is a good idea to turn Rapid Automation trace on by adding ra=99. This will give more troubleshooting information if something goes wrong during the install. After a successful Agent start, you can set ra=0, and restart the Agent to turn Rapid Automation trace off.

   • connection

     Address of the communication process in the Automation Engine system to which the Agent should connect itself. The format is:

     <DNS name or TCP/IP address>:<port number>

   For more in formation, see Agent RA Core.

6. To install and start the Agent, run the following command on the location where you have stored the Agent installation files:

   <path to java> -jar ucxjkafka.jar

   Tip:

   If Java is installed in a folder whose name contains spaces, the path to java must be in quotes, for example: "C:\Program Files (x86)\Java\jreX\bin\java" -jar -Xrs -Xmx1G ucxjkafka.jar

   The Agent is now available and up and running. To check it, do the following:

   1. Open the Automic Web Interface (Automic Automation's web interface) and log in to Client 0.

   2. Go to the Administration perspective > Agents & Agent Groups > Agents page.

   Note:

   If you are installing the Agent for the first time, this command installs and starts it. If you have already installed it before and run this command, it will simply start it.

7. Newly installed Agents are not assigned to a Client automatically and are available on Client 0 only. You must assigned the Agent to the corresponding Client(s). For more information, see Assigning Clients to Agents in the Automic Automation documentation.

Managing the Agent through the Service Manager

The Service Manager, one of Automic Automation's components, provides an easy and convenient way to start, stop and access components, such as Agents, from a central point. Usually you install the Service Manager when you install the Automic Automation components.

You can manage the Agent from the Service Manager, too. For this purpose, you must add the Agent to the Service Manager first. For information about how to do it, see the Adding Components section in the Service Manager - Dialog program documentation.

Next Step

Once you have finished the installation, the Agent is available in the Administration perspective in Client 0. You can configure the Agent properties in Client 0 using the Automic Web Interface, see Defining the Apache Kafka Agent.

For more information about Agents, see Agents (HOST) in the Automic Automation documentation.

See also:

• Automic Automation / Apache Kafka Agent Integration

• Implementation Overview

• Establishing the Connection to Apache Kafka