Git を使用したエージェント設定の管理

Git リポジトリーを自分でホストする場合は、自己署名証明書を使用できます。 エージェントが Git リポジトリに安全に接続するには、自己署名証明書を Java のトラストストアにインポートする必要があります。 詳細については、 「自己署名証明書」 を参照してください。

Git リポジトリーへのアクセスは、 .netrc ファイルを使用してパスワードまたはアクセス・トークンを指定することで許可できます。 .netrc は広く使用されており、その詳細については、 .netrc マニュアル・ページを参照してください。

Instana ホストエージェントが実行されているユーザーのホームディレクトリ（例： root）にあるファイル .netrc を設定できます。 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 内の -g、 -b、 -u および -p オプション を参照してください。これらは、 環境変数 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 ベースの構成管理は、エージェント管理ダッシュボードの 「構成管理 」セクションで設定できます。

Gitベースの構成管理は、 Web REST API 資料の Host Agent セクションで説明されているように、API を使用して初期化および構成できます。

手動セットアップでは、 *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-repository-url> 形式については、 Git の URLの公式資料で説明されています。

Git フックは、リポジトリーの .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
 

GitOps 用の Instana GitHub アクションを使用すると、 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 ベースの設定管理と動的なエージェントのバージョン固定を組み合わせて使用できます。 テスト環境があれば、本番環境にアップデートを適用する前に、本番環境と同様のシナリオでエージェントのデプロイメントをテストできます。