Installing the Agent for Google Cloud Composer

This topic guides you through the installation of the Agent for Google Cloud Composer (GC Composer) 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.

Tip! This page refers only to the manual installation process. If you want instructions on how to install a containerized Java agent, see Installing Containerized Java Agents.

It is best to install the agent in a separate directory (such as C:\AUTOMIC\AGENTS\GCC or Automic/Agent/gcc).

Important! Before installing the GC Composer Agent, check the version compatibility information at compatibility matrix. For information about how to use the compatibility matrix, see Compatibility Information.

This page includes the following:

Requirements

Before installing the Agent, make sure of the following:

  • If not already available, install the Java Runtime Environment.

  • Google service accounts are necessary for this integration. You should be familiar with the steps you need to take in this respect before installing the Agent for Google Cloud Composer.

    For some of the possible setups, a service account key is required. In these cases, make sure that you have the necessary .JSON file with the authentication information at hand. Please refer to the official Google documentation at Service accounts.

Connecting to the Automation Engine

The Automation Engine and the Windows, UNIX, and Java Agents communicate using TLS/SSL. These agents establish a connection with the Java communication process (JCP), which uses trusted certificates to prove their identity to other communication partners.

Note: The TLS/SSL implementation does not apply to the HP-UX Agent, as it is no longer supported in this version.

You can use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters in the respective INI file to point to the relevant certificates. If the trustedCertFolder= parameter is not set, the certificates should be installed in the respective store; that is the Java trust store for Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. For more information, see Securing Connections to the AE (TLS/SSL).

For more information about the different certificate types and for detailed instructions on how to create and use them, see What Kind of Certificates Should I Use for Automic Automation v21.

TLS/SSL Agents (in containers or on-premises) and the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer and not the JCP directly. The ingress / HTTPS load balancer must be reachable and requires a certificate for authentication. The address of the load balancer must be defined on both sides: the Automation Engine and the Agent / TLS Gateway.

Important! When you install or upgrade Agents manually for an Automic Automation Kubernetes Edition system, you have to make sure that you configure your Agents and/or TLS Gateway to reach the TCP or HTTPS load balancer and not the CP or JCP directly. Also, make sure that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to the AAKE Cluster.

Connecting to the Google Cloud Composer Environment

Once the Agent is installed and before you start it, you must identify the Google project to which you want to connect. Then, you must authenticate the Agent.

  1. Identify the Google Project for the Agent for Google Cloud Composer to which the Agent will connect. You have the following options:

    • Enter the Google project ID in the Automic Web Interface on the GC Composer page (Administration perspective > Agents & Groups > Agents > GC Composer Agent > GC Composer). You define the Agent object on this page. For more information, see Agent for Google Cloud Composer - Agent Object.

    • If you use the service account key, the .JSON file already contains the project ID and you do need to set it additionally.

    • If AAKE and the Agent run on a Google Cloud Platform in a Kubernetes cluster and the Agent runs in a container, you specify the project ID in the GCP_PROJECT_ID environment variable.

      If you configure the project ID both in AWI and through the GCP_PROJECT_ID environment variable, the variable is used and overwrites the value entered in the user interface.

  2. Authenticate the Agent to the Google project.

    You have the following options depending on your setup:

    • AAKE and the Agent run on the Google Cloud Platform in a Kubernetes cluster and the Agent runs in a container

      In these setups, you authenticate the Agent through the Workload Identity.

      Setting up the GCP_PROJECT_ID environment variable and authenticating the Agent through he Workload Identity is part of your work when configuring the Google Cloud Platform. This is the reason why we do not include the corresponding documentation here.

    • Other setups, for example on-prem systems, Agents not running on the Google Cloud Platform, and so on.

      Configure the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to the path where you have stored the .JSON file.

      In these setups, the Agent for Google Cloud Composer authenticates with the GC Composer environment through the service account key stored in the .JOSN file.

      1. Create the GOOGLE_APPLICATION_CREDENTIALS environment variable.

      2. Configure the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to the path where you have stored the JSON file.

      For more information about authentication with the Google Cloud Platform, please refer to the official documentation at https://cloud.google.com/docs/authentication.

