Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

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.

NOTE: Additional Docker Private Agent documentation is available at https://hub.docker.com/r/jitterbit/agent/.

Overview

To complete this tutorial, complete each step in order:

  1. Prerequisites: Make sure that you have the necessary software, credentials, and available agents.
  2. Create an Agent Installer User: Create a username and password that will be shared between agents and used when registering.
  3. Generate an Encrypted Username and Password: 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 Jitterbit 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 Jitterbit Harmony organization and login with admin privileges
  • A minimum of two available agents in your Harmony subscription

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 permissions (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 permissions). 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 create in section 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=

CAUTION: If you escape the username or password in the Docker command, check that value returned by the escape command matches correctly. This can be tricky:

# 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, encrypted username, password, and Agent Group ID appropriate for your Jitterbit Harmony region:

    RegionCloud URL

    NA (North America)

    https://na-east.jitterbit.com

    APAC (Asia-Pacific)

    https://emea-west.jitterbit.com

    EMEA (Europe, Middle East, Africa)

    https://apac-southwest.jitterbit.com

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

    {
      "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

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

NOTE: To stop or run the agent in background mode, use these commands:

  • To stop the agent, use Control+C or docker stop <docker-name> (You will need to note the Docker instance's container ID).
  • To run the agent in background mode, use -d when launching the agent:

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

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.

Bonus Exercise

Alternatively, 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
On This Page

Last updated:  Mar 25, 2020

  • No labels