はじめに
Instana Self-Hosted on dockerをBuild 193からBuild 253まで度々アップグレードをしてきましたので、そのTipsに関してまとめておきます。（あくまで参考までに。）
本手順は以下の環境で実施しています。
- Instana Backend: Self-Hosted on docker (Single)
- Platform: IBM Cloud VSI
- OS: RHEL 7.9
- docker: 1.13.1 (RHEL7 bundle)
Instana Self-Hostedのリリースとアップグレードパス
Instana SaaSは隔週でリリースされ、Build 251,252,253...という連番の数字で表されるのに対し、Self-Hostedは月1回リリースされ、Build 249,251,253...のように奇数の連番となっています。
今までの傾向としては、Instana SaaSの奇数Buildがリリースされた後、約2週間後にInstana Self-Hostedの同Buildがリリースされています。
アップグレードパスは、基本的には、直近2リリースからのみ直接アップグレード可能となっています。
例えば、Build 253へ直接アップグレードできるのは、Build 249または251となる。それ以前のバージョンを使用している場合は段階的にアップグレードを行う必要があります。
リリースノートにアップグレードに関するRelease informationならびにInstallation instructionsが記載されていることがあるため、必ず目を通しておくことをお勧めします。
アップグレードの大まかな手順と流れ
ドキュメントにも記載がありますが、要約すると以下の流れです。
- バージョンロックの解除 ⇨バージョンロック適用時のみ
- バックアップの取得（バージョンロック解除前でも良い）⇨必要に応じて ※本記事では省略
-
instana-consoleパッケージのアップデート -
instana updateコマンドでInstana Backendのアップグレード - 段階的アップグレードの場合、2バージョンずつ3.4.を繰り返す。
- バージョンロックの適用 ⇨必要に応じて
1. バージョンロックの解除
ドキュメントに記載の手順でBackendインストールをしている場合は、最後にバージョンロックの設定が記載されているので、まずはそれを解除します。
[root@instana-host]# yum versionlock list
0:instana-console-245-0.*
versionlock list done
[root@instana-host]# yum versionlock delete instana-console
Deleting versionlock for: 0:instana-console-245-0.*
versionlock deleted: 1
[root@instana-host]# yum versionlock list
versionlock list done
2. バックアップの取得
本記事では省略します。
必要に応じて、ドキュメントに記載のデータバックアップを行います。
バックアップを取得する場合は、静止点のためBackendを停止する必要があります。
3. instana-consoleパッケージのアップデート
まずはinstana-consoleパッケージをアップデートする必要があります。
普通にアップデートすると利用可能な最新バージョンになるので、アップグレードパスに従い適切なバージョンをインストールします。ターゲットバージョンを指定して、後ろに*をつけると最新のマイナーバージョンが自動選択されるので楽です。（Build 245辺りで微妙に表記が変わったのにも対応可）
[root@instana-host]# export TARGET_VERSION=XXX
[root@instana-host]# yum update instana-console-${TARGET_VERSION}*
参考までに、インストール可能なバージョンの一覧を取得するには、yumリポジトリを更新してから以下のコマンドを実行します。
[root@instana-host]# yum --showduplicate list instana-console
(省略)
利用可能なパッケージ
(省略)
instana-console.x86_64 241-5 instana-product
instana-console.x86_64 243-0 instana-product
instana-console.x86_64 243-1 instana-product
instana-console.x86_64 243-2 instana-product
instana-console.x86_64 243-3 instana-product
instana-console.x86_64 243-4 instana-product
instana-console.x86_64 243-5 instana-product
instana-console.x86_64 243-6 instana-product
instana-console.x86_64 245-0 instana-product
instana-console.x86_64 245_1-1 instana-product
instana-console.x86_64 245_2-1 instana-product
instana-console.x86_64 247_0-1 instana-product
instana-console.x86_64 247_1-1 instana-product
instana-console.x86_64 247_2-1 instana-product
instana-console.x86_64 247_3-1 instana-product
instana-console.x86_64 247_4-1 instana-product
instana-console.x86_64 249_0-1 instana-product
instana-console.x86_64 249_1-1 instana-product
instana-console.x86_64 249_2-1 instana-product
instana-console.x86_64 251_0-1 instana-product
instana-console.x86_64 251_1-1 instana-product
instana-console.x86_64 251_2-1 instana-product
instana-console.x86_64 253_0-1 instana-product
instana-console.x86_64 253_1-1 instana-product
4. Instana Backendのアップグレード
instana updateコマンドを使用して、Instana Backendを更新します。事前にBackendを停止しておく必要はありません。
settings.hclファイルがあるディレクトリに移動してコマンドを実行するか、-fオプションでsettings.hclファイルの場所を指定してコマンドを実行します。
[root@instana-host]# export INSTANA_DIR=/opt/ibm/instana
[root@instana-host]# cd ${INSTANA_DIR}
[root@instana-host]# instana update
まずEnsure imagesのプロセスで、対応するバージョンのコンテナのダウンロードが行われますので、そこそこ時間がかかります。ダウンロードの間はBackendはまだ動作しています。
次のClean docker containersのプロセスで旧バージョンのコンテナの削除が行われますので、Backendが稼働している場合は停止されます。
その後、Check data directoriesからMigrate data storesプロセスにかけて、新バージョンのデータストア関連コンテナの起動とデータ移行が行われます。アーキテクチャ変更によりMigrationが必要な場合は自動的にやってくれます。
最後に、Run componentsプロセスでその他のコンテナの起動が行われて、正常に起動したことが確認されると一連のアップグレード処理は完了です。
最終的に、以下のようなメッセージが表示されたら成功です。
[root@instana-host]# instana update
Setup host environment ✓
Handle certificates ✓
Ensure images ✓
Clean docker containers ✓
Check data directories ✓
Run datastores ✓
Create configurations ✓
Migrate data stores ✓
Run components ✓
Check components ✓
Setup environment urls ✓
Run nginx ✓
Welcome to the World of Automatic Infrastructure and Application Monitoring
バージョンを確認するには、以下のコマンドを実行します。
# instana version
Instana self-hosted: 253-1 3.253.268-0 (a948f12734f00173bac5980ef3d5c14d91cc0da6)
5. 2バージョンずつ3.4.を繰り返す。
段階的アップグレードの場合は、
2リリース毎にinstana-consoleのアップデートとinstana updateを繰り返します。
6. バージョンロックの適用 ⇨必要に応じて
一連のアップグレードが完了したら、最後にinstana-consoleのバージョンをロックします。
実施は任意ですが、別途OSのアップグレードを行っている場合は、意図せずinstana-consoleのバージョンが上がらないようにロックしておいた方が良いでしょう。
[root@instana-host]# yum versionlock list
versionlock list done
[root@instana-host]# yum versionlock instana-console
Adding versionlock on: 0:instana-console-253_1-1
versionlock added: 1
[root@instana-host]# yum versionlock list
0:instana-console-253_1-1.*
versionlock list done
[root@instana-host]#
Appendix. アップグレードに関するTips
アップグレードは概ねすんなりうまくいきますが、たまにうまくいかないこともあります。
以降は、うまくいかなかった場合の対処法の例をTipsとしてまとめます。
a. コンテナのダウンロードに失敗する
特にリリースされて間もない最新版にアップグレードした時に起こりやすいですが、instana updateコマンドの実行時の新しいコンテナイメージのダウンロードに失敗する場合があります。
その場合、マイナーリリースを1つ下げてみるとうまくいく可能性があります。
以下のコマンドで利用可能なリリースの一覧を確認します。
[root@instana-host]# yum --showduplicate list instana-console
例えば、うまくいかなかった現在のバージョンが253_1-1だった場合は、253_0-1にダウングレードを試します。
[root@instana-host]# yum -y downgrade instana-console-253_0
instana-consoleのダウングレードが完了したら、instana updateをリトライします。
b. アップグレード直後の起動に失敗する
instana update実行の最後にコンポーネントの起動確認(600秒)がありますが、そこで全てのコンテナが起動していないと失敗になります。
[root@instana-host]# instana update
Setup host environment ✓
Handle certificates ✓
Ensure images ✓
Clean docker containers ✓
Check data directories ✓
Run datastores ✓
Create configurations ✓
Migrate data stores ✓
Run components ✓
Check components ✗
component filler is unavailable
そのまま、もう一度instana updateをリトライすればうまくいくことが多いです。
イメージのダウンロードは完了しているので、
Run datastores→Run components→Check componentsとすんなり進みます。
気になる場合はdocker -aコマンドでコンテナの起動状況をウォッチできます。
c. データストアコンテナ関連のエラーでアップグレードが失敗する
Migrate data storesプロセスでエラーが発生した場合、ログの内容を確認して対処します。
[root@instana-host]# instana update
Setup host environment ✓
Handle certificates ✓
Ensure images ✓
Clean docker containers ✓
Check data directories ✓
Create configurations ✓
Run datastores ✓
Migrate data stores ✗
failed init for (metadata_ng-tu-onprem_xxx): failed to put mappings to index onprem_xxx_events_es7_20233: {"error":{"root_cause":[{"type":"cluster_block_exception","reason":"index [onprem_xxx_events_es7_20233] blocked by: [TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark, index has read-only-allow-delete block];"}],"type":"cluster_block_exception","reason":"index [onprem_xxx_events_es7_20233] blocked by: [TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark, index has read-only-allow-delete block];"},"status":429}
Instana Backendのデータディレクトリの使用率が90%を超えている場合は、コンテナの起動に失敗するようになっているようです。
今回のエラーの場合は、ディスクの拡張後に再試行してうまくいきました。
d. 新機能のフラグを有効化する
Backendを有効化しただけでは、有効にならない新機能もあります。
その場合は、ドキュメントに記載の通り、Featureフラグを設定します。
[root@instana-host]# cd ${INSTANA_DIR}
[root@instana-host]# vi settings.hcl
---(以下の行を追記)
feature "beeinstana" {
enabled=true
}
feature "infraEntityExplore" {
enabled=true
}
---
instana updateコマンドで適用します。Backendが再起動されます。
[root@instana-host]# instana update
e. Instanaエージェント導入時のClickhouse関連エラー
Build 247以降またはBuild 239-245の指定マイナーリリース以降にアップグレードした際に、
セキュリティのため、各データストアの通信が認証付きに変更となります。
その結果、Self-hosted自身の監視用にInstanaエージェント(infraモード)を導入している場合、
Instanaエージェントのログに大量のClickhouse認証エラーが出力されてしまいます。
2023-08-15T04:06:34.464+0900 | ERROR | se-fetch-metrics | ClickHouseClient | 193 - com.instana.sensor-clickhouse - 1.0.19 | Failed to execute query xxx
because: 'Code: 516. DB::Exception: default: Authentication failed: password is incorrect, or there is no user with such name.
(省略)
Clickhouseの認証情報はsettings.hclに追記されているので、
その情報を元にinstanaエージェントを設定します。
[root@instana-host]# cat << EOF > /opt/instana/agent/etc/instana/configuration_clickhouse.yaml
# Clickhouse
com.instana.plugin.clickhouse:
user: clickhouse # the username used to access ClickHouse's HTTP interface
password: <password> # the password used to access ClickHouse's HTTP interface
# protocol: http # 'http' or 'https'
# host: localhost # the host name or IP of the ClickHouse server
# httpPort: 8123 # the port of the ClickHouse server
f. Build 249以降のレポジトリ変更
リリースノートに記載の通り、instana-consoleを提供していたレポジトリが変更になったため、従来のレポジトリのままだとBuild 247までしかダウンロードできません。Build 249以降へアップグレードする場合は、レポジトリの内容を変更する必要があります。
[root@instana-host]# rm -f /etc/yum.repos.d/Instana-Product.repo
[root@instana-host]# export DOWNLOAD_KEY=XXXXX
[root@instana-host]# cat << EOF > /etc/yum.repos.d/Instana-Product.repo
[instana-product]
name=Instana-Product
baseurl=https://_:$DOWNLOAD_KEY@artifact-public.instana.io/artifactory/rel-rpm-public-virtual/
enabled=1
gpgcheck=0
gpgkey=https://_:$DOWNLOAD_KEY@artifact-public.instana.io/artifactory/api/security/keypair/public/repositories/rel-rpm-public-virtual
repo_gpgcheck=1
EOF
おわりに
Instana Self-Hosted on dockerのアップグレードに関するTipsをまとめました。
今後も何かあれば追記していきます。
少しでも参考になれば幸いです。