How do I deploy Dynatrace OneAgent as a Docker container?

This topic explains how to run OneAgent as a Docker container, as opposed to the standard script-based Linux installation approach.

Note
To monitor applications that run in Docker containers, run Dynatrace OneAgent on the host—either as a separate container or by installing Dynatrace OneAgent on the host. You don't need to embed OneAgent into any of your Docker images or inherit it from a special base image.

Supported versions

Feature Versions
Direct deployment via Docker1 1.10 - 1.13.1, 17.03+ CE and EE
Kubernetes 1.3.1 - 1.9.2, 1.10.x, 1.11.x
OpenShift Container Platform 3.4, 3.5, 3.6, 3.7, 3.9, 3.10

1 OneAgent deployment via a Docker container is only available for Linux-based hosts. Installation within the container isn't supported. Please see the limitations of this deployment model.

Requirements

  • You need Dynatrace environment credentials.

  • Your Docker environment must allow your OneAgent container to run in privileged mode.

Note:
Starting from the image version 1.11.1000, OneAgent Docker image no longer ships with the OneAgent installer contained within it. Instead the installer is downloaded from your environment during the image startup process. The image is forward compatible with new OneAgent versions and there is no specific link between the OneAgent version and the image version. The only dependency that exists is a requirement for a minimum supported OneAgent version for a given image version. For details see the table below:

Image version Minimum required OneAgent version
1.11.1000 - 1.12.1000 1.119
>= 1.13.1000 1.139

Locate your Dynatrace OneAgent installer URL

The first step is to obtain the location for ONEAGENT_INSTALLER_SCRIPT_URL. This information is presented to you during Dynatrace OneAgent installation.

To get your ONEAGENT_INSTALLER_SCRIPT_URL

  1. Select Deploy Dynatrace from the navigation menu.
  2. Click Start installation and select Linux.
  3. Copy the URL, shown below. This is your ONEAGENT_INSTALLER_SCRIPT_URL.

Run Dynatrace OneAgent as a Docker container

To run Dynatrace OneAgent as a Docker container you need to execute the following docker run command on all your Docker hosts:

$ docker run -d --restart=unless-stopped --privileged=true --pid=host --net=host --ipc=host -v /:/mnt/root -e ONEAGENT_INSTALLER_SCRIPT_URL="REPLACE_WITH_YOUR_URL" dynatrace/oneagent APP_LOG_CONTENT_ACCESS=1 <INSTALLER_PARAMETERS>

Be sure to replace REPLACE_WITH_YOUR_URL placeholder with the Dynatrace OneAgent installer URL as explained above.

Note:
Once the container is started, a regular OneAgent full-stack installer is executed and OneAgent files are deployed to the underlying file system of the machine running the container. The installation package and associated shell script are downloaded from your environment upon container startup, using the URL provided for launching the container. The signature of the installer is verified automatically following the download.

Using a container orchestration tool

If you use a container orchestration tool, your orchestrator can deploy the Dynatrace OneAgent container for you. The example snippets below show you how to take advantage of orchestration tools in deploying Dynatrace OneAgent to all your nodes.

Custom installation with command line parameters

You can alternatively perform a custom installation with command line parameters.

Security implications

Dynatrace OneAgent is what is referred to as a "super-privileged container." It's designed to have almost complete access to the host system as a root user. The following Docker command options open selected privileges to the host:

--ipc=host - Allows processes running inside the container to directly access the host’s IPC namespace.

--net=host - Allows processes running inside the container to directly access host network interfaces.

--pid=host - Allows processes running inside the container to see and work with all processes in the host process table.

-v /:/mnt/root - Mounts the host's root directory into the container at /mnt/root to enable the installation of Dynatrace OneAgent on the host at /opt/dynatrace.

Supported technologies

Running Dynatrace OneAgent as a Docker container gives you full-stack visibility into your complete containerized environment. This includes deep monitoring of supported applications, services, and databases.

Updates

To update Dynatrace OneAgent you need only to restart the container using the following command

$ docker restart oneagent

provided that you have added the parameter --name=oneagent in the suggested Docker run command (see above).

The OneAgent Docker image will automatically fetch the latest version of Dynatrace OneAgent. If you've specified a default OneAgent install version for new hosts and applications in your OneAgent updates settings, the OneAgent Docker image will automatically fetch the defined default version of Dynatrace OneAgent. Please note that when Dynatrace OneAgent is deployed as a Docker image, Dynatrace OneAgent auto-update isn't supported.

Limitations

  • Deep monitoring for native (i.e., non-containerized) processes on hosts is disabled. The injection file ld.so.preload on the host file system isn't modified, and therefore the automatic injection into processes running outside of containers isn't possible.
  • Because of this, the JMX plugin can only work with the processes that run inside containers. The JMX plugin is tightly coupled with deep monitoring of Java processes.
  • Capturing of application crashes and core dumps via oneagentdumpproc isn't supported.
  • OneAgent isn't registered in the system's autostart. Lifetime and startup of the container with OneAgent processes is managed by Docker.
  • All the command line parameters of the installer are supported, with the exception of INSTALL_PATH.
  • There is a startup dependency between the container in which OneAgent is deployed and application containers to be instrumented (i.e., which have deep process monitoring enabled). The OneAgent container must be started and the oneagenthelper process must be running prior to the application container being launched so that the application can be properly instrumented.