使用 Git 管理代理配置

如果您自己托管 Git 存储库，那么可以使用自签名证书。 为了让代理能够安全地连接到 Git 存储库，您必须将自签名证书导入 Java 的信任库中。 如需更多信息，请参阅 “自签名证书 ”。

可以通过使用 .netrc 文件提供密码或访问令牌来授权访问 Git 存储库。 .netrc 已被广泛使用，有关它的详细信息，可以访问 .netrc 联机帮助页。

您可以在运行 Instana 主机代理的用户主目录（例如）中配置该 .netrcroot 文件。 请参阅 github.com 存储库的以下样本 .netrc 文件:

machine github.com
login oauth2
password <access_token>
 

在 Git 存储库中，您需要具有与 *instanaAgentDir*/etc中相同的目录结构。 例如，如果要从名为 configuration-mysql.yaml的 Git 文件获取数据，那么需要将此文件放在名为 instana 的 Git 目录 (即，文件 instana/configuration-mysql.yaml) 中。 否则，当从 Git 存储库获取文件时，该文件会被放置在服务器上的错误位置，且不会被 Instana 主机代理使用。

下图显示了 Git 存储库的示例结构:

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

通过使用 systemd ，指定其他参数的最简单方法是使用混入文件。 要查看混入目录的路径，请运行以下命令:

systemctl status instana-agent
 

此目录中的文件必须具有文件扩展名 .conf，否则将忽略这些文件。

1. 在 /etc/systemd/system/instana-agent.service.d/ 目录中创建扩展名为 .conf的新文件，例如 git-configuration-environments.conf。
2. 将以下内容添加到该文件：

   [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>`.
   
    

添加或更改混入文件后，请完成以下步骤:

1. 通过运行 systemctl daemon-reload 命令来重新装入混入文件。
2. 运行命令 systemctl restart instana-agent ，重启 Instana 主机代理。

如果已设置以下环境变量，那么在启动主机代理程序时，它会检查 *instanaAgentDir*/etc/ 文件夹中是否存在本地 Git 存储库。 如果本地 Git 存储库不存在，那么主机代理程序将创建连接到远程存储库的本地存储库。

如果 Instana 代理直接在主机上运行，则需要在该主机上设置以下环境变量。 如果主机代理程序正在容器化环境中运行，请在容器级别设置变量。

请参阅 OneLiner 文档中的 , -b, -u 和 -p 选项 -g，这些选项分别对应于环境方法 INSTANA_GIT_REMOTE_REPOSITORY中的, INSTANA_GIT_REMOTE_BRANCH, INSTANA_GIT_REMOTE_USERNAME 和 INSTANA_GIT_REMOTE_PASSWORD 环境变量。

下表显示了环境变量与单行命令的参数之间的映射:

通过将 INSTANA_GIT_REMOTE_REPOSITORY、INSTANA_GIT_REMOTE_BRANCH、INSTANA_GIT_REMOTE_USERNAME 和 INSTANA_GIT_REMOTE_PASSWORD 环境变量添加到 Docker 容器中，这些步骤与环境方法基本相同。

例如，以下代码示例展示了在容器中启动主机代理所需的参数，以及启用基于 Git 的配置管理所需的 Git 参数：

# 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
 

基于 Git 的配置管理可在 “代理管理”仪表板中的 “配置管理 ”部分进行设置。

可以使用 API 来初始化和配置基于 Git 的配置管理，如 Web REST API 文档的 Host Agent 部分中所述。

手动设置包括初始化 *instanaAgentDir*/etc/ 文件夹中的 Git 存储库，以及添加名为 configuration 的 remote。

主机代理程序通过使用 configuration 远程配置的跟踪分支来拉取本地 main 分支。 可以通过多种方式来设置 Git 存储库，并且您可以自由选择最适合设置的存储库。

例如，通过以下设置，可以从 configuration 远程的 main 分支获取主机代理程序拉取配置：

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
 

以下示例允许从 configuration 远程中的 my-configurations 分支中拉取配置：

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 URL 上的官方文档中描述了可能的 <git-repository-url> 格式。

Git Hook 是可以放置在存储库的 .git/hooks 目录中的程序，它们在 Git 存储库的生命周期中的不同时间触发。 Git 提供许多不同的挂钩，并且 post-update 挂钩是最适合与基于 Git的主机代理程序配置管理集成的。

GitOps-Demo 仓库提供了一个示例性的 post-updateGit 钩子 ，该钩子会在仓库中的分支发生更新时触发主机代理的更新。

您将会看到在触发推送之后，脚本的预期输出已发送回 Git 客户机：

$ 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
 

通过 Instana GitHub 中的 “ GitOps ”操作，您可以直接使用 Instana 的 Web 界面 API 触发主机代理的远程操作。

GitOps - 演示存储库显示了如何在 GitHub 上设置存储库以管理主机代理程序配置，以及如何使用针对 GitOps 的 Instana GitHub 操作来自动触发更新。

GitHub 通过使用令牌来支持 HTTPS 认证，这可以由主机代理程序使用，如本部分中所述。

要使用 GitHub 存储库，必须先创建个人访问令牌。 具体操作方法详见 “创建个人访问令牌 ”文档页面： GitHub。 该令牌仅需要读许可权即可访问存储库。

GitHub 期望该令牌以 HTTPS 基本身份验证用户名的形式提供，且密码为空。 因此，通过设置以下环境变量集，可以将主机代理程序配置为对 GitHub 存储库使用 HTTPS 基本认证：

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=''
 

请注意，与用户名相同的空密码和个人令牌原则也适用于配置主机代理程序，以进行基于 Git 的配置管理的其他方法。 有关可能采用的配置方法的概述，请参阅设置部分。

您可以使用多种方法来控制部署到生产环境中的主机代理的版本更新。 如果使用静态代理，则必须根据需要手动更新主机代理。 如果使用动态代理，则可以对更新进行配置，以设置更新间隔、固定版本等。 如需更多信息，请参阅 “配置动态主机代理的更新 ”。 如果未指定配置，则每天自动对动态代理进行更新。 此外，如果需要更严格地控制主机代理的版本更新，可以将动态代理版本固定与基于 Git 的配置管理相结合。 如果有测试环境，则可以在将更新应用到生产环境之前，根据类似生产环境的场景测试代理部署。