Docker Agent Automatic Registration Tutorial¶

Introduction¶

This tutorial shows you how to set up two (or more) Docker Private Agents that will automatically register to a designated Private Agent Group in your organization. You do this using a register.json file.

Overview¶

To complete this tutorial, complete each step in order:

1. Prerequisites: Make sure that you have the necessary software, credentials, and available agents.

   Important

   If using agents version 10.83 / 11.21 or later, skip steps 2 and 3 when using an Agent Registration access token as a recommended prerequisite. Steps 2 and 3 should be completed only if you are using Harmony credentials in the register.json file.

2. Create an Agent Installer User: If not using an Agent Registration access token, create a username and password that will be shared between agents and used when registering.

3. Generate an Encrypted Username and Password: If not using an Agent Registration access token, generate encrypted versions of the username and password.

4. Choose an Agent Group: Select an Agent Group and obtain its ID.

5. Create the register.json File: Create, complete, and install the register.json file.

6. Launch the First Agent: Launch the first agent using the automatic registration that you have configured.

7. Launch the Second Agent: Launch a second agent using the same automatic registration that you have configured.

8. Confirm Two Running Agents: Check that both of the agents have been started by using the Harmony Management Console.

Bonus Exercise: Instead of using a shared register.json file, configure and start an agent using environment variables whose values can be shared.

1. Prerequisites¶

To complete this tutorial, you will need:

• Docker (1.12 or higher) on Windows, Linux, or macOS
• A Harmony organization and login with Admin permission
• A minimum of two available agents in your Harmony subscription

If using agents version 10.83 / 11.21 or later, we recommend using Agent Registration access tokens over encrypted Agent Installer user credentials. Agent Registration access tokens do not expire and can be managed in the Management Console at any time.

2. Create an Agent Installer User¶

Create a user in your Harmony organization that has only the Agent Install permission:

