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 a 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.)

Manual Registration

To manually register an agent, follow these steps:

1. Open the Management Console Agents page.

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 -it \
-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

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 jitterbit/agent
   

   Tip

   You should use either a credentials.txt file or a register.json file. The private agent won't start if the conf directory contains both.

To use the register.json file on non-containerized Linux private agents, move or 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: