Installing the Host Agent on Docker

Pulling the Instana agent container image

The Instana Agent image is available from the public IBM Cloud Container Registry at

In addition, dynamic and static Agent images are available from our Instana Container Registry at Log in with your agent key and pull the appropriate image:

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

Listing available tags

To list the available image tags, query the public tag list. The image tags can be used with the public registry and the Instana registry.

You need the command-line tools Curl to query and jq to filter the output. Enter the following command to list all the available tags:

curl | jq

To filter the tags by an Instana backend version, enter the following command. Enter the Instana version in place of <backend_version> in the following example:

INSTANA_VERSION=<backend_version> && curl | jq '.tags[] | select(. | contains ("'"$INSTANA_VERSION"'"))'

Running the Instana agent container 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).

Upgrading the Instana agent container image

In some cases, you need to run the following command to manually update the Agent Container Image. Replace <your-architecture> with one of amd64, arm64, s390x or ppc64le, according to your architecture:

skopeo inspect docker://<your-architecture>-dynamic | jq '.Digest'

If you are running the OpenJ9 variant, run the following command:

skopeo inspect docker://<your-architecture>-dynamic-j9 | jq '.Digest'

Compare it with the one that you use 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 then compare the Image SHA on the Docker dashboard.

If you are using Helm 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 delete the namespace and re-install the agent:

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

If you have any questions contact support.

Installing by using 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" \

Once running, the agent log is available by using the following command:

docker logs instana-agent

Agent Configuration

In addition to the required environment variables, additional variables can be configured during startup:

Variable Name Required Default Value Comment
INSTANA_AGENT_KEY Yes N/A Your Instana agent key.
INSTANA_AGENT_ENDPOINT Yes N/A The host agent endpoint.
INSTANA_AGENT_ENDPOINT_PORT Yes N/A The host agent endpoint port.
INSTANA_AGENT_ZONE No N/A The zone name of the host.
INSTANA_AGENT_TAGS No N/A Comma-separated list of host tags.
INSTANA_DOWNLOAD_KEY No N/A Your Instana download key.
INSTANA_AGENT_UPDATES_VERSION No N/A Pin the Sensor versions to a specific SHA. For more information, see Updates and version pinning.
INSTANA_AGENT_UPDATES_FREQUENCY No DAY Control the frequency at which Sensor updates are fetched. For more information, see Updates and version pinning.
INSTANA_AGENT_UPDATES_TIME No 04:30 Control the time at which Sensor updates are fetched. For more information, see Updates and version pinning.
INSTANA_AGENT_PROXY_HOST No N/A The hostname/address of a proxy.
INSTANA_AGENT_PROXY_PORT No N/A The port of a proxy.
INSTANA_AGENT_PROXY_PROTOCOL No N/A The proxy protocol, such as http.
INSTANA_AGENT_PROXY_USER No N/A The username of the proxy auth.
INSTANA_AGENT_PROXY_PASSWORD No N/A The password of the proxy auth.
INSTANA_AGENT_PROXY_USE_DNS No false Boolean if the proxy also does DNS.
INSTANA_GIT_REMOTE_REPOSITORY No N/A Git remote URL to be used by the host agent for Git-based configuration management. The variable must be set if INSTANA_GIT_REMOTE_BRANCH is set.
INSTANA_GIT_REMOTE_BRANCH No N/A Git remote branch to be tracked by the host agent for Git-based configuration management. The variable must be set if INSTANA_GIT_REMOTE_REPOSITORY is set.
INSTANA_REPOSITORY_PROXY_ENABLED No N/A Enable overriding proxy settings specifically for Sensor updates.
INSTANA_REPOSITORY_PROXY_HOST No N/A The hostname/address of a proxy for the Maven Sensors repository.
INSTANA_REPOSITORY_PROXY_PORT No N/A The port of a proxy for the Maven Sensors repository.
INSTANA_REPOSITORY_PROXY_PROTOCOL No N/A The proxy protocol for the Maven Sensors repository.
INSTANA_REPOSITORY_PROXY_USER No N/A The username of the proxy auth for the Maven Sensors repository.
INSTANA_REPOSITORY_PROXY_PASSWORD No N/A The password of the proxy auth for the Maven Sensors repository.
INSTANA_MVN_REPOSITORY_URL No N/A The host name of the Maven repository for dynamic agent & sensor bundle downloads. For more information, see Configuring agent repository mirror).
INSTANA_MVN_REPOSITORY_FEATURES_PATH No N/A The Maven repository path for feature updates. For more information, see Configuring agent repository mirror).
INSTANA_MVN_REPOSITORY_SHARED_PATH No N/A The Maven repository path for agent and sensor bundle updates. For more information, see Configuring agent repository mirror).

The main configuration files can be mounted into the /root directory, and will be copied in place once the agent tarball is unpacked.

Overriding agent configuration with volume mounts

It is possible to swap out agent configuration files by using the Docker volume feature. The agent's configuration.yaml provided with the image defines default values and might not be overwritten. It might 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

Configuring multiple backends

The Instana host agent can be configured to report to multiple backends. For general considerations and notes about the configuration, see Configuring multiple backends.

The Instana host agent container images are specially configured so that adding extra backends can be easily done by mounting the backend files, such as com.instana.agent.main.sender.Backend-2.cfg.

An example argument for a containerized agent is as follows:

--mount type=bind,source=<path-to-additional-backend-config>,target=/opt/instana/agent/etc/instana/com.instana.agent.main.sender.Backend-2.cfg

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

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