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
Host agent bootstrap version
1.2.12adds support for
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
- Configuration updates
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
it automatically activates its Git-based configuration management capabilities, and looks for a Git remote in the local repository called
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
HTTP/HTTPSauthentication is supported. The environment variables
INSTANA_GIT_REMOTE_PASSWORDcan be used to set access credentials.
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
machine github.com 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:
repository-root/ ├── instana/ │ ├── configuration-mysql.yaml │ └── com.instana.agent.main.config.UpdateManager.cfg └── org.ops4j.pax.url.mvn.cfg
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.
- Create a new file in the
/etc/systemd/system/instana-agent.service.d/directory with the extension
.conf, such as
- Add the following content to the file:
[Service] Environment=INSTANA_GIT_REMOTE_BRANCH=<branch> Environment=INSTANA_GIT_REMOTE_REPOSITORY=<repository_url> Environment=INSTANA_GIT_REMOTE_USERNAME=<username> Environment=INSTANA_GIT_REMOTE_PASSWORD=<access_token> ``` **Notes:** - Replace *<branch>* with the name of the remote branch that the Instana host agent connects to. - Replace *<repository_url>* with the URL of the remote Git repository; for example, `https://github.com/<your_account>/<your_repo>.git`. - Replace *<username>* 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 *<access_token>* 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:
- Reload the drop-in files, by running the systemctl daemon-reload command.
- 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.
||The URL of the remote Git repository; for example,
||The name of the remote branch that the Instana host agent is to follow; for example,
||Optional: The username or access token to be used in basic authentication (See the note after this table.)|
||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
-p options in the OneLiner documentation, which map to the
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|
With Docker images
The steps are fundamentally the same as the environment method, by adding the
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_ENDPOINT=" \ --env="INSTANA_AGENT_ENDPOINT_PORT=" \ --env="INSTANA_AGENT_KEY=" \ --env="INSTANA_DOWNLOAD_KEY=" \ --env="INSTANA_AGENT_ZONE=" \ --env="INSTANA_GIT_REMOTE_BRANCH=" \ --env="INSTANA_GIT_REMOTE_PASSWORD=" \ --env="INSTANA_GIT_REMOTE_REPOSITORY=" \ --env="INSTANA_GIT_REMOTE_USERNAME=" \ icr.io/instana/agent
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
https://github.com/<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.
A manual setup consists of initializing a Git repository in the
<instana-agent-dir>/etc/ folder and adding a
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
For example, the following setup allows 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 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 fetches 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 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,
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: 'entity.zone:"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:
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 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.