Setting up agent repositories for dynamic host agents

Dynamic host agents update either from the Instana agent repository or from a mirror. See the following sections to learn how to set up agent repositories for dynamic host agents.

Notes:

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

You cannot directly access the Instana agent repository UI and get the agent packages. Instead, use a curl or wget command to request to list all available packages in the repository. When you run the command, the repository verifies your agent key and provides you with the agent packages. See the following example command to list all available dynamic agent installation packages for AIX on Power:
```
curl https://_:@artifact-public.instana.io/artifactory/shared/com/instana/agent-assembly/1.0.0-SNAPSHOT/ | grep aix-ppc
```

For more information about configuring dynamic host agent updates, see Updates of dynamic host agents.

To set up agent repositories for dynamic host agents, first you must set up an agent repository mirror.

Then, you can use three different approaches:

Configuring the agent repository as the mirror
Change the agent repository location for package-based host agent
Change the agent repository location for Docker-based host agent

Setting up an agent repository mirror

In certain instances where the agent cannot communicate directly with the Instana agent repositories (for example, air-gapped deployments), you can create a local mirror of the repository and configure the dynamic agent to get packages from the mirror. You must configure each deployed agent to use the mirror. For more information, see 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 Instana agent repositories, the following general repository configuration applies. The agent accesses the following two repositories to pull the updates:

Repository Name: agent-release

Remote Repository: https://artifact-public.instana.io/artifactory/features-public
Repository Name: instana-shared

Remote Repository: https://artifact-public.instana.io/artifactory/shared

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

Sonatype Nexus is preferred to use as the agent repository mirror. However, you can choose any tool that can act as a mirror. The chosen tool must 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).

If you choose Nexus, see the following sections to learn how to use it as the agent repository mirror.

Step 1: Running Nexus

If you do not have Sonatype Nexus running, get started by running it in a Docker container.

Run the following command to access the Nexus Repository Manager:

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

Use the following default credentials:

Username: admin Password: admin123

nexus setup

If the corresponding computer that runs the Nexus is only allowed to access the network by using an HTTP proxy, click HTTP to open the form to enter the credentials.

HTTP

Step 2: Configuring Nexus

To proxy data between the Instana backend and the Instana agent, you need to set up the following two repositories:

Agent-release repository
Shared repository

To set up a repository, in the Nexus Repository Manager, click Create repository and enter the configuration details.

Agent-release repository configuration

Name: agent-release
Format: Maven2
Type: Proxy
Version Policy: Mixed
Layout Policy: Permissive
Remote Storage: https://artifact-public.instana.io/artifactory/features-public
Username: _
Password: ${INSTANA_AGENT_KEY}

Shared repository configuration

Name: instana-shared
Format: Maven2
Type: Proxy
Version Policy: Mixed
Layout Policy: Permissive
Remote Storage Location: https://artifact-public.instana.io/artifactory/shared
Username: _
Password: ${INSTANA_AGENT_KEY}

Step 3: Running Artifactory

If you do not have a running Artifactory OSS, get started by using the vendor-provided Docker container.

Run the following command to access the user interface:

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

Use the default credentials:

Username: admin Password: password

Then, create two remote repositories:

Table 1: Remote repositories
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, open the <agentfolder>/etc/mvn-settings.xml file and uncomment the following section:

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

If you install the agent in a Kubernetes environment, you can use the following flags in the operator or helm chart installations. The agentRelease flags correspond to the agent-release server and the instanaShared flags correspond to the instana-shared server. For more information about the repositories, see Generic repository information.

agent.agentReleaseRepoMirrorUrl
agent.agentReleaseRepoMirrorUsername
agent.agentReleaseRepoMirrorPassword
agent.instanaSharedRepoMirrorUrl
agent.instanaSharedRepoMirrorUsername
agent.instanaSharedRepoMirrorPassword

If you install the agent on Docker, you can use the following environment variables to configure the mirroring:

AGENT_RELEASE_REPOSITORY_MIRROR_URL
AGENT_RELEASE_REPOSITORY_MIRROR_USERNAME
AGENT_RELEASE_REPOSITORY_MIRROR_PASSWORD
INSTANA_SHARED_REPOSITORY_MIRROR_URL
INSTANA_SHARED_REPOSITORY_MIRROR_USERNAME
INSTANA_SHARED_REPOSITORY_MIRROR_PASSWORD

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. See the following configuration example of the Nexus setup on the host 192.168.69.3 and port 8081:

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:

Specify the base URL by using the INSTANA_MVN_REPOSITORY_URL environment variable. See the following example:
```
INSTANA_MVN_REPOSITORY_URL=http://192.168.69.3:8081/repository
```
Specify a location for the host agent to download updates and sensors by using the INSTANA_MVN_REPOSITORY_FEATURES_PATH environment variable. See 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.
Specify a location for the host agent to download updates and sensors by using the INSTANA_MVN_REPOSITORY_SHARED_PATH environment variable. See the following example:
```
INSTANA_MVN_REPOSITORY_SHARED_PATH=instana-shared@id=shared@snapshots@snapshotsUpdate=always
```