Git-based Configuration Management

Note: The Git-based configuration management functionality is 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.

Note: The Git-based configuration management functionality is currently in alpha. It is fully functional, we are confident the fundamental user-experience won't change much as it approaches GA, but it does not yet provide the level of automation and ease of use we demand of Instana features.

Note: The Git-based configuration management functionality is available from the host agent boostrap version 1.2.8.

The host agent is capable of retrieving its configurations from a remote Git repository. All the configurations discussed in the host agent configuration documentation are manageable over Git. Some of the host agent configurations require the host agent to restart before they take effect: the documentation clarifies in the relevant section for the particular configuration whether that is the case.

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 using 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 deployed in entire landscapes or environments.

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

The requirements in terms of your Git repository setup are outlined in the Pre-requisites section.


Note: the Instana host agent configuration may include sensitive information, for example credentials, and should be protected from unauthorized access.

The Git-based configuration management does not assume any local Git client or other tools. Only the configured remote repository has to be accessible from the host agent, this includes network access and Git authentication.

The system providing access to the remote Git repository has to be reachable via a network connection from the host agent and based on the used Git transport protocol (HTTP, HTTPS) the appropriate ports have to be open.

Currently the HTTP and HTTPS transport protocol is supported. Access to a repository can be authorized using a .netrc file in the user home directory to provide password or access token. .netrc is widely used and details about it can, for example, be found on the .netrc man page.


This functionality, in its current alpha state, requires manual setup. Future versions will offer a much more streamlined experience with integration in the various agent packages.

Manual setup

Manual setup consists of initializing a Git repository in the <instana-agent-dir>/etc/ folder and adding a remote named configuration. The host agent will pull the local master branch, 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 will allow you to have the host agent pull configurations from the master branch of the configuration remote:

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

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

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

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

Configuration updates

The host agent will fetch configuration updates from the remote repository:

  1. Upon startup or restart
  2. Through a reboot initiated over the Agent Dashboard UI, as described in the Agent Management Dashboard documentation.

The Git-based configuration management operates on the local master branch und 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 and no further update is executed.

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