Installing Enterprise Agents with Docker

ThousandEyes Enterprise Agents can be installed within a Docker container running a 64-bit Linux distribution, if the OS uses kernel version 3.10 or later, and supports both cgroups and network namespaces.

ThousandEyes recommends using Ubuntu 20.04 LTS for Docker agents.

This article provides the installation instructions for Enterprise Agents in Docker containers.

Docker installations are considered a self-managed option. They can be used at your own risk, if your team has sufficient resources to manage the deployment.

As a part of container package best practices, we recommend updating your container regularly.

ThousandEyes does not support Docker for macOS or Docker for Windows for production deployments.

Prerequisites

Users will need the correct permissions to add new Enterprise Agents to the account group. For more information, see Role-Based Access Control, Explained.

Deployment Options

You can choose between two different deployment options: the full Enterprise Agent (with BrowserBot for browser synthetics testing), or the base agent, that does not include BrowserBot.

Additional system requirements (such as larger flash storage) are needed for BrowserBot installation (required for page load and transaction tests). ThousandEyes recommends performing a small proof-of-concept before committing to a larger deployment platform.

Docker-based Enterprise Agents can be transitioned between including/not including BrowserBot via the command line. For instructions, see Add / Remove BrowserBot from Existing Docker Enterprise Agents.

Installing the Enterprise Agent Image

The instructions below assume that you have installed and validated the Docker container.

  1. Log into the ThousandEyes platform with a user account that has edit agent permissions.

  2. Navigate to Cloud & Enterprise Agents > Agent Settings.

  3. Click Add New Enterprise Agent.

  4. Select the Docker tab.

  5. Enter a name for your agent in the textbox. The agent name should not contain underscores or spaces.

  6. Define the folder on the Docker host where persistent agent files will be stored (e.g. /opt). The folder will be created automatically upon agent instantiation, and log content will be sent here.

  7. [Optional] Select a proxy configuration by clicking Static or PAC, then input the relevant proxy information. For more information, see Configuring an Enterprise Agent to Use a Proxy Server.

  8. If you are installing the Enterprise Agent with BrowserBot, leave the Install with BrowserBot support box checked. If you wish to install only the base agent, uncheck the box.

  9. Once these steps are completed, the code snippet/s will be updated with the set of commands you will need to copy and paste into the CLI of your Docker host. We recommend saving the commands locally, in case you need to reinstall the Docker image without changing the Enterprise Agent configuration.

The screenshot below shows an example configuration that includes BrowserBot:

The first set of commands are for configuring seccomp and AppArmor profiles for your Docker host, and are only necessary if you have chosen to install BrowserBot. For more information on these requirements, see Support for Page Load and Transaction Tests.

If the Docker host supports SELinux, you may have to disable it to run page load and transaction tests.

The second set of commands will install and set up the Enterprise Agent. Once these commands have been run, your Docker-based Enterprise Agent will be installed and start running. The Enterprise Agent will be restarted automatically upon Docker host restart.

You may receive a WARNING: Your kernel does not support swap limit capabilities, memory limited without swap message when issuing the docker run command. You can safely continue, as this will not affect your Enterprise Agent installation.

The Enterprise Agent container will be automatically connected to the default docker0 network bridge and assigned a private IP address. The container uses network address translation (NAT) to the Docker host default interface to connect the Enterprise Agent to the network. No additional network configuration is required.

Stopping, Starting, and Restarting the Enterprise Agent

After installing the image, you can verify that the Enterprise Agent is running by using the docker ps command:

docker ps

Output should be similar to:

CONTAINER ID IMAGE                         COMMAND         CREATED        STATUS      PORTS NAMES
400b4ad7bb34 thousandeyes/enterprise-agent "/sbin/my_init" 2 minutes ago  Up 2 minutes      <agent-name>

You can stop the container by running the following command:

docker stop <agent-name>

NOTE: If you stop the container using the docker stop command, the container will not automatically restart upon Docker host restart.

To verify that the agent has been stopped, run docker ps -a. This shows the status of all containers, including stopped ones.

docker ps -a

Output should be similar to:

CONTAINER ID IMAGE                         COMMAND         CREATED        STATUS               NAMES
400b4ad7bb34 thousandeyes/enterprise-agent "/sbin/my_init" 2 minutes ago  Exited (0) 5 sec ago <agent-name>

You can start the agent container by using docker start:

docker start <agent-name>

NOTE: The Enterprise Agent container will automatically restart upon Docker host reboot if started with the docker start command.

Removing an Enterprise Agent

To remove an Enterprise Agent container, use the docker rm command.

Note: use -v to remove anonymous Docker volumes that may be associated with the Enterprise Agent container.

docker rm -fv <agent-name>

If you're permanently removing an Enterprise Agent, delete the persistent volumes as well. If you're just updating the container, running docker start will automatically update the container to the latest version.

To remove the persistent volumes on your Docker host:

rm -Rf <host-os-agent-folder>/thousandeyes/<agent-name>

Reinstalling the Enterprise Agent

You can easily remove and reinstall Enterprise Agent containers. You may need to reinstall the Enterprise Agent in a case of serious Enterprise Agent failure and/or when suggested to do so by ThousandEyes Support. All persistent data for the Enterprise Agent is stored in the persistent volumes on the host. As long as you keep the agent-name consistent, and persistent volumes on the host the same, the Enterprise Agent will keep its data and same identity in the ThousandEyes platform, even if you remove the container and replace it with a new one.

To reinstall the Enterprise Agent, do the following:

  1. Ensure you have the latest Enterprise Agent image on your host by running the following command on the Docker host:

    docker pull thousandeyes/enterprise-agent

  2. Log into ThousandEyes, and navigate to Cloud & Enterprise Agents > Agent Settings.

  3. Click + Add New Agent to open the form.

  4. Click Docker* for the Package Type setting.

  5. Enter a name for your Enterprise Agent, which must be the same as the name of currently running Enterprise Agent you want to reinstall.

  6. Enter a folder on the Docker host where persistent files for the existent Enterprise Agent are already stored (e.g. /opt).

  7. (Optional) If your Docker agent will be running page load or transaction tests, do the following:

    1. On the +Add New Agent form, select Install with BrowserBot support.

    2. Copy the commands shown in the upper text box, and run them at the command line of your Docker host.

      These commands configure seccomp and AppArmor profiles for your Docker host. For information on these requirements, see Support for Page Load and Transaction Tests.

    3. Additionally, if your Docker host supports SELinux, you may need to disable it in order to run page load or transaction tests.

  8. Copy the commands generated for your container in the + Add New Agent form, then paste and run them in the command line of your Docker host.

Warning: Removing data from persistent volumes on the host (host-os-agent-folder/thousandeyes/agent-name/*) will result in reinitialization of the agent. The agent will register as a new agent in ThousandEyes.

Agent System Time

Docker containers use the host system kernel clock. Enterprise Agent containers cannot alter the clock. If an agent's system time is offset, you need to adjust host system time, ideally by configuring valid NTP servers on the host system.

Advanced DNS Configuration

Enterprise Agent containers use the host's DNS settings by default. You can configure a different set of DNS servers for the Enterprise Agent, if needed. When using the docker run command upon Enterprise Agent installation, add the --dns=<dns-server> parameter before the last line. If you need to add multiple servers, repeat the command:

--dns=8.8.8.8 \
--dns=8.8.4.4 \
thousandeyes/enterprise-agent /sbin/my_init

Exposing Ports for Agent-to-Agent Tests

If you are connecting your Docker-based Enterprise Agent to the world using the NAT network (which is Docker default), agent-to-agent tests targeting your Docker agent will not work out of the box. To enable the agent-to-agent test traffic to reach your Docker agent hosted behind a NAT network, relevant ports need to be exposed and published. To achieve this, add the following parameters to your docker run command:

--expose=49152/udp \
--expose=49153/udp \
--expose=49153/tcp \
--publish=49152:49152/udp \
--publish=49153:49153/udp \
--publish=49153:49153/tcp \
thousandeyes/enterprise-agent /sbin/my_init

Agent Proxy Configuration

Customers deploying ThousandEyes Enterprise Agents behind a proxy may need proxy-specific configuration for the Enterprise Agent in order to use certain tests, report test data to the ThousandEyes collector, and perform software package updates.

You should configure proxy settings upon Enterprise Agent installation. See the Deploying a Docker Agent section of Installing Enterprise Agents in Proxy Environments for instructions on installing Docker.

You can verify the proxy settings of a running agent by running the following command on the Docker host:

docker exec <agent-name> cat /etc/te-agent.cfg | grep proxy

You cannot change the proxy configuration of a currently running agent. You must reinstall the agent with a new proxy configuration. See Reinstalling the Enterprise Agent.

Support for Page Load and Transaction Tests

Prior to BrowserBot 2, the requirements outlined in this section applied only to agents running transaction tests.

The following should be considered during container deployment:

seccomp Security computing mode is a Linux kernel feature used to restrict container actions. The Docker community has documented how seccomp is used with containers. ThousandEyes provides a seccomp file that you can use to configure seccomp when deploying containers.

AppArmor configuration AppArmor is a mandatory access control (MAC) system used to limit an application's access to resources. AppArmor is currently the default MAC system for the Debian, Ubuntu, SuSE, and Arch Linux distributions.

SELinux configuration SELinux is a mandatory access control (MAC) system used to limit an application's access to resources. SELinux is currently the default MAC system for Red Hat Enterprise, CentOS, Fedora, Oracle, and Gentoo Linux distributions.

user.max_user_namespaces Distributions that share a common code base with Red Hat Enterprise Linux 7 may have a default user.max_user_namespaces value of 0, or may simply leave this feature disabled. The Docker community has documented how this issue affects container deployment along with common resolutions. In point release 7.6 and up, the user.max_user_namespaces value simply needs to be increased for proper operation. This feature is also required when running a container as a user other than root.

snap Note that Docker installed via Ubuntu's snap tool is not supported. Users should install Docker as suggested by the official Docker documentation at docs.docker.com.

Example Deployment (New Agent)

Operating Systems Using seccomp or AppArmor

ThousandEyes provides a Bash script to configure existing Docker environments to run transaction tests. If your Docker host relies on seccomp or AppArmor, do the following:

  1. Download the script.

    curl -Os https://downloads.thousandeyes.com/bbot/configure_docker.sh

  2. Make the script executable.

    chmod +x configure_docker.sh

  3. Execute the script (requires sudo and curl).

    sudo ./configure_docker.sh

    The script creates a working directory, /var/docker/configs, and downloads some recommended configuration files for seccomp and AppArmor, if supported, on your Docker host.

    If AppArmor is installed on the Docker host, the script applies the given configuration using apparmor_parser.

Operating Systems Using SELinux

Setting SELinux to "permissive" mode allows applications to run while logging any activity that would violate the system's current SELinux profile.

Before returning SELinux to "enforcing" mode, review the SELinux logs to see if your profile should be updated.

Next, deploy your agent using the the modified run command. For example:

 docker run \
    --hostname='<AGENT NAME>' \
    --memory=2g \
    --memory-swap=2g \
    --detach=true \
    --tty=true \
    --shm-size=512M \
    -e TEAGENT_ACCOUNT_TOKEN=<ACCOUNT TOKEN> \
    -e TEAGENT_INET=4 \
    -v '/var/docker/thousandeyes/<AGENT NAME>/te-agent':/var/lib/te-agent \
    -v '/var/docker/thousandeyes/<AGENT NAME>/te-browserbot':/var/lib/te-browserbot \
    -v '/var/docker/thousandeyes/<AGENT NAME>/log/':/var/log/agent \
    --cap-add=NET_ADMIN \
    --cap-add=SYS_ADMIN \
    --name '<AGENT NAME>' \
    --restart=unless-stopped \
    --security-opt seccomp=/var/docker/configs/te-seccomp.json \
    --security-opt apparmor=docker_sandbox \
    thousandeyes/enterprise-agent /sbin/my_init

Troubleshooting and Log Information

If you're directed by ThousandEyes Customer Engineering team to pull log files for the agent, the logs are found in the persistent volume, under the thousandeyes/agent-name/log folder. The agent log file is called te-agent.log, and this file rolls over automatically. You can tail this log from the Docker host using the tail -f command. An example is found below, assuming /opt was the persistent storage location supplied, and agent-name is the name of the agent:

tail -f /opt/thousandeyes/agent-name/log/te-agent.log

FAQ

Question: How do I connect to the agent shell for Docker agents?

Answer: To access the agent shell, run one of the following commands:

docker exec -it <thousandeyes/enterprise-agent> /bin/bash -l
docker exec -it <AGENT-NAME> /bin/bash -l

To verify the agent is running, you can use the sv status te-agent command, which should return similar output to the example below:

$ sv status te-agent
run: te-agent: (pid 653) 79389s

Additional commands include:

  • Start the agent: sv start te-agent

  • Stop the agent: sv stop te-agent

For more information on configuration options and troubleshooting, see:

PreviousDocker AgentsNextCloud Templates

Last updated