Installing the Host Agent on Docker

Pull the Instana Agent Docker Image

The Instana Agent Docker image is available in the public Docker Hub.

docker login -u _ -p <agent_key>

# pull the dynamic image, powered by the Azul JDK
docker pull

# download the static image, powered by the Azul JDK
docker pull

# pull the dynamic image, powered by the OpenJ9 JDK
docker pull

# download the static image, powered by the OpenJ9 JDK
docker pull

Run the Instana Agent Docker Image

Docker powers a large number of platforms, like many Kubernetes-based services, DC/OS and others. Thus, the way to run the Instana Agent Docker image depends on the platform being used. Please refer to install the Instana host agent for the list of platforms where the Instana host agent can be installed.

What kind of containerized environment do you have?

You can also install the agent directly on the Linux Host, for example, if you have a specific image for your worker machines. Please note that any kind of container technology is currently only supported on Linux as the hosting OS (that means for example that Docker-Machine on Mac or Docker on Windows are not supported).

Upgrade agent container image

In some cases the Agent Container Image needs to be updated manually. For this please check Docker Hub for the image digest of the latest image tag and compare it to the one used on your installation. To check which Instana Agent docker image you have currently installed: Go to Kubernetes > "My Cluster" > Namespaces > instana-agent, select one agent pod, select the instana-agent container and compare the Image SHA on the Docker dashboard.

If you are using Helm please upgrade to the latest Helm chart:

helm upgrade --repo instana-agent --reuse-values --set agent.image.tag=latest --set agent.image.pullPolicy=Always instana-agent

If you are using the Kubernetes Yaml please delete the namespace and re-install the agent:

kubectl apply -f <your-instana-agent-daemonset.yaml>

If you have any questions please contact support.

Install via custom containers

Instana provided Agent Docker containers are build according to the definition in the Instana Agent Docker project.

While not supported by Instana, there might be reasons to further customize our Agent images. We advise to use the Instana Agent Docker project as reference.


  1. Sign in to Instana, click More -> Agents -> Instana agent installation -> Docker.

    Your agent key and host agent endpoint are pre-populated in the one-liner command.

  2. The Instana agent can be executed as a privileged container using the following command:
sudo docker run \
  --detach \
  --name instana-agent \
  --volume /var/run:/var/run \
  --volume /run:/run \
  --volume /dev:/dev:ro \
  --volume /sys:/sys:ro \
  --volume /var/log:/var/log:ro \
  --privileged \
  --net=host \
  --pid=host \
  --env="INSTANA_AGENT_KEY=your Instana agent key" \
  --env="INSTANA_AGENT_ENDPOINT=the host agent endpoint" \
  --env="INSTANA_AGENT_ENDPOINT_PORT=the host agent endpoint port" \

In the above command, you can also include the following optional variables:

  --env="INSTANA_AGENT_ZONE=the zone name of the host" \
  --env="INSTANA_AGENT_TAGS=comma separated list of host tags" \
  --env="INSTANA_DOWNLOAD_KEY=Instana download key" \
  --env="INSTANA_AGENT_UPDATES_VERSION=pin the Sensor versions to a specific SHA" \
  --env="INSTANA_AGENT_UPDATES_FREQUENCY=control the frequency at which Sensor updates are fetched" \
  --env="INSTANA_AGENT_UPDATES_TIME=control the time at which Sensor updates are fetched" \
  --env="INSTANA_AGENT_PROXY_HOST=hostname/address of a proxy" \
  --env="INSTANA_AGENT_PROXY_PORT=port of a proxy" \
  --env="INSTANA_AGENT_PROXY_PROTOCOL=proxy protocol e.g. http" \
  --env="INSTANA_AGENT_PROXY_USER=username of the proxy auth" \
  --env="INSTANA_AGENT_PROXY_PASSWORD=password of the proxy auth" \
  --env="INSTANA_AGENT_PROXY_USE_DNS=the boolean if the proxy also does DNS" \
  --env="INSTANA_GIT_REMOTE_REPOSITORY=Git remote url to be used by the host agent for Git-based configuration management, must be set if INSTANA_GIT_REMOTE_BRANCH is set" \
  --env="INSTANA_GIT_REMOTE_BRANCH=Git remote branch to be tracked by the host agent for Git-based configuration management, must be set if INSTANA_GIT_REMOTE_REPOSITORY is set" \
  --env="INSTANA_REPOSITORY_PROXY_ENABLED=enable overriding proxy settings specifically for Sensor updates" \
  --env="INSTANA_REPOSITORY_PROXY_HOST=hostname/address of a proxy for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_PORT=port of a proxy for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_PROTOCOL=proxy protocol for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_USER=username of the proxy auth for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_PASSWORD=password of the proxy auto for the Maven Sensors repo" \
  --env="INSTANA_REPOSITORY_PROXY_USE_DNS=boolean if proxy also does DNS" \
  --env="INSTANA_MVN_REPOSITORY_URL=The host name of the Maven repository for dynamic agent & sensor bundle downloads" \
  --env="INSTANA_MVN_REPOSITORY_FEATURES_PATH=The Maven repository path for feature updates" \
  --env="INSTANA_MVN_REPOSITORY_SHARED_PATH=The Maven repsotiory path for agent & sensor bundle updates"  \
  --env="INSTANA_LOG_LEVEL=either INFO, DEBUG, TRACE, ERROR or OFF; default is INFO"

Once running, the agent log is available via docker logs instana-agent. The main configuration files can be mounted into the /root directory, and will be copied in place once the agent tarball is unpacked.

Override agent configuration with volume mounts

It is possible to swap out agent configuration files via the Docker volume feature. For instance, to change the artifact repository endpoint, add the following parameter:

--volume <host-path>/org.ops4j.pax.url.mvn.cfg:/opt/instana/agent/etc/org.ops4j.pax.url.mvn.cfg

The agent's configuration.yaml provided with the image defines default values and may not be overwritten. It may be extended by custom configuration snippets named configuration-<custom-extension>.yaml like this:

--volume <host-path>/configuration-<custom-extension>.yaml:/opt/instana/agent/etc/instana/configuration-<custom-extension>.yaml

One example use case would be to have a configuration-mysql.yaml for the MySQL credentials and add this configuration file during container start.


# Mysql
  user: 'mysqlAdmin'
  password: 'mysqlSecretPassword'

docker run volume mount

--volume /opt/instana-agent/etc/instana/configuration-mysql.yaml:/opt/instana/agent/etc/instana/configuration-mysql.yaml

Configure Agent Repository Mirror

When you provide your own agent repository mirror the dynamic agent needs to be configured using INSTANA_MVN_REPOSITORY_URL, INSTANA_MVN_REPOSITORY_SHARED_PATH and INSTANA_MVN_REPOSITORY_FEATURES_PATH environment variables. Please see the example in the agent repository mirror documentation for information on which values to configure.

Agent Proxy Settings

The Instana Agent reaches out to two different endpoints; our backend system for sending all collected data, and a repository for fetching Agent and Sensor updates. Both can (separately) be configured for using proxy settings. There are 3 options:

  1. No proxy settings for both endpoints - no need to configure any proxy settings
  2. Same proxy settings for both backend and repository - only need to configure the 'Agent' proxy settings
  3. Different proxy settings for backend and repository - configure both proxies separately and make sure to set INSTANA_REPOSITORY_PROXY_ENABLED=true

For example, in case you only need to configure a proxy for the repository, use the following configuration:

  • Set all INSTANA_AGENT_PROXY_ variables to "" (empty string).
  • Set all INSTANA_REPOSITORY_PROXY_ to the proxy configuration as needed.

The same applies the other way around, when only needing a proxy for the backend and not the repository.

Updates and Version Pinning

Using the INSTANA_AGENT_UPDATES_VERSION, INSTANA_AGENT_UPDATES_FREQUENCY and INSTANA_AGENT_UPDATES_TIME environment variables, you can control whether the agent sensor versions get pinned to a specific version. This enables you to control when new updates are fetched.

See Agent Configuration documentation for more information about these settings.

Valid options for the INSTANA_AGENT_UPDATES_FREQUENCY parameter are:

  • DAY (for daily updates)

Multiple options can be supplied, separated by a colon.

Enable GPU monitoring

The following Nvidia Graphic Cards are supported.

Brand Model
Tesla S1070, S2050, C1060, C2050/70, M2050/70/90, X2070/90, K10, K20, K20X, K40, K80, M40, P40, P100, V100
Quadro 4000, 5000, 6000, 7000, M2070-Q, K-series, M-series, P-series, RTX-series
GeForce varying levels of support, with fewer metrics available than on the Tesla and Quadro products

Supported OS: Linux.


  • Minimum Docker version 19.03.
  • Latest official Nvidia drivers are installed. Drivers installed through package managers are not sufficient.
  • NVIDIA Container Toolkit is installed.

To enable GPU monitoring, start the Instana agent container on one or more GPUs. The agent can be started as a privileged container.

The agent collects metrics for all the system-wide available GPUs which are supported regardless of how many GPU(s) the agent is running.

For a detailed list of the collected metrics, see our GPU docs.

There are several ways to start the agent container using GPUs:

  • to start on all available GPUs, provide the --gpus all flag.
  • to start on the exact number of GPUs, provide the --gpus <number of gpus to use> flag.
  • to start on desired GPUs, provide the --gpus '"device=<gpu1-uuid>,<gpu2-uuid>"' flag.