Instana Self-Hosted on dockerのアップグレードに関するTips

# はじめに
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となる。それ以前のバージョンを使用している場合は段階的にアップグレードを行う必要があります。

:::note info
[リリースノート][1]にアップグレードに関する**Release information**ならびに**Installation instructions**が記載されていることがあるため、必ず目を通しておくことをお勧めします。
:::

[1]:https://www.ibm.com/docs/en/instana-observability/current?topic=release-notes

# アップグレードの大まかな手順と流れ
ドキュメントにも記載がありますが、要約すると以下の流れです。
1. バージョンロックの解除　⇨バージョンロック適用時のみ
2. バックアップの取得（バージョンロック解除前でも良い）⇨必要に応じて ※本記事では省略
3. `instana-console`パッケージのアップデート
4. `instana update`コマンドでInstana Backendのアップグレード
5. 段階的アップグレードの場合、2バージョンずつ3.4.を繰り返す。
6. バージョンロックの適用　⇨必要に応じて

## 1. バージョンロックの解除
ドキュメントに記載の手順でBackendインストールをしている場合は、最後にバージョンロックの設定が記載されているので、まずはそれを解除します。
```bash
[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. バックアップの取得
本記事では省略します。
必要に応じて、ドキュメントに記載のデータバックアップを行います。

:::note warn
バックアップを取得する場合は、静止点のためBackendを停止する必要があります。
:::

## 3. `instana-console`パッケージのアップデート
まずは`instana-console`パッケージをアップデートする必要があります。
普通にアップデートすると利用可能な最新バージョンになるので、アップグレードパスに従い適切なバージョンをインストールします。ターゲットバージョンを指定して、後ろに`*`をつけると最新のマイナーバージョンが自動選択されるので楽です。（Build 245辺りで微妙に表記が変わったのにも対応可）
```bash
[root@instana-host]# export TARGET_VERSION=XXX
[root@instana-host]# yum update instana-console-${TARGET_VERSION}*
```

参考までに、インストール可能なバージョンの一覧を取得するには、yumリポジトリを更新してから以下のコマンドを実行します。
```bash
[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`ファイルの場所を指定してコマンドを実行します。

```bash
[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**プロセスでその他のコンテナの起動が行われて、正常に起動したことが確認されると一連のアップグレード処理は完了です。

最終的に、以下のようなメッセージが表示されたら成功です。
```bash
[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
```
バージョンを確認するには、以下のコマンドを実行します。
```bash
# 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`のバージョンが上がらないようにロックしておいた方が良いでしょう。
```bash
[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つ下げてみるとうまくいく可能性があります。
以下のコマンドで利用可能なリリースの一覧を確認します。
```bash
[root@instana-host]# yum --showduplicate list instana-console
```
例えば、うまくいかなかった現在のバージョンが`253_1-1`だった場合は、`253_0-1`にダウングレードを試します。
```bash
[root@instana-host]# yum -y downgrade instana-console-253_0
```
`instana-console`のダウングレードが完了したら、`instana update`をリトライします。

## b. アップグレード直後の起動に失敗する
`instana update`実行の最後にコンポーネントの起動確認(600秒)がありますが、そこで全てのコンテナが起動していないと失敗になります。

```bash
[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**プロセスでエラーが発生した場合、ログの内容を確認して対処します。

```bash
[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を有効化しただけでは、有効にならない新機能もあります。
その場合は、[ドキュメント][d1]に記載の通り、Featureフラグを設定します。

[d1]:https://www.ibm.com/docs/en/instana-observability/current?topic=installer-installing-instana-backend-docker#optional-features

```bash
[root@instana-host]# cd ${INSTANA_DIR}
[root@instana-host]# vi settings.hcl
---(以下の行を追記)
feature "beeinstana" {
  enabled=true
}
feature "infraEntityExplore" {
  enabled=true
}
---
```
`instana update`コマンドで適用します。Backendが再起動されます。
```bash
[root@instana-host]# instana update
```

## e. Instanaエージェント導入時のClickhouse関連エラー
Build 247以降または[Build 239-245の指定マイナーリリース以降][e1]にアップグレードした際に、
セキュリティのため、各データストアの通信が認証付きに変更となります。

[e1]:https://www.ibm.com/support/pages/node/6959969

その結果、Self-hosted自身の監視用にInstanaエージェント(infraモード)を導入している場合、
Instanaエージェントのログに大量のClickhouse認証エラーが出力されてしまいます。
```bash
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エージェントを設定します。

```bash
[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以降のレポジトリ変更
[リリースノート][f1]に記載の通り、`instana-console`を提供していたレポジトリが変更になったため、従来のレポジトリのままだとBuild 247までしかダウンロードできません。Build 249以降へアップグレードする場合は、レポジトリの内容を変更する必要があります。

[f1]:https://www.ibm.com/docs/en/instana-observability/249?topic=docker-build-249#release-information

```bash
[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をまとめました。
今後も何かあれば追記していきます。
少しでも参考になれば幸いです。