Agent registration for Jitterbit private agents

Introduction

Before a private agent can process integration project operations, it must register with a Harmony server. The information it needs to register includes the Harmony server URL for your organization's region, your Harmony account credentials, the name of the private agent group it is to join, and the name of the agent itself. To get the name of a private agent, you must first add one using the Management Console Agents page. You can then give it as one of the required pieces of registration information during the installation step on Windows (with manual input into the installer), the configuration step on Linux (with manual input or parameters for jitterbit-config), or when starting a Docker container (with environment variables). This approach to registration is known as manual registration.

If you want to automatically provision and dispose of containerized private agents (for example, using Kubernetes), you must use the Jitterbit private agent auto-register feature. With this, you don't need to add an agent with the Management Console Agents page. The system automatically adds a private agent to a named agent group, generates an agent name, then registers it. The system can also optionally de-register and remove the private agent from the agent group when the agent stops. (There is one disadvantage: you cannot use a proxy with automatic registration.)

How it works

This section is an overview of the key concepts and settings that govern how an agent registers and de-registers, and how it behaves after a restart.

The credentials.txt file

When a private agent registers with Harmony for the first time, it creates the file JITTERBIT_HOME/Resources/credentials.txt. This file contains the agent's encrypted credentials, and is used to authenticate and reconnect to Harmony after a restart. It must be preserved to allow the agent to restart.

Agent behavior on restart

The register.json file's deregisterAgentOnDrainstop parameter controls what happens when a private agent stops or restarts. (This parameter can also be passed as an environment variable in automated environments.) The allowed values are true and false. Each value has the following behavior:

• deregisterAgentOnDrainstop=false: This is the default value. With this, an agent is not removed from Harmony when it stops, but remains listed in a Stopped state.

  When the agent restarts, it uses its existing credentials.txt file to re-authenticate with Harmony and resume operations. This is the recommended approach for most use cases, especially when you need agents to persist across planned or unplanned restarts.

• deregisterAgentOnDrainstop=true: With this, the agent actively de-registers itself from Harmony when it is stopped, and is removed from the agent group's agent list in the Management Console.

  If you try to restart the agent, it fails to initialize. This happens because its credentials.txt file is now invalid and Harmony no longer recognizes the agent. To recover this agent, you must remove (delete) the stale credentials.txt file. This forces the agent to perform a fresh registration the next time it starts. This behavior is typically used in auto-scaling environments where agents are considered disposable and are frequently created and destroyed.

Registration methods

There are two mechanisms for registering a private agent:

• Manual: With this method, you first add an agent in the Management Console to create an agent entry. You then provide the agent's details during the installation process (on Windows and Linux), or with environment variables (for Docker).

• Automatic: This approach is primarily used for containerized agents with platforms like Docker and Kubernetes. It lets an agent automatically create and register itself in Harmony. It uses a register.json configuration file or environment variables to provide the necessary information. This approach is ideal for automated, auto-scaling deployments.

Manual registration

To manually register an agent, follow these steps:

1. Go to Management Console > Agents.

2. Add a private agent group, or identify an existing one, then add a new private agent to it.

3. Supply the registration information. When you do this depends on the agent host type:

   WindowsLinuxDocker

   During installation, the user interface prompts you to select which agent group to join, and which agent to register.

   During configuration, the jitterbit-config command prompts you to select which agent group to join, and which agent to register. (Alternatively, these values can be provided as parameters to jitterbit-config.)

   When running the container, use the environment variables below.

Manual registration of a Docker private agent using environment variables

To use manual registration with containerized private agents, set values for the following environment variables, and pass them into the container:

docker run -d \
-e HARMONY_ORIGIN=https://na-east.jitterbit.com \
-e HARMONY_USERNAME=example@jbexample.com \
-e HARMONY_PASSWORD=P@55w0rd \
-e HARMONY_ORG_NAME="Example Org" \
-e HARMONY_AGENT_GROUP_NAME="Example Agent Group_Example Environment" \
-e HARMONY_AGENT_NAME=ExampleAgent \
jitterbit/agent