Java Runtime Environment (JRE)

On the admin and/or user computer, install the Java Runtime Environment (JRE).

If you have JRE installed, you can ignore this step. For a list of compatible java versions, see compatibility matrix.

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/.

Supplied Files

The GC Composer core includes the following files:

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

    Contains the AWI panels.

  • uc.msl

    Message library

  • ucxjcitx.ini

    Agent configuration file

  • ucxjgcc.jar

    Agent core for the Agent

  • setup.exe

Installing the Agent

  1. If you have not already done so, do the following:

    1. Install the Java Runtime Environment (JRE).

    2. Set up your Google credentials and the GOOGLE_APPLICATION_CREDENTIALS environment variable.

  2. Download the installation package from https://docs.automic.com/documentation.

  3. On the host, install the Agent:

    UNIX

    1. Log in using the AE user.

    2. Transfer the ucxjgcc.tar file to a directory, for example gcc.

    3. Switch to the gcc directory: cd gcc.

    4. Unpack the .tar file:

      gzip -d ucxjgcc.tar

      tar xvfo ucxjgcc.tar

      Make sure all files have been unpacked correctly and to note all .tar messages, which can come from various owners. After that you can delete the .tar file if you like.

    5. Make sure all files have the correct owner and group entries.

    6. Rename the supplied INI file ucxjcitx.ori.ini to ucxjcitx.ini.

    7. Adjust the INI file to your system environment.

      • Use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters in the respective INI file to point to the relevant certificates. If the trustedCertFolder= parameter is not set, the certificates should be installed in the respective store; that is the Java trust store for Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. For more information, see Securing Connections to the AE (TLS/SSL).

      • 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.

        Although Agent names are limited to 32 characters, you should keep them under 25 characters. The last seven characters are used for adding the suffix '.NEW.nn' when a new Agent is created from its template.

      • 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

    WINDOWS

    1. Run setup.exe to start the program.

    2. Adjust the INI file to your system environment.

      • Use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters in the respective INI file to point to the relevant certificates. If the trustedCertFolder= parameter is not set, the certificates should be installed in the respective store; that is the Java trust store for Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. For more information, see Securing Connections to the AE (TLS/SSL).

      • 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.

        Although Agent names are limited to 32 characters, you should keep them under 25 characters. The last seven characters are used for adding the suffix '.NEW.nn' when a new Agent is created from its template.

      • 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

      The GC Composer Agent is an AE background program and it is generally started as a service in the ServiceManager. For more information, see ServiceManager.

  4. Start the Agent.

    1. Make sure that the AE system is running on the server computer. For more information, see Multi-Server Operations.

    2. On the host, start the Agent with the following commands:

      • Windows:

        <path to java> -Xrs -jar ucxjgcc.jar

        If java is installed in a folder which contains spaces the command needs to be placed in quotes.

        Example

        "C:\Program Files (x86)\Java\jre8\bin\java" -jar -Xrs -Xmx1G ucxjgcc.jar

      • UNIX:

        <path to java> -jar ucxjgcc.jar

        Example

        /usr/bin/java -jar ucxjgcc.jar

    3. On the admin or server computer, verify that the Agent is logged on to the Automation Engine.

      Newly logged on Agents are not assigned to a client automatically and can only be viewed in Client 0. Once you have logged in to Client 0, access the Administration perspective and select Agents & Groups.

      Assign the new Agent to clients with the required rights using the Agent object definition. For more information, see Authorizations Page.

Use the ServiceManager to start or end the Agent as a service. For more information, see ServiceManager.

Working with the Agent for Google Cloud Composer

Once you have finished the installation, the GC Composer is available in the Administration perspective in Client 0.

For information about how to work with Agent, see:

See also: