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>
docker pull
#downloads the latest version of the dynamic agent
docker pull
#downloads the latest version of the static agent

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 repo update
helm upgrade instana-agent --reuse-values --set agent.image.tag=latest --set agent.image.pullPolicy=Always stable/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

While the agent container provided by Instana will get you started quickly, it does not offer all the configuration options a regular agent download has.

For users who want to build their own, fully customized, Agent container, here are some guidelines:

  • The Instana Agent container is based off ubuntu:18.04. Other supported OS work as well.
  • If running alpine, add glibc support to it.
  • Add docker support to the container.
  • Extract a JDK into the container. The Instana Agent container uses the Azul Zulu JVM.
  • You can also use a preconfigured Linux with Java, like alpine with Oracle by
  • Download the agent as described in Manual Agent Installation.
  • Extract and configure it in the container.
  • To support standard container logging integration, the file logging should be deactivated and console logging activated.
  • Run the agent with: exec /instana-agent/bin/karaf daemon.
  • By using exec + the daemon flag, the process will correctly handle the restart signals.

Easy configuration override

FROM instana/agent

COPY my-configuration.yaml /root/configuration.yaml
COPY my-mvn-settings.xml.tmpl /root/mvn-settings.xml.tmpl
COPY com.instana.agent.main.sender.Backend-1.cfg.tmpl /root/com.instana.agent.main.sender.Backend-1.cfg.tmpl
docker build -t myrepro/newagent .
docker push myrepro/newagent:devtag

For reference, see the GitHub Docker project that Instana utilizes to build the dynamic, static and RHEL Docker agents.


  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 \
  --volume /sys:/sys \
  --volume /var/log:/var/log \
  --privileged \
  --net=host \
  --pid=host \
  --ipc=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_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"  \

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

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, incase 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.