cat > agent.env <<EOF
HARMONY_ORIGIN=https://qa-green.jitterbit.com
HARMONY_USERNAME=example@jbexample.com
HARMONY_PASSWORD=J1tt_erb1t
HARMONY_ORG_NAME="JB Example Company"
HARMONY_AGENT_GROUP_NAME="Agent Group A_Default Environment"
HARMONY_AGENT_NAME=XMPL_3
ENABLE_JITTERBIT_METRICS=true
EOF
docker run -d --env-file=agent.env jitterbit/agent

Automatic registration

With automatic registration, there are two ways to supply registration information: in a register.json file, or as environment variables.

Register a Docker private agent using the register.json file

To automatically register a Docker private agent using a register.json file, follow these steps:

1. Create a directory and file conf/register.json containing the following, with values set according to the table below:

   conf/register.json

   {
       "cloudUrl": "https://REGION.jitterbit.com",
       "agentGroupId": GROUP_ID,
       "username": "ENCRYPTED_USERNAME",
       "password": "ENCRYPTED_PASSWORD",
       "agentNamePrefix": "PREFIX",
       "deregisterAgentOnDrainstop": false,
       "retryCount": 10,
       "retryIntervalSeconds": 5
   }
   

   Parameter	Value description
   cloudUrl	The login URL for your Harmony account, https://REGION.jitterbit.com, where REGION is one of na-east, emea-west, or apac-southeast.
   agentGroupId	The private agent group ID number.
   username	Your encrypted Harmony account username.
   password	Your encrypted Harmony account password.
   agentNamePrefix	A prefix for the auto-generated private agent name.

   Example conf/register.json

   {
       "cloudUrl": "https://na-east.jitterbit.com",
       "agentGroupId": 12345,
       "username": "$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C",
       "password": "$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=",
       "agentNamePrefix": "test",
       "deregisterAgentOnDrainstop": false,
       "retryCount": 10,
       "retryIntervalSeconds": 5
   }
   

2. Start the Docker private agent with the conf directory mounted to the container's /conf directory. (See Automatic registration with register.json file for an example.)

   Example

   docker run --detach --name jitterbit-agent --rm --volume ./conf:/conf --volume local_resources:/opt/jitterbit/Resources jitterbit/agent
   

You must use either a credentials.txt file or a register.json file. The private agent won't start if the conf directory contains both. The register.json file is converted into a credentials.txt file and then removed. The credentials.txt file is never removed, and remains when the container is stopped and the agent deregistered.

To use the register.json file on non-containerized Linux private agents, remove the /opt/jitterbit/Resources/credentials.txt file, create a /opt/jitterbit/Resources/register.json file as shown above, then restart the agent.

Register a Docker private agent using environment variables

To automatically register a Docker private agent using environment variables, follow these steps:

1. Create a file containing the following, with values substituted according to the table below:

   HARMONY_ORIGIN=
   AUTO_REGISTER=true
   AUTO_REGISTER_AGENT_GROUP_ID=
   AUTO_REGISTER_AGENT_NAME_PREFIX=auto
   AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP=false
   AUTO_REGISTER_ENCRYPTED_USERNAME=
   AUTO_REGISTER_ENCRYPTED_PASSWORD=
   

   Variable	Value description
   HARMONY_ORIGIN	The login URL for your Harmony account, https://REGION.jitterbit.com, where REGION is one of na-east, emea-west, or apac-southeast.
   AUTO_REGISTER_AGENT_GROUP_ID	The private agent group ID number.
   AUTO_REGISTER_ENCRYPTED_USERNAME	Your encrypted Harmony account username.
   AUTO_REGISTER_ENCRYPTED_PASSWORD	Your encrypted Harmony account password.

   Example

   HARMONY_ORIGIN=https://na-east.jitterbit.com
   AUTO_REGISTER=true
   AUTO_REGISTER_AGENT_GROUP_ID=12345
   AUTO_REGISTER_AGENT_NAME_PREFIX=auto
   AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP=false
   AUTO_REGISTER_ENCRYPTED_USERNAME=$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
   AUTO_REGISTER_ENCRYPTED_PASSWORD=$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=
   

2. Start the Docker private agent, passing the environment variables file using the --env-file option for docker run:

   Example

   docker run --detach --env-file FILE jitterbit/agent
   

   Tip

   Alternatively, use the -e/--env option to set environment variables individually.

Comparison of register.json parameters and environment variables

The following table compares the parameters used in the register.json file with their environment variable equivalents: