Git-based configuration management

The Git-based configuration management functions are optional. If you already have other means of delivering file-based configurations for the host agent, like Ansible, Terraform, Chef, or Puppet, then you likely do not need Git-based configuration management.


  • The Git-based configuration management functions are currently in alpha. It is fully functional, and the fundamental user-experience doesn't change much as it approaches GA, but it does not yet provide the level of automation and ease of use as that are demanded for Instana features.

  • The Git-based configuration management functions are available from the host agent bootstrap version 1.2.11.

  • Host agent bootstrap version 1.2.12 adds support for HTTP/HTTPS basic authentication.

The host agent can retrieve its configurations from a remote Git repository. All the configurations that are discussed in the host agent configuration documentation are manageable over Git. Some host agent configurations require the host agent to restart before they take effect (the documentation clarifies this requirement in the relevant section).

When to use Git-based configuration management

The Instana host agent ships with sane defaults for its configurations and generally, there is very little to no configuration needed in most production scenarios.

However, features like dynamic version pinning, the host agent backend configurations (especially when you use multiple backends), secrets, and host tags greatly benefit from some centralized version control that allows you to set a configuration once, and having it spread to host agents that are deployed in entire landscapes or environments.

The Instana host agent has a built-in Git client that can fetch configurations from a remote repository that you operate. When the host agent discovers a local Git repository in its <instana-agent-dir>/etc/ directory, it automatically activates its Git-based configuration management capabilities, and looks for a Git remote in the local repository called configuration. On startup, the host agent updates its local repository based on what is available in the remote one. For more information about the configuration update process, see the Configuration updates section.

The requirements of your Git repository setup are outlined in the Prerequisites section.


Note: The host agent configuration might include sensitive information (such as credentials), and should be protected from unauthorized access.

The Git-based configuration management does not assume any local Git client or other tools. The host agent needs access to the configured remote Git repository. This access includes network connection and Git authentication:

  • The system that hosts the remote Git repository must be reachable by using a network connection from the host agent. The system needs to provide access based on the Git transport protocol. Currently, the host agent supports HTTP and HTTPS transport protocols. In addition, the appropriate ports must be open.

  • Starting with agent bootstrap above version 1.2.12, basic HTTP/HTTPS authentication is supported. The environment variables INSTANA_GIT_REMOTE_USERNAME and INSTANA_GIT_REMOTE_PASSWORD can be used to set access credentials.


Self-signed certificates

If you host the Git repository yourself, you can use a self-signed certificate. For the agent to connect securely to a Git repository, you must import the self-signed certificate into the Java truststore. For more information, see Self-signed certificates.

Authentication with .netrc file

Access to a Git repository can be authorized by using a .netrc file to provide the password or access token. .netrc is widely used and details about it can be found on the .netrc man page.

You can configure the .netrc file in the home directory of the user (for example, root) where the Instana host agent is running. See the following sample .netrc file for the repository:

login oauth2 
password <access_token> 

Note: Replace <access_token> with an access token.

Git repository structure

In the Git repository, you need to have same structure of directories as in <instana-agent-dir>/etc. For example, if you want to get data from the Git file named configuration-mysql.yaml, this file needs to be placed in the Git directory named instana (that is, the file instana/configuration-mysql.yaml). Otherwise, when the file is obtained from the Git repository, the file is placed in the wrong location on the server and is not used by the Instana host agent.

The following figure shows the example structure of a Git repository:

├── instana/
│   ├── configuration-mysql.yaml
│   └── com.instana.agent.main.config.UpdateManager.cfg
└── org.ops4j.pax.url.mvn.cfg

With systemd

By using systemd, the easiest way to specify the additional parameters is using a drop-in file. To view the path to the drop-in directory, run the following command:

systemctl status instana-agent

