AKS 内で使用している Loki の Helm Chart を 5.x から 6.x へ アップデートした際に発生したエラーと解決方法
はじめに
Grafana Loki (以下、Loki) は、ログ集約システムとして、ユースケースの一つに、Kubernetes と併用して採用されており、Helm を使用してデプロイ・管理されています。また、Cloud マネージドな Kubernetes、例えば、Azure Kubernetes Service(以下、AKS)や Elastic Kubernetes Service(以下、EKS)では、コスト削減の観点からマネージドではない Loki を採用することがあります。この場合、Loki の Helm Chart のバージョンアップなど、バージョン管理作業を手動で実施する必要があります。
この記事では、Helm で管理している AKS 内の Loki の Helm Chart を、バージョン 5.x から最新(2025年4月15日時点)のバージョン 6.x へ、手動アップデートした際に発生したエラーとそれを解決する方法を確認します。
前提条件
- Kubernetes クラスター v1.31.x の AKS
- kubectl v1.31.6
- Helm v3.17.1
- バックアップなどのアップデート事前準備作業が完了済み
- バージョンアップ前の Loki の Helm Chart v5.x
- バージョンアップ後の Loki の Helm Chart v6.x
発生したエラーと調査
バックアップなどのすべてのアップデート前準備を完了したのちに下記のコマンドを実行すると、エラーが発生しました。
# 実行コマンド
$ helm upgrade loki grafana/loki -n ${NAME_SAPCE} --version 6.29.0 --dry-run
# 出力されたエラー
Error: UPGRADE FAILED: execution error at (loki/templates/validate.yaml:40:4): You must provide a schema_config for Loki, one is not provided as this will be individual for every Loki cluster. See https://grafana.com/docs/loki/latest/operations/storage/schema/ for schema information. For quick testing (with no persistence) add `--set loki.useTestSchema=true`
schema_config が未定義もしくは正しく値を受け渡せていないことが原因でエラーが出ていそうなので、Loki の Helm Chart にてユーザが定義した値を下記コマンドで出力して確認します。
$ helm get values loki -n ${NAME_SAPCE} > loki-values.yaml
出力した loki-values.yaml を確認すると、公式ドキュメントに記載の通り schema_config が定義されていました。
# ~~~~~~~~ 省略
schema_config:
configs:
- from: "2024-04-01"
index:
period: 24h
prefix: loki_index_
object_store: azure
schema: v13
store: tsdb
# ~~~~~~~~ 省略
公式ドキュメント通りに schema_config が定義されていることを確認したのちに、Upgrade Loki や Upgrading to v6.x、Artifact HUB: Loki を確認してみましたが、解決に至りそうなテキストは見つかりませんでした。。。
ドキュメントでは解決に至らなかったので、Loki の GitHub リポジトリの Issues と Pull requests を確認してみると、解決策にたどり着きました。
解決策
解決策は schema_config を schemaConfig に修正する です。
こちらの Issues で今回発生していたエラーと近しいエラーに対する問題が挙げられていました。
loki-values.yamlを下記の通り修正します。
# ~~~~~~~~ 省略
schemaConfig: # ここを schema_config から schemaConfig に修正した。
configs:
- from: "2020-12-11"
index:
period: 24h
prefix: index_
object_store: azure
schema: v13
store: tsdb
# ~~~~~~~~ 省略
修正後、下記のコマンドを実行すると、アップデートシミュレーションが成功しました。
$ helm upgrade loki grafana/loki -n ${NAME_SAPCE} --version 6.29.0 -f loki-values.yaml --dry-run
--dry-run フラグを外してコマンドを実行、アップデートを実施、Helm や kubectl、Azure Portal などを駆使して動作確認をしたところ、問題なくアップデートが完了しました。
schemaConfig に変更されたバージョン
Loki の Helm Chart のスキーマが schema_config から schemaConfig に変更されたバージョンを簡易的に確認したところ、Loki の Helm Chart のバージョンが 6.x にアップデートされたタイミングでこの問題が発生していそうでした。(5.48.0までは schema_config 定義でアップデート可能でした。)
ただ、こちらの調査はローカル環境で helm upgrade ~ --version x.x.x の x.x.x にリリースされている適当なバージョンをあてはめて実行して確認したため、ご参考までにとどめていただけますと幸いです。
余談ですが、Loki の Helm Chart 6.x では大幅なアップデートがあり、いくつかの破壊的変更が含まれているようです。
The Helm chart has gone through some significant changes and has a separate upgrade guide: Upgrading to Helm 6.x.
引用元：https://grafana.com/docs/loki/latest/setup/upgrade/#300
まとめ
Loki のバージョン 5.x から 6.x へのアップデートは、ユーザが定義した値を修正せずに helm upgrade ~ を実行するだけではアップデートできず、5.x の values.yaml を 6.x に適応したスキーマに修正してからアップデートを行う必要がありました。Kubernetes 内の Loki を Helm 管理する場合には、手動でのバージョン管理から逃れることができないので、引き続き安全にアップデートできるようにしていきたいと思います。
Discussion