Dynamic agent Maven repositories

Dynamic Instana agents require access to a Maven repository to download features, sensors, and updates.

By default, dynamic agents are configured to use the following repository:

  • Repository Name: shared
  • URL: https://artifact-public.instana.io/artifactory/shared
  • Authentication:
    • Username: _
    • Password: Your Instana download key

Using dynamic agents in environments where the shared repository is not reachable (for example, in air-gapped environments) requires a custom agent configuration and a reachable mirror of the Maven repository. This requirement applies only to dynamic agents because static agents do not require access to Maven repositories. For more information about agent updates, see Updates of dynamic host agents.

Note:
Before May 2026, dynamic agents were configured with two Maven repositories: shared and features. The features repository is no longer required because all necessary artifacts are now available in the shared repository. However, the configuration mechanisms for the features repository are still supported for compatibility with earlier versions. For more information, see Legacy Maven repository configuration.

Creating a Maven repository mirror

You can use any Maven 2 Wagon - compatible repository to create a mirror of the Instana Maven repository.

The following sections describe repository mirror configurations for repository managers: Sonatype Nexus (recommended) and JFrog Artifactory.

The repository mirror must have access to the Instana Maven repository over the network.

Sonatype Nexus

First, prepare a self-hosted Nexus instance as described in the Nexus documentation.

Next, create a new repository in Nexus with the following configuration:

  • Recipe: maven2 (proxy)
  • Name: instana-shared
  • Version policy: Mixed
  • Layout policy: Permissive
  • Remote storage: https://artifact-public.instana.io/artifactory/shared
  • Authentication: Enabled
    • Authentication type: Username
    • Username: _
    • Password: Your Instana download key

JFrog Artifactory

First, prepare a self-hosted Artifactory instance as described in the Artifactory documentation.

Next, create a new remote repository in Artifactory with the following configuration:

  • Package Type: Maven
  • Repository Key: instana-shared
  • URL: https://artifact-public.instana.io/artifactory/shared
  • Username: _
  • Password: Your Instana download key
  • Repository Layout: maven-2-default

Configuring the agent

After you set up a Maven repository mirror, configure your dynamic agents to use the mirror. The Instana agent uses the following configuration files to manage Maven repository access:

  • org.ops4j.pax.url.mvn.cfg configures the main repositories.
  • mvn-settings.xml configures repository mirrors for the repositories that are defined in org.ops4j.pax.url.mvn.repositories. The file also configures credentials for both the repositories and their mirrors.

Containerized agents provide container environment variables and Kubernetes or Helm configuration parameters to adjust the relevant settings in the configuration files. These mechanisms eliminate the need to manually edit configuration files in containers.

You can customize the dynamic agent Maven configuration in two ways:

Configuring Maven repository mirrors

Non-containerized agents

To configure a non-containerized agent to use a mirrored Maven repository, open the <instana-agent-dir>/etc/mvn-settings.xml file, then uncomment and adjust the <mirrors> section: 
<mirrors>
  <mirror>
    <id>instana-shared</id>
    <url>https://repo.example.com/artifactory/instana-shared</url>
    <mirrorOf>shared</mirrorOf>
  </mirror>
</mirrors>

Replace the example URL with the actual URL of your repository mirror.

If your mirror requires authentication, add the credentials to the <servers> section of the mvn-settings.xml file: 
<servers>
  <server>
    <id>instana-shared</id>
    <username>myuser</username>
    <password>mypassword</password>
  </server>
</servers>

Kubernetes environments

For agents deployed in Kubernetes by using the operator or Helm chart, use the following configuration parameters:

  • agent.instanaSharedRepoMirrorUrl - Mirror URL for the shared repository
  • agent.instanaSharedRepoMirrorUsername - Username for mirror authentication
  • agent.instanaSharedRepoMirrorPassword - Password for mirror authentication

Docker containers

For Docker-based agents, use the following container environment variables:

  • INSTANA_SHARED_REPOSITORY_MIRROR_URL - Mirror URL for the shared repository
  • INSTANA_SHARED_REPOSITORY_MIRROR_USERNAME - Username for mirror authentication
  • INSTANA_SHARED_REPOSITORY_MIRROR_PASSWORD - Password for mirror authentication

