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 bootstrap version 1.2.11.

Note: Host agent bootstrap version 1.2.12 added support for HTTP/HTTPS basic authentication.

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 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 repository 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 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 protocols are supported. Access to a repository can be authorized using a .netrc file in the user home directory to provide the password or access token. .netrc is widely used and details about it can, for example, be found on the .netrc man page.

As of agent bootstrap 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.


With the Environment

By setting the following environment variables on the host agent, it will check for the existence of the Git repository in the <instana-agent-dir>/etc/ folder and, if none is found, a new repository is created:

  • INSTANA_GIT_REMOTE_REPOSITORY=<git-repository-url>: specification of the remote's url
  • INSTANA_GIT_REMOTE_BRANCH=<branch_name>: name of the remote branch to follow, e.g., main
  • INSTANA_GIT_REMOTE_USERNAME=[username]: optional environment variable to configure the username to be used in basic authentication with HTTP remotes
  • INSTANA_GIT_REMOTE_PASSWORD=[password]: optional environment variable to configure the password to be used in basic authentication with HTTP remotes

With the OneLiner

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.

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.

With the Agent Management Dashboard

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

With the API

The Git-based configuration management can be initialized and configured via 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 will pull the local main 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 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, instead, 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 will fetch 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 executed, the agent resumes its monitoring using the current configurations.

Local changes are not expected and will be discarded on updates. 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.

Triggering updates via Git Hooks

Git Hooks are programs you can place in the .git/hooks directory of the repository, and they will trigger at different times in the lifecycle of your Git repository. Git offers a lot of 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.

Below you see 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 via GitHub Update Action

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

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


Private GitHub Repository

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

To use a GitHub repository you first have to 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 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 will work 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.