The files in this directory must have the file extension .conf, otherwise the files are ignored.

  1. Create a new file in the /etc/systemd/system/instana-agent.service.d/ directory with the extension .conf, such as git-configuration-environments.conf.
  2. Add the following content to the file:
    ```   **Notes:**
     - Replace *&lt;branch&gt;* with the name of the remote branch that the Instana host agent connects to.
     - Replace *&lt;repository_url&gt;* with the URL of the remote Git repository; for example, `<your_account>/<your_repo>.git`.
     - Replace *&lt;username&gt;* with a username or access token (for basic authentication). If you are using a `.netrc` file or a public repository, you can remove the whole line `Environment=INSTANA_GIT_REMOTE_USERNAME=<username>`.
     - Replace *&lt;access_token&gt;* with an access token. If you are using an access token as username (basic authentication), a `.netrc` file, or a public repository, you can remove the whole line `Environment=INSTANA_GIT_REMOTE_PASSWORD=<access_token>`.

After you add or change a drop-in file, complete the following steps:

  1. Reload the drop-in files, by running the systemctl daemon-reload command.
  2. Restart the Instana host agent, by running the command systemctl restart instana-agent.

With environment variables

If you have set the following environment variables, then when a host agent is started it checks for the presence of the local Git repository in the <instana-agent-dir>/etc/ folder. If the local Git repository is not present, the host agent creates a local repository that is connected to the remote repository.

If the Instana agent is running directly on a host, the following environment variables need to be set on the host. If the host agent is running in a containerized environment, set the variables on the container-level.

Environment variable Description
INSTANA_GIT_REMOTE_REPOSITORY The URL of the remote Git repository; for example,<your_account>/<your_repo>.git.
INSTANA_GIT_REMOTE_BRANCH The name of the remote branch that the Instana host agent is to follow; for example, main
INSTANA_GIT_REMOTE_USERNAME Optional: The username or access token to be used in basic authentication (See the note after this table.)
INSTANA_GIT_REMOTE_PASSWORD Optional: The password to be used in basic authentication (See the note after this table.)

Note: If you want to use basic authentication with an access token instead of a username and password, set the access token in the parameter INSTANA_GIT_REMOTE_USERNAME. This ensures that basic authentication is configured correctly without a username.

With the one-liner command

Refer to the -g, -b, -u and -p options in the OneLiner documentation, which map to the INSTANA_GIT_REMOTE_REPOSITORY, INSTANA_GIT_REMOTE_BRANCH, INSTANA_GIT_REMOTE_USERNAME and INSTANA_GIT_REMOTE_PASSWORD environment variables for the environment method.

The following table shows the mapping between the environment variables and the parameters of the one-liner command:

Environment variable Parameter of the one-liner command
INSTANA_GIT_REMOTE_REPOSITORY -g = (optional, needed if -b is set)
INSTANA_GIT_REMOTE_BRANCH -b = (optional, needed if -g is set)
INSTANA_GIT_REMOTE_USERNAME -u = (optional, needed if -p is set)

With Docker images

The steps are fundamentally the same as the environment method, by adding the INSTANA_GIT_REMOTE_REPOSITORY, INSTANA_GIT_REMOTE_BRANCH, INSTANA_GIT_REMOTE_USERNAME and INSTANA_GIT_REMOTE_PASSWORD environment variables to the Docker container.

For example, the following extract gives the parameters that are needed to start the host agent in a container and the required Git parameters to enable Git-based configuration management:

# Please enter proper values for all --env arguments.
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_KEY=" \
   --env="INSTANA_AGENT_ZONE=" \

With the agent management dashboard

The Git-based configuration management can be set up in the Configuration management section on the Agent management dashboard.

Important: You must add the .git suffix to the end of the INSTANA_GIT_REMOTE_REPOSITORY address, such as<your_account>/<your_repo>.git. In addition, to configure basic authentication for access to the Git repository, you can use a .netrc file. For more information, see Authentication with .netrc file.

With the API

The Git-based configuration management can be initialized and configured by using the API as described in the Host Agent section of the Web REST API documentation.

Manual setup

A manual setup consists of initializing a Git repository in the <instana-agent-dir>/etc/ folder and adding a remote named configuration.

The host agent pulls the local main branch by using the configured tracking branch from the configuration remote. There are multiple ways to set up the Git repository, and you can freely choose the one that fits best your setup.

For example, the following setup allows you to have the host agent pull configurations from the main branch of the configuration remote:

etc> git init
etc> git remote add -m main -t main configuration <git-repository-url>
etc> git fetch configuration
etc> git checkout -f -b main --track configuration/main

The following example allows you to pull the configurations from the my-configurations branch in the configuration remote:

etc> git init
etc> git remote add -m main -t my-configurations configuration <git-repository-url>
etc> git fetch configuration
etc> git checkout -f -b main --track configuration/my-configurations

Possible <git-repository-url> formats are described in the official documentation on Git URLs.

Configuration updates

The host agent fetches configuration updates from the remote repository:

  1. Upon the startup or restart.
  2. Through a reboot initiated over the Agent Management Dashboard.
  3. Through a configuration change over the Agent Management Dashboard.
  4. Through the Web API as described in the Host Agent section and the integrations that rely on it like the GitHub Update Agent action.

The Git-based configuration management operates on the local main branch, and updates it with the version of the configured remote tracking branch. If no tracking branch is configured, an error message is added to the host agent log file. While no further configuration update is run, the agent resumes its monitoring by using the current configurations.

Local changes are not expected and are discarded on updates. Untracked files are touched by the Git-based configuration management so that initially not all files need to be added to the repository.

Triggering updates by using Git Hooks

Git Hooks are programs that you can place in the .git/hooks directory of the repository, and they trigger at different times in the lifecycle of your Git repository. Git offers many different hooks, and the post-update hook is the best suited for integration with the Git-based configuration management of host agents.

The GitOps-Demo repository provides a sample post-update Git hook that triggers the update of host agents whenever a branch in the repository is updated.

You see that the expected output of the script sent back to your Git client after you trigger a push:

$ gitops-test# git push origin HEAD:main
[detached HEAD 9632c09] origin
 1 file changed, 1 insertion(+), 1 deletion(-)
Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Delta compression using up to 12 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 376 bytes | 376.00 KiB/s, done.
Total 4 (delta 1), reused 0 (delta 0)
remote: GitOps update: Triggering the configuration update of agents matching the following query: '"test"' ... OK
   699ada9..9632c09  HEAD -> main

Triggering updates by using GitHub Update Action

The Instana GitHub action for GitOps allows you to straightforwardly trigger the remote of the host agents by using Instana's Web API.

The GitOps-Demo repository shows how to set up a repository on GitHub to manage your host agent configurations and how to automatically trigger the updates by using the Instana GitHub action for GitOps.


Private GitHub repository

GitHub supports HTTPS authentication by using tokens, and this can be used by the host agent as described in this section.

To use a GitHub repository, you first must create a personal access token. Details on how to do that are documented on the Creating a personal access token GitHub documentation page. The token needs only read permissions to access the repository.

GitHub expects the token to be provided as HTTPS basic authentication username with an empty password. Therefore, the host agent can be configured to use HTTPS basic authentication for GitHub repositories by setting the following environment variables set:


Notice that the same principle of empty password and personal token as username works also with the other means of configuring the host agent for Git-based configuration management. For an overview of the possible configuration approaches, refer to the Setup section.