Installing the agent on Docker

To install and configure the Instana agent on Docker, pull the Instana agent container image and run it, and then install and run the Instana host agent as a privileged container.

Pulling the Instana agent container image

You can find the Instana agent image in the public IBM Cloud Container Registry at icr.io/instana/agent:latest.

In addition, you can also get dynamic and static agent images from the Instana Container Registry at containers.instana.io.

To pull the latest Instana agent image, complete the following steps:

  1. Log in with your agent key:
docker login containers.instana.io -u _ -p <agent_key>
  1. Pull the required image by using the suitable command from the following list:
# 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

Listing available tags

To list the available image tags, query the icr.io public tag list. The image tags can be used with the icr.io public registry and the containers.instana.io 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 https://icr.io/v2/instana/agent/tags/list | 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 https://icr.io/v2/instana/agent/tags/list | jq '.tags[] | select(. | contains ("'"$INSTANA_VERSION"'"))'

Running the Instana agent container image

Docker supports multiple platforms such as many Kubernetes-based services, DC/OS, and others. The method to run the Instana agent Docker image depends on the platform.

See the list of containerized environments on which you can install the Instana host agent:

You can also install the agent directly on the Linux Host (for example, if you have a specific image for your worker machines).

Upgrading the Instana agent container image

To manually update the agent container image, run the following command:

skopeo inspect docker://icr.io/instana/agent:latest-<your-architecture>-dynamic | jq '.Digest'

Replace <your-architecture> with amd64, arm64, s390x or ppc64le, according to your architecture.

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'

To check the Instana agent docker image that you currently installed, go to Kubernetes > My Cluster > Namespaces > instana-agent, and then 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, run the following command:

helm pull --repo https://agents.instana.io/helm --untar instana-agent && kubectl apply -f instana-agent/crds && helm upgrade --repo https://agents.instana.io/helm instana-agent --reuse-values --set agent.image.tag=latest --set agent.image.pullPolicy=Always instana-agent

The Instana Helm chart deploys the instana-agent-operator internally, which then deploys the agent resources. This deployment is based on the agent custom resource (CR), which is created based on the Helm values. The operator pattern requires a custom resource definition (CRD) in the cluster before defining any custom resources. Therefore, the Helm chart includes the required CRD, which is deployed during the initial installations before submitting other artifacts.

Currently, Helm can handle only the initial installations of CRDs and not their upgrade, deletion, and uninstallation. Because of this limitation, CRD updates are automatically submitted to the cluster only during the initial installation and not during the upgrades. For more information on this limitation, see Custom Resource Definitions.

If you are using the Kubernetes YAML, delete the namespace and re-install the agent:

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

Installing the agent

  1. On the Instana UI home page, click Deploy Agent.

  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, use the following command to generate the agent logs:

docker logs instana-agent