1. Log in to the Harmony Portal (https://login.jitterbit.com) as a user with Admin permission (administrator credentials).

2. Go to Management Console > Organizations.

3. Add a new role and name it Agent Installer:

   

4. Modify this new role's permissions by using the dropdown next to Read to select only the Agent Install permission:

   

5. Select the Members tab, add a new member using a valid email address, and assign it to the Agent Installer role:

   

   Note

   This should be a dedicated user account with a valid email address. This will be used specifically for automatically registering agents.

6. Log out of the current user account (the one with Admin permission). This enables you to respond to the email for the new user you just created. Otherwise, you will need to respond using a private browser window to prevent using any cached login credentials.

7. Register this new user (check its email for the activation steps). You will need the username and password you created in step 3, Generate an Encrypted Username and Password.

8. Once the new user has been successfully registered, you can log back in to the Harmony Portal using your administrator credentials.

3. Generate an Encrypted Username and Password¶

Generate an encrypted username and password for the dedicated user you just created for automatically registering agents:

1. From a command line in a terminal running Docker, encrypt the username (shown below as first.last+agent-install@example.com) and password (shown below as some_Passw0Rd1) of the member you just created:

   # This Docker command returns an encrypted username and password (example only, actual will be different)
   docker run --rm jitterbit/agent:latest jitterbit-utils -e 'first.last+agent-install@example.com' 'some_Passw0Rd1'
   
   $000jwdBLiBsJnx4hCNIob1yn3gK9kisBm6knxmLFxV.../WHp6X7pvBkxuROg==
   $00phLWHm04Zsx9Wmug1eiIVaJemGjjm91CAVtkHH0bG+Y=
   

2. The encrypted credentials are on the two lines following the command. Note these will be different each time they are generated, even with the same username and password. The username is followed by the password:

   • Encrypted username: $000jwdBLiBsJnx4hCNIob1yn3gK9kisBm6knxmLFxV.../WHp6X7pvBkxuROg==
   • Encrypted password: $00phLWHm04Zsx9Wmug1eiIVaJemGjjm91CAVtkHH0bG+Y=

# Escaping special characters in 4pete'sSake!

echo "4pete'sSake\!"
4pete'sSake\!

echo '4pete'"'"'sSake!'
4pete'sSake!

4. Choose an Agent Group¶

Choose an Agent Group in your org and note its ID:

1. Go to Management Console > Agents > Agent Groups .

2. Hover over the Agent Group that will be associated with the new automatically registering agent and note its ID:

   

5. Create the register.json File¶

Create the file for automatically registering the agent:

1. In your current working directory, create a folder called conf.

2. In that directory, create and edit a file called register.json.

3. Insert the cloud URL, token (or encrypted username and password), and Agent Group ID appropriate for your Harmony region:

   Region	Cloud URL
   NA (North America)	https://na-east.jitterbit.com
   APAC (Asia-Pacific)	https://apac-southeast.jitterbit.com
   EMEA (Europe, Middle East, Africa)	https://emea-west.jitterbit.com

   Here is an example of a register.json file completed for use in the NA region:

   Agent Registration Access TokenEncrypted Username and Password

   Important

   Agent Registration access tokens require agents version 10.83 / 11.21 or later.

   register.json

   {
     "cloudUrl": "https://na-east.jitterbit.com",
     "token": "jb_a1b23c45-d6ef-789a-b0cd-e12fabcd3e4f",
     "agentGroupId": "224281",
     "agentNamePrefix": "auto_%ip%_%host%_%guid%",
     "deregisterAgentOnDrainstop": "true",
     "retryCount": "10",
     "retryIntervalSeconds": "5"
   }
   

   Important

   If using agents version 10.83 / 11.21 or later, we recommend using Agent Registration access tokens over encrypted Agent Installer user credentials. Agent Registration access tokens do not expire and can be managed in the Management Console at any time.

   register.json

   {
     "cloudUrl": "https://na-east.jitterbit.com",
     "username": "$000MTF/XSfev/KjlB/M1Q5vFkPLBKU5.../PwoHRiSGGLlJ",
     "password": "$006WIdHtws7wrjgCNAoabUzu0f+HsyzAfAZtTpauvsHBE=",
     "agentGroupId": "224281",
     "agentNamePrefix": "auto_%ip%_%host%_%guid%",
     "deregisterAgentOnDrainstop": "true",
     "retryCount": "10",
     "retryIntervalSeconds": "5"
   }
   

6. Launch the First Agent¶

Launch the first agent:

1. Make sure <working directory>/conf contains the updated register.json file.

2. Go to your working directory, the parent to the conf directory.

3. Use Docker to pull down the latest Jitterbit agent:

   docker pull jitterbit/agent:latest
   

   4. Launch a Docker Private Agent that uses that conf directory and the register.json file:

   docker run -it --rm -v "$(pwd)/conf:/conf" jitterbit/agent:latest
   # Command returns:
   ffdb4ed859472029cbf0b1ef0d4259db5a6...7290e200d36dbe5f75bfb59349
   

4. The Docker name will show when you run the command docker ps -a, and the container ID will match the value returned by the run command:

   docker ps -a
   CONTAINER ID IMAGE                  COMMAND                CREATED        STATUS        NAMES
   ffdb4ed85947 jitterbit/agent:latest "/entrypoint.sh /age…" 23 seconds ago Up 22 seconds bold_bhabha
   

7. Launch the Second Agent¶

Launch the second agent:

1. Make sure <working directory>/conf contains the updated register.json file.

2. Go to your working directory, the parent to the conf directory.

3. Use Docker to pull down the latest Jitterbit agent:

   docker pull jitterbit/agent:latest
   

4. Launch a second Docker Private Agent, substituting an appropriate name in this command for <dockername>:

   docker run --name <dockername> -d --rm -v "$(pwd)/ conf:/conf " jitterbit/agent:latest
   

   Tip

   This time, we gave the Docker instance a <dockername> so that you can stop it using docker stop <dockername>.

8. Confirm Two Running Agents¶

Confirm that both the first and second agent are running:

1. Return to Management Console > Agents > Agent Groups to confirm your running agents.
2. You should see two agents running, each identified by a name based on the agentNamePrefix , such as auto_172.17.0.2_b2a546cc080e_59a260ca_2020-02-14 17:43:03.033.

Environment Variables¶

If using encrypted Agent Installer user credentials, you can also launch a container using environment variables instead of the register.json file.

Test using DOCKER_AGENT_NAME, AUTO_REGISTER, and AUTO_REGISTER__X_ environment variables:

DOCKER_AGENT_NAME=agent1
docker run -it --rm \
           --name=${DOCKER_AGENT_NAME} \
           -e AUTO_REGISTER="true" \
           -e HARMONY_ORIGIN="https://na-east.jitterbit.com" \
           -e AUTO_REGISTER_ENCRYPTED_USERNAME="<encrypted username>" \
           -e AUTO_REGISTER_ENCRYPTED_PASSWORD="<encrypted password>" \
           -e AUTO_REGISTER_AGENT_GROUP_ID="<agent group id>" \
           -e AUTO_REGISTER_AGENT_NAME_PREFIX="auto_%ip%_%host%_%guid%" \
           -e AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP="true" \
           jitterbit/agent:latest