はじめに

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 管理する場合には、手動でのバージョン管理から逃れることができないので、引き続き安全にアップデートできるようにしていきたいと思います。

# 参考リンク

- [Grafana Loki 公式ドキュメント](https://grafana.com/docs/loki/latest/)
- [Grafana Loki 公式ドキュメント | Storage schema](https://grafana.com/docs/loki/latest/operations/storage/schema/)
- [Grafana Loki 公式ドキュメント | Upgrade Loki](https://grafana.com/docs/loki/latest/setup/upgrade/#upgrade-loki)
- [Grafana Loki 公式ドキュメント | Upgrading to v6.x](https://grafana.com/docs/loki/latest/setup/upgrade/upgrade-to-6x/#upgra…)
- [Grafana Loki 公式ドキュメント | Loki 6.0 リリースノート](https://grafana.com/docs/loki/latest/release-notes/)
- [GitHub リポジトリ | grafana/loki](https://github.com/grafana/loki)
- [GitHub リポジトリ | grafana/loki | Helm Chart](https://github.com/grafana/helm-charts/tree/main/charts/loki)
- [ArtifactHUB: Loki v6.29.0](https://artifacthub.io/packages/helm/grafana/loki/)