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.

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

The OneAgent container image can also be used for deployment on Kubernetes, Google Kubernetes Engine, and Red Hat OpenShift.

Supported versions

OneAgent deployment via Docker container is supported for Docker Engine versions 1.10 - 1.13.1, 17.03+ CE and EE and is available only for Linux-based hosts. Installation within the container isn't supported. For more information, see the limitations of this deployment model.

Requirements

• Generate an environment ID and a PaaS token

  1. Sign in using your Dynatrace account.
  2. Select Deploy Dynatrace from the left-hand menu.
  3. Select Set up PaaS integration.
  4. Your environment ID appears in the Environment ID text box. You'll need this ID to link your Dynatrace account with your PaaS environment. Select Copy to copy the ID to the clipboard. You can do this at any time by revisiting this page.
  5. To generate a PaaS token, select Generate new token.
     The PaaS token is essentially an API token that's used in combination with your environment ID to download OneAgent. As you'll see, there's also a default InstallerDownload token available that you can alternatively use. However, for security reasons, it's recommended that you create several discrete tokens for each environment you have.
  6. Enter a meaningful name for your PaaS token. A meaningful token name might be the name of the PaaS platform you want to monitor (for example, azure, cloud-foundry, or openshift).
  7. Select Generate to create the PaaS token. The newly created PaaS token will appear in the list below. Select Copy to copy the generated token to the clipboard. You can do this at any time by revisiting this page and selecting Show token next to the relevant PaaS token.

  Alternatively you can use the POST a new token API call to generate a token with the InstallerDownload and SupportAlert permissions.

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

• The /opt directory must exist on the host where you deploy your OneAgent container.

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's 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:

Locate your OneAgent installer URL

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

To get your ONEAGENT_INSTALLER_SCRIPT_URL

1. Select Deploy Dynatrace from the navigation menu, select Start installation, and then Linux.
2. Determine the installer script URL and token from the UI-provided wget command:

Run OneAgent as a Docker container

To run 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>
-e ONEAGENT_INSTALLER_DOWNLOAD_TOKEN=<Api-Token>
dynatrace/oneagent --set-app-log-content-access=true <INSTALLER_PARAMETERS>

$ 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 --set-app-log-content-access=true <INSTALLER_PARAMETERS>

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.

Deploy OneAgent via a container orchestration tool

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

• Run OneAgent with Mesos/Marathon
• Run OneAgent with Kubernetes
• Run OneAgent with Elastic Container Service

Custom installation with command-line parameters

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

Security implications

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 OneAgent on the host at /opt/dynatrace.

Note: OneAgent executes these commands in the context of the container. Consequently it won't report the metrics related to the disks of underlying hosts. See the limitations below.

Limitations

• OneAgent only has access to the disks that are mounted within the container that it runs in. Therefore OneAgent can only report metrics for these container disks and not the disks of underlying hosts. This is caused by the context in which OneAgent executes its commands for gathering data.
• 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 extension can only work with the processes that run inside containers. The JMX extension 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 and DATA_STORAGE.
• There's 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.