Git-based Configuration Management
TABLE OF CONTENTS
- When to use 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
Note: Host agent boostrap 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.
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
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 (
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 boostrap version
1.2.12 basic HTTP/HTTPS authentication is supported. The environment variables
INSTANA_GIT_REMOTE_PASSWORD can be used to set access credentials.
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
INSTANA_GIT_REMOTE_BRANCH=<branch_name>: name of the remote branch to follow, e.g.,
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
Refer to the
-p options in the OneLiner documentation, which map to the
INSTANA_GIT_REMOTE_PASSWORD environment variables for the environment method.
The steps are fundamentally the same as the environment method, by adding the
INSTANA_GIT_REMOTE_PASSWORD environment variables to the Docker container.
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.
A manual setup consists of initializing a Git repository in the
<instana-agent-dir>/etc/ folder and adding a
The host agent will pull the local
main branch, using the configured tracking branch from the
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
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
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
<git-repository-url> formats are described in the official documentation on Git URLs.
The host agent will fetch configuration updates from the remote repository:
- Upon the startup or restart
- Through a
rebootinitiated over the Agent Management Dashboard
- Through a configuration change over the Agent Management Dashboard
- Through the Web API as described in the
Host Agentsection 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.
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.
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: 'entity.zone:"test"' ... OK 699ada9..9632c09 HEAD -> main
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.
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:
INSTANA_GIT_REMOTE_REPOSITORY='https://github.com/<user/organization>/<repository>.git INSTANA_GIT_REMOTE_BRANCH='<branch>' INSTANA_GIT_REMOTE_USERNAME='<token>' INSTANA_GIT_REMOTE_PASSWORD=''
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.