Setting up agent repositories for dynamic host agents

Dynamic host agents can update themselves from the Instana agent repository, or from a mirror thereof. This topic covers how to set up a mirror of the Instana agent repository.

Notes:

  • This topic applies to only dynamic host agents, instead of static host agents. For more information about the difference between static and dynamic agents, see Host agent types.

  • The dynamic agent does not update the tracers that are updated through the mutating webhook. For more information, see Supported runtimes.

  • You cannot browse the Instana-provided repositories interactively. The backing repository redirects any JavaScript-capable browser to the feature-rich UI, which is not accessible from the public internet. If you need to list the repository contents, you can use command line tools like curl or wget to access the repository contents. An example command to list all available dynamic agent install packages for AIX on Power is as follows:

      curl https://_:<agent-key>@artifact-public.instana.io/artifactory/shared/com/instana/agent-assembly/1.0.0-SNAPSHOT/ | grep aix-ppc

For more information about how to configure dynamic host agent updates, see Updates of dynamic host agents.

Setting up an agent repository mirror

In situations where it is undesirable or impossible to make the agent communicate with the Instana hosted agent repositories, a local mirror can be created instead. Each deployed agent needs to be configured to use the mirror by following the process that is described in the section Configuring the agent repository as the mirror.

Generic repository information

The Instana host agent pulls feature definitions and updates from any Maven 2 Wagon compatible repository. When you mirror or proxy the repositories that Instana provides, the following general repository configuration applies. Two separate repositories that the agent accesses are provided to pull updates:

The mirror or proxy configuration depends on the vendor and version of your Maven 2 repository.

As an example, the following section describes how to configure Sonatype Nexus to act as an agent repository mirror. Though it's preferred, you are not required to use Nexus for your installation. Any tools that can either proxy the requests to the public download site, or serve the Maven 2 Wagon (located in the system folder of the static agent installation) is capable of acting as a mirror.

Running Nexus

If you do not have Sonatype Nexus running, probably the easiest way to get started is to use it in a Docker container (the WebUI appears on http://localhost:8081/, and the default credentials are admin/admin123):

docker run -d -p 8081:8081 --name nexus sonatype/nexus3

nexus setup

If the corresponding machine that runs the Nexus is only allowed to access the Internet by using an HTTP proxy, you can find the form to enter the credentials when you click HTTP.

HTTP

Configuring Nexus

To proxy data between the Instana Backend and the Instana Agent, two repositories are required:

  1. agent-release
  2. shared

Agent-release repository

Public png

Shared repository

Shared png

Running Artifactory

If you do not have a running Artifactory OSS, an easy way to get started is to use the vendor-provided Docker container. The UI appears on http://localhost:8082/. The default credentials are admin/password. To run this on your system, use the following command:

docker run --name artifactory -d -p 8081:8081 -p 8082:8082 docker.bintray.io/jfrog/artifactory-oss:latest

Then, create two remote repositories that are needed:

Name Format URL Username Password
instana-shared Maven2 https://artifact-public.instana.io/artifactory/shared _ ${INSTANA_AGENT_KEY}
agent-release Maven2 https://artifact-public.instana.io/artifactory/features-public _ ${INSTANA_AGENT_KEY}

Configuring the agent repository as the mirror

You can configure the Instana host agent to use the agent repository as the mirror or configure a different mirror.

To use your agent repository mirror, uncomment the following section in the <agentfolder>/etc/mvn-settings.xml file:

<mirrors>
  <mirror>
    <id>agent-release</id>
    <url>http://192.168.69.3:8081/repository/agent-release</url>
    <mirrorOf>features</mirrorOf>
  </mirror>
  <mirror>
    <id>instana-shared</id>
    <url>http://192.168.69.3:8081/repository/instana-shared</url>
    <mirrorOf>shared</mirrorOf>
  </mirror>
</mirrors>

If you require authentication for the agent repository mirror, update the following sections in the <agentfolder>/etc/mvn-settings.xml file:

<server>
  <id>agent-release</id>
  <username>myuser</username>
  <password>mypassword</password>
</server>
<server>
  <id>instana-shared</id>
  <username>myuser</username>
  <password>mypassword</password>
</server>

Changing the agent repository location for package-based host agent

You can change the agent repository location for package-based host agent instead of configuring the agent repository as the mirror.

When you install the host agent by using the One-Liner or a package-based installer, the location from which the host agent downloads updates and sensors is specified in the <agentfolder>/etc/org.ops4j.pax.url.mvn.cfg file.

To change the agent repository location, add the path to access the Maven repository. To add the path, use the org.ops4j.pax.url.mvn.repositories variable. A sample configuration for the Nexus setup on the host 192.168.69.3 on port 8081 is shown in the following example:

org.ops4j.pax.url.mvn.repositories=http://192.168.69.3:8081/repository/agent-release@id=features@snapshots@snapshotsUpdate=always,http://192.168.69.3:8081/repository/instana-shared@id=shared@snapshots@snapshotsUpdate=always

In the example, the following proxy locations for the Maven repositories are set. Each location is separated by a comma.

  • http://192.168.69.3:8081/repository/agent-release@id=features@snapshots@snapshotsUpdate=always
  • http://192.168.69.3:8081/repository/instana-shared@id=shared@snapshots@snapshotsUpdate=always

Append the Maven repository URL with the following parameters:

  • @id: The identifier for the Maven repository. The variable is optional.
  • @snapshots: The snapshots are artifacts in the Maven repository. If this parameter is set, the Instana agent is updated automatically by using the artifacts.
  • @snapshotsUpdate=always: The snapshots are updated every time an agent update runs. If this parameter is not set, the snapshots are updated only once in 24 hours and the updates might be delayed.

Changing the agent repository location for Docker-based host agent

You can change the agent repository location for Docker-based host agent instead of configuring the agent repository as the mirror. Similar to the package-based agent, the org.ops4j.pax.url.mvn.repositories parameter is used. The startup script sets the value based on the following expression:

org.ops4j.pax.url.mvn.repositories={{ getenv "INSTANA_MVN_REPOSITORY_URL" }}/{{ getenv "INSTANA_MVN_REPOSITORY_FEATURES_PATH" }},{{ getenv "INSTANA_MVN_REPOSITORY_URL" }}/{{ getenv "INSTANA_MVN_REPOSITORY_SHARED_PATH" }

To change the agent repository location, complete the following steps:

  1. Specify the base URL by using the INSTANA_MVN_REPOSITORY_URL environment variable. The variable usage is shown the following example:

    INSTANA_MVN_REPOSITORY_URL=http://192.168.69.3:8081/repository

  2. Specify a location for the host agent to download updates and sensors by using the INSTANA_MVN_REPOSITORY_FEATURES_PATH environment variable. The variable usage is shown the following example:

    INSTANA_MVN_REPOSITORY_FEATURES_PATH=agent-release@id=features@noreleases@snapshots@snapshotsUpdate=always

    The Bill of Material (BOM) of the agent is retrieved from the path. The BOM contains the list of all the features that Instana agent can use.

  3. Specify a location for the host agent to download updates and sensors by using the INSTANA_MVN_REPOSITORY_SHARED_PATH environment variable. The variable usage is shown the following example:

    INSTANA_MVN_REPOSITORY_SHARED_PATH=instana-shared@id=shared@snapshots@snapshotsUpdate=always