Jitterbit private agents on Docker
Introduction
The examples on this page show you how to run one or more containerized private agents using Jitterbit's Docker hub image.
Note
The Docker image is not updated at the same time as the Windows or Linux agent packages. Refer to the image's tags page to see what versions are available.
The following examples show how to run a single agent:
- Quick start
- Manual registration with environment variables
- Automatic registration with environment variables
- Automatic registration with
register.json
file
The following examples show how to run multiple agents:
Important
Use the commands on this page for testing or as the basis for further development, and consult the Docker documentation for information on making them suitable for production systems.
Prerequisites
You must have the following:
- Docker
- Your Harmony account username and password.
- Your Harmony organization name.
You must have the following to run the multiple agent examples:
Quick start
This example uses the jitterbit-config
command to prompt for the agent's registration information, the jitterbit
command to start the agent, and tail -F
to wait for and show the agent log file.
-
Select Management Console > Agents from the Harmony Portal menu, then add a private agent group, or note the name and ID of an existing one.
-
In a terminal, run this command and respond to the prompts:
docker run -it jitterbit/agent sh -c "jitterbit-config; jitterbit start; tail -F log/jitterbit-agent.log"
-
To check the status of your agent, refresh the Management Console > Agents page.
-
In the terminal, press
Control+C
to stop the agent, or use thedocker container stop
command. -
(Optional) Delete the agent using the Management Console. (Agents started in this way are not automatically removed when stopped.)
Manual registration with environment variables
In the Quick start example, you must enter the agent's registration information when prompted. In this example, this information is provided using environment variables.
-
Add an agent to your agent group and note its name.
-
Create a file containing the following, with values set according to the table below:
HARMONY_ORIGIN= HARMONY_USERNAME= HARMONY_PASSWORD= HARMONY_ORG_NAME= HARMONY_AGENT_GROUP_NAME= HARMONY_AGENT_NAME=
Variable Value Description HARMONY_ORIGIN
The login URL for your Harmony account, https://REGION.jitterbit.com
, whereREGION
is one ofna-east
,emea-west
, orapac-southeast
.HARMONY_USERNAME
Your Harmony account username. HARMONY_PASSWORD
Your Harmony account password. HARMONY_ORG_NAME
Your Harmony organization name. HARMONY_AGENT_GROUP_NAME
The agent group name and environment name, separated by an underscore. HARMONY_AGENT_NAME
The agent name. ExampleHARMONY_ORIGIN=https://na-east.jitterbit.com HARMONY_USERNAME=example@jbexample.com HARMONY_PASSWORD=P@55w0rd HARMONY_ORG_NAME=Example Org HARMONY_AGENT_GROUP_NAME=Example Agent Group_Example Env HARMONY_AGENT_NAME=Example Agent 1
-
In a terminal, run this command to start the agent, replacing
FILE
with the name of the file created in step 2:docker run --env-file FILE jitterbit/agent
-
To check the status of your agent, refresh the Management Console > Agents page.
-
In the terminal, press
Control+C
to stop the agent, or use thedocker container stop
command. -
(Optional) Delete the agent using the Management Console. (Agents started in this way are not automatically removed when stopped.)
Automatic registration with environment variables
There are two disadvantages with the manual registration example: you must manually add an agent in the Management Console, and your Harmony credentials are visible to anyone with access to the system.
This example avoids both of these. It uses automatic registration to automatically add an agent to Harmony. Your Harmony credentials are encrypted and passed with the other required registration values to the container using a different set of environment variables.
-
In a terminal, run the following
jitterbit-utils
command to encrypt your credentials, replacingUSERNAME
andPASSWORD
with your Harmony username and password:docker run jitterbit/agent jitterbit-utils -e USERNAME PASSWORD
Example commanddocker run jitterbit/agent jitterbit-utils -e example@jbexample.com P@55w0rd
Example output$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C $003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=
-
Copy the output for use in the next step.
-
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
, whereREGION
is one ofna-east
,emea-west
, orapac-southeast
.AUTO_REGISTER_AGENT_GROUP_ID
The agent group ID number. AUTO_REGISTER_ENCRYPTED_USERNAME
The first line of output from step 1. AUTO_REGISTER_ENCRYPTED_PASSWORD
The second line of output from step 1. ExampleHARMONY_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=
-
Run this command to start the containerized private agent, where
FILE
is the name of the file created in step 2:docker run --detach --env-file FILE jitterbit/agent
-
To check the status of your agent, refresh the Management Console > Agents page.
-
To stop the agent, use the Management Console to drain stop the agent.
-
To stop the container, find the container ID with
docker ps
, then usedocker container stop CONTAINER_ID
. -
If
AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP
is set totrue
, the agent is automatically removed when stopped. If not, delete the agent in the Management Console.
Automatic registration with register.json
file
This example shows an alternative to registering with environment variables is to use a register.json
file.
-
Run the
jitterbit-utils
command to encrypt your Harmony username and password:docker run jitterbit/agent jitterbit-utils -e USERNAME PASSWORD
Tip
You can use the same encrypted username and password output from the previous example.
-
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": "test", "deregisterAgentOnDrainstop": false, "retryCount": 10, "retryIntervalSeconds": 5 }
Parameter Value description cloudUrl
The login URL for your Harmony account, https://REGION.jitterbit.com
, whereREGION
is one ofna-east
,emea-west
, orapac-southeast
.agentGroupId
The agent group ID number. username
The encrypted username (first line of output from step 1). password
The encrypted password (second line of output from step 1). Example conf/register.json{ "cloudUrl": "https://na-east.jitterbit.com", "agentGroupId": 12345, "username": "$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C", "password": "$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=", "agentNamePrefix": "test", "deregisterAgentOnDrainstop": false, "retryCount": 10, "retryIntervalSeconds": 5 }
Tip
An agent started this way uses the default settings in the Docker image's
jitterbit.conf
file. Without persistence, any changes you make to this file inside the container are lost when the container stops. To use your own settings, put them inconf/jitterbit.conf
. This file is copied into the container when it starts, overwriting the default file. -
Run this command to start the containerized private agent:
docker run --detach --name jitterbit-agent --rm --volume ./conf:/conf jitterbit/agent
Important
The private agent fails to start if the
conf
directory contains both acredentials.txt
file and aregister.json
file. -
To check the status of your agent, refresh the Management Console > Agents page.
-
To stop the agent, use the Management Console to drain stop the agent.
-
To stop the container, find the container ID with
docker ps
, then usedocker stop CONTAINER_ID
. -
If
deregisterAgentOnDrainstop
is set totrue
, the agent is automatically removed when stopped. If not, delete the agent in the Management Console.
Multiple agents with docker compose
In this example, three private agents with identical configurations run in an agent group.
-
Create an environment variables file as shown above.
-
Create a file
docker-compose.yml
containing the following:docker-compose.ymlservices: agent1: env_file: FILE image: jitterbit/agent container_name: jitterbit-agent1 agent2: env_file: FILE image: jitterbit/agent container_name: jitterbit-agent2 agent3: env_file: FILE image: jitterbit/agent container_name: jitterbit-agent3
FILE
: The name of the environment variable file created in step 1.
-
Run this command to start the private agent group:
docker compose up -d
Tip
Run
docker compose logs -f
to watch the log files from all agents, ordocker stats
to monitor each agent's resource usage. -
To check the status of your agent, refresh the Management Console > Agents page.
-
Run this command to stop the private agent group and remove their containers:
docker compose down -d
Multiple agents with helm
and kubernetes
Jitterbit provide a Helm chart that you can use to run a cluster of agents using Kubernetes.
-
Tip
In Docker Desktop, select Settings > Kubernetes > Enable Kubernetes.
-
Run this command to encrypt your Harmony username and password:
docker run jitterbit/agent jitterbit-utils -e USERNAME PASSWORD
Tip
You can use the same output from previous examples.
-
Create a file
values.yaml
containing the following, with values substituted according to the table below:1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
nameOverride: private-agent-group image: repository: jitterbit/agent pullPolicy: always agent: registerjson: cloudUrl: "https://REGION.jitterbit.com" agentGroupId: GROUP_ID username: ENCRYPTED_USERNAME password: ENCRYPTED_PASSWORD agentNamePrefix: "test" deregisterAgentOnDrainstop: true hpa: enabled: true minReplicas: 3 maxReplicas: 5 replicas: 4
Line Value Replace with 9 REGION
Your Harmony account region ( na-east
,emea-west
, orapac-southeast
).10 GROUP_ID
The agent group ID number. 11 ENCRYPTED_USERNAME
The first line of output from step 2. 12 ENCRYPTED_PASSWORD
The second line of output from step 2. Caution
This configuration specifies that Kubernetes should run at least 3 and at most 5 agents if the Horizontal Pod Autoscaler is active, or 4 agents if not. As each Docker private agent needs approximately 0.25 CPU cores and 2 GB of memory, you should check your host's specifications can support this number of agents. You can also add a
resources
element to set the limits of resource utilization. For more details, see Jitterbit's examplevalue.yml
file. -
Run these commands to add and update the Helm chart repository:
helm repo add jitterbit https://jitterbit.github.io/charts helm repo update
-
Run this command to start the private agent cluster:
helm upgrade -i -f values.yaml private-agent-group jitterbit/agent-group
Tip
Run
kubectl -n default get pods --watch
to monitor the cluster status, orkubectl exec -it private-agent-group-0 -- curl localhost:46912/axis/v1/cdk/internal/members
to list the members of the listening service's cluster. -
Run this command to stop the cluster and remove the containers:
helm uninstall private-agent-group