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 icr.io/instana/agent:latest.

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

docker login containers.instana.io -u _ -p <agent_key>

# pull the dynamic image, powered by the Azul JDK
docker pull containers.instana.io/instana/release/agent/dynamic:latest

# download the static image, powered by the Azul JDK
docker pull containers.instana.io/instana/release/agent/static:latest

# pull the dynamic image, powered by the OpenJ9 JDK
docker pull containers.instana.io/instana/release/agent/dynamic:latest-j9

# download the static image, powered by the OpenJ9 JDK
docker pull containers.instana.io/instana/release/agent/static:latest-j9

curl https://icr.io/v2/instana/agent/tags/list | jq

INSTANA_VERSION=<backend_version> && curl https://icr.io/v2/instana/agent/tags/list | 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?

• Kubernetes
• OpenShift
• Oracle OKE
• DC/OS
• Docker
• Amazon ECS

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://icr.io/instana/agent:latest-<your-architecture>-dynamic | jq '.Digest'

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

skopeo inspect docker://icr.io/instana/agent:latest-<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 https://agents.instana.io/helm 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.

Installation

1. Sign in to the Instana UI, and then select an option to display the agent catalog; for example, on the home page, click Deploy Agent.

   If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

2. Click the tile Docker

3. (Optional) If you want the host agent to be part of a custom agent zone, enter the name for the agent zone. If you enter a name in the Agent zone field, the line --env="INSTANA_AGENT_ZONE=<agent_zone>" \ is added to the agent deployment code.

4. Copy and then use the agent deployment code to run the Instana agent as a privileged container:

   The Instana UI provides the agent deployment code as follows:

   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_ENDPOINT=<the_host_agent_endpoint>" \
     --env="INSTANA_AGENT_ENDPOINT_PORT=<the_host_agent_endpoint_port>" \
     --env="INSTANA_AGENT_KEY=<your_instana_agent_key>" \
     --env="INSTANA_AGENT_DOWNLOAD_KEY=<your_instana_agent_download_key>" \
     icr.io/instana/agent
   

   Your agent key, download key, and host agent endpoint are pre-populated in the agent deployment code.

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

docker logs instana-agent

Checking the status of the host agent

After you install the host agent, you can check the status of the host agent in the Instana UI or on the host. For more information, see Checking the status of the host agent.

Agent Configuration

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

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

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

# Mysql
com.instana.plugin.mysql:
  user: 'mysqlAdmin'
  password: 'mysqlSecretPassword'

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

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

Troubleshooting agent deployment

If installing the agent is not successful at first, you can check log messages and troubleshooting tips. If this troubleshooting section does not answer the questions you have, contact the IBM Instana support team with information about your experience, so that we can help you and update our documentation accordingly.

For troubleshooting information that is general to all host agents, see Managing host agents / Troubleshooting.