Instana Agentの自動更新のタイミング変更と手動更新の方法

はじめに

Instana Host Agentをインストールするときにワンライナーを使って簡単にインストールすることができますが、エージェント・モードを動的(dynamic)か静的(static)かを選択することができます。動的(dynamic)を選んだ場合、エージェントは自動更新機能が有効化されますが、この自動更新のタイミングを変更する方法と、自動更新以外のタイミングで手動更新する方法について書きます。

本手順は以下の環境で実施しています。

• クライアントPC: macOS
• Instana Backend: Self-Hosted Build 231
• Instana Agent: RHEL 7.9

自動更新設定はどう設定すべきか？

デフォルトでは、以下のように設定されています。
つまり、毎日4:30前後に自動更新が走るということになります。

[root@host ~]# cat /opt/instana/agent/etc/instana/com.instana.agent.main.config.UpdateManager.cfg
# Instana Update Manager configuration.
# AUTO for automatic updates with given schedule. OFF for no automatic updates.
mode = AUTO
# DAY for daily, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
every = DAY
# Time is hh:mm in 24 hours format.
at = 04:30
# Extend default jitter to -45 / +45 minutes to spread update load on backend infrastructure
jitter = 90

デフォルト値は環境や製品のバージョンによって変わるかもしれませんのでご注意ください。
詳細はドキュメントや実機のファイルをご確認ください。
jitterはドキュメントでは30になっていますが、実機では90になっていましたので、OSによっても異なるかもしれません。

- パターン1: デフォルト設定のまま

基本的には、エージェント導入後の設定変更しなかったとしても、毎日自動更新が動くのでこれが最適解のように思います。一方で、自動更新時に何かしらの不具合が発生する可能性はゼロではないので、そのリスクを許容する形になります。

- パターン2: 自動更新の頻度を減らしタイミングを管理下に置く

SaaSバックエンドの更新はbi-weeklyですし、Agentは毎日更新チェックしなくて良いと考える場合は週1回の更新に変更できます。上記の自動更新時のリスクを減らすこともできます。また、問題が生じても比較的動きやすい曜日や時間帯を指定することもできます。

- パターン3: 自動更新を無効化し、手動で更新を実行する

自動更新による運用負荷軽減のメリットは享受できませんが、手動運用でカバーできるのであれば、自動更新を無効に設定するという選択肢もあります。定期メンテナンスや、Backendの更新のタイミングに合わせて実施するなどが案として挙げられます。

エージェントのバージョンを固定することで自動更新を無効にする方法もあります。
こちらの詳細は以下の記事をご参照ください。

自動更新を無効にする場合、エージェントのサポートはリリースから6ヶ月間ですのでご注意ください。詳細はサポートポリシーをご確認ください。

設定変更方法

ここでは、パターン2および3を選択した場合、どのように設定するかを書きます。

a. パターン2の場合

自動更新の頻度を減らし、毎週火曜日の4:30前後に実行するように設定変更したいと思います。
mode = AUTOのままで、every = TUESDAYに設定します。

% ssh $HOST
[root@host ~]# cd /opt/instana/agent/etc/instana
[root@host instana]# sed -i.bak -e '/^every/s/DAY/TUESDAY/g' /opt/instana/agent/etc/instana/com.instana.agent.main.config.UpdateManager.cfg

リモートから実行する場合は、以下のようになります。

% ssh $HOST sed -i.bak -e '/^every/s/DAY/TUESDAY/g' /opt/instana/agent/etc/instana/com.instana.agent.main.config.UpdateManager.cfg

設定ファイルを変更すると、Agentが自動的に変更を検知します。(Agentの再起動は不要)
Agentログに以下が出力されます。

2022-11-22T23:54:02.196+0900 | INFO  | g.UpdateManager) | UpdateManagerImpl                | 50 - com.instana.agent-bootstrap - 1.2.14 | Automatic updates scheduled every TUESDAY at 04:30

b. パターン3の場合

自動更新をしないように設定変更したいと思います。
mode = OFFに設定します。

% ssh $HOST
[root@host ~]# cd /opt/instana/agent/etc/instana
[root@host instana]# sed -i.bak -e '/^mode/s/AUTO/OFF/g' /opt/instana/agent/etc/instana/com.instana.agent.main.config.UpdateManager.cfg

リモートから実行する場合は、以下のようになります。

% ssh $HOST sed -i.bak -e '/^mode/s/AUTO/OFF/g' /opt/instana/agent/etc/instana/com.instana.agent.main.config.UpdateManager.cfg

設定ファイルを変更すると、Agentが自動的に変更を検知します。(Agentの再起動は不要)
Agentログに以下が出力されます。

2022-11-22T23:46:32.173+0900 | INFO  | g.UpdateManager) | UpdateManagerImpl                | 50 - com.instana.agent-bootstrap - 1.2.14 | Automatic updates disabled

手動で更新する方法

パターン3で自動更新を無効にした場合、どのように手動更新をするのかについて書きます。

a. Backend UIから実行

台数が少ない場合、UIのエージェントの画面からが一番楽だと思います。
その他 > エージェント > エージェントの詳細から該当のエージェントを選択
管理内にある「エージェントの更新」ボタンをクリック。

b. Backend APIから実行

台数が多い場合など、自動化したい場合はAPIから実行が良いと思います。

1. 事前にAPIキーを作成しておきます。その際、APIキーに「エージェントの構成」の権限を付与しておきます。
   

   権限付与をしていなかった場合、Agent更新のAPI実行がエラーとなります。
   {"errors":["Insufficient access rights for resource method. Missing permissions: canConfigureAgents"]}

2. 作成したAPIキーの情報と、バックエンドのURLを環境変数に入れておきます。

   % API_SERVER=https://unit-tenant.instana.io #Instana Backend URL
   % API_KEY=XXXX #上記で作成したAPIキー
   

3. Instana Agentが導入されているホストのIDが必要なので取得します。（APIドキュメント）

   % curl -H "authorization: apiToken $API_KEY" \
    $API_SERVER/api/host-agent | jq 
   
   #以下レスポンス
   {
     "items": [
       {
         "snapshotId": "UKsFfzom-QoYyxBFEoV0inXXXXX",
         "plugin": "instanaAgent",
         "from": 1669061263000,
         "to": null,
         "tags": [],
         "label": "Instana Agent @ hostname",
         "host": "02:00:03:ff:fe:22:96:55"
       },
       #(省略)
     ]
   }
   

   ホストの情報だけ取得したい場合は以下の様にします。

   % curl -H "authorization: apiToken $API_KEY" \
    $API_SERVER/api/host-agent | jq .items[].host
   

4. ホストIDを使用して、更新をキックします。（APIドキュメント）

   HOST=02:00:03:ff:fe:22:96:55 #APIで取得したホストID
   curl -X POST -H "authorization: apiToken $API_KEY" \
    https://$API_SERVER/api/host-agent/$HOST/update 
   

   APIの応答はありませんが、ログに更新の開始が出力されます。

   2022-11-22T23:07:31.621+0900 | INFO  | ate.com:1444-4-1 | UpdateManagerImpl                | 50 - com.instana.agent-bootstrap - 1.2.14 | Performing update
   

おわりに

自動更新の設定変更の方法と、自動更新を無効化した場合の手動更新の方法についてまとめました。
少しでも参考になれば幸いです。