Overriding the default Maven repository

Instead of configuring the agent to use a repository mirror, you can also override the default main repository location.

Non-containerized agents

To set the Maven repository location for a non-containerized agent, edit the <instana-agent-dir>/etc/org.ops4j.pax.url.mvn.cfg file and modify the org.ops4j.pax.url.mvn.repositories setting:

org.ops4j.pax.url.mvn.repositories=https://repo.example.com/artifactory/instana-shared@id=shared@snapshots@snapshotsUpdate=always

URL parameters:

  • @id=shared - Repository identifier.
  • @snapshots - Enables the use of snapshot artifacts.
  • @snapshotsUpdate=always - Updates snapshot artifacts on every agent update. If this parameter is not set, snapshots update only once in 24 hours.

To configure multiple repositories, provide a comma-separated list of repository URLs.

If a repository in org.ops4j.pax.url.mvn.repositories requires authentication, add the credentials to the <servers> section of the <instana-agent-dir>/etc/mvn-settings.xml file: 
<servers>
  <server>
    <id>shared</id>
    <username>myuser</username>
    <password>mypassword</password>
  </server>
</servers>
Containerized agents

Use the following container environment variables to set the Maven repository location for a containerized agent:

  1. INSTANA_MVN_REPOSITORY_URL - Base URL of your Maven repository. See the following example: 
    INSTANA_MVN_REPOSITORY_URL=https://artifact-public.instana.io/artifactory
  2. INSTANA_MVN_REPOSITORY_SHARED_PATH - Path to the shared repository. See the following example: 
    INSTANA_MVN_REPOSITORY_SHARED_PATH=instana-shared@id=shared@snapshots@snapshotsUpdate=always

These container environment variables configure the org.ops4j.pax.url.mvn.repositories setting in the org.ops4j.pax.url.mvn.cfg configuration file:

org.ops4j.pax.url.mvn.repositories=${INSTANA_MVN_REPOSITORY_URL}/${INSTANA_MVN_REPOSITORY_SHARED_PATH}

Legacy Maven repository configuration

Before May 2026, dynamic agents were configured with two Maven repositories: shared and features. The features repository is no longer required because all necessary artifacts are now available in the shared repository.

All dynamic agent releases, regardless of the release date, are compatible with the new configuration that uses only the shared repository. All dynamic agents, including releases from May 2026 and later, also continue to support the configuration mechanisms for the legacy features repository.

Legacy mirror configuration

For non-containerized agents, you can still configure a mirror for the features repository in the <instana-agent-dir>/etc/mvn-settings.xml file: 
<mirror>
  <id>instana-features</id>
  <url>https://repo.example.com/artifactory/instana-features</url>
  <mirrorOf>features</mirrorOf>
</mirror>
If your mirror requires authentication, add the credentials to the <servers> section of the mvn-settings.xml file: 
<server>
  <id>instana-features</id>
  <username>myuser</username>
  <password>mypassword</password>
</server>

Legacy Kubernetes configuration

For Kubernetes deployments, use the following configuration parameters to configure a mirror for the legacy features repository:

  • agent.agentReleaseRepoMirrorUrl
  • agent.agentReleaseRepoMirrorUsername
  • agent.agentReleaseRepoMirrorPassword

Legacy Docker configuration

For Docker-based agents, use the following container environment variables to configure a mirror for the legacy features repository:

  • AGENT_RELEASE_REPOSITORY_MIRROR_URL
  • AGENT_RELEASE_REPOSITORY_MIRROR_USERNAME
  • AGENT_RELEASE_REPOSITORY_MIRROR_PASSWORD

Legacy repository override

For containerized agents, you can optionally use the INSTANA_MVN_REPOSITORY_FEATURES_PATH container environment variable to add the features repository to org.ops4j.pax.url.mvn.repositories:

INSTANA_MVN_REPOSITORY_FEATURES_PATH=features-public@id=features@snapshots@snapshotsUpdate=always

If this container environment variable is set, a second repository URL is appended to the configuration in the container:

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