使用管理代理配置 Git

如果你自己托管仓库 Git ，可以使用自签名证书。 要使代理安全地连接到存储 Git 库，必须将自签名证书导入Java信任存储库。 有关更多信息，请参阅自签名证书。

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

您可以在用户主目录（例如）中 root配置文件 .netrc ，该目录是Instana主机代理的运行位置。 请参阅以下 .netrc 示例文件以了解 github.com 该存储库：

machine github.com
login oauth2
password <access_token>

在存储 Git 库中，您需要保持与 *instanaAgentDir*/etc.目录相同的目录结构。 例如，若要获取名为 configuration-mysql.yaml的 Git 文件中的数据，该文件需放置在名为 的 Git 目录 instana 中（即文件 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 命令重新加载 drop-in 文件。
2. 通过运行命令 systemctl restart instana-agent 重启 Instana 主机代理。

若已设置以下环境变量，则当主机代理启动时，它会检查本地 Git 存储库是否存在于指定 *instanaAgentDir*/etc/ 文件夹中。 如果本地 Git 存储库不存在，主机代理将创建一个与远程存储库相连的本地存储库。

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

请参阅文档 OneLiner 中的、 -u-b-g 和 -p 选项 ，它们分别映射到环境方法的、 INSTANA_GIT_REMOTE_USERNAMEINSTANA_GIT_REMOTE_BRANCHINSTANA_GIT_REMOTE_REPOSITORY 和 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 存储库提供了一个示例 Gitpost-update 钩子 ，当存储库中的分支被更新时，该钩子会触发主机代理的更新。

您将会看到在触发推送之后，脚本的预期输出已发送回 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 基于配置的管理方案。 若您拥有测试环境，可在将更新部署至生产环境前，针对类似生产环境的场景对代理部署进行测试。