すべてがファイルで定義されていると、失敗もファイルの中にあります。誤ったインデント、欠けている UID、コンテナ内に存在しないパスなどです。Grafana は自分が何をしたかを教えてくれますが、どこを見るべきかを知っている必要があります。このガイドでは、再読み込みのエンドポイント、いくつかの確認コマンド、そして最も遭遇しやすいエラーを説明するので、UI を開かずにそれらを修正できます。

何がいつ適用されるか

リソース	読み込まれるタイミング	再適用する方法
grafana.ini と GF_* 環境変数	起動時のみ	Grafana を再起動
データソース	起動時	再起動、または再読み込みのエンドポイント
ダッシュボード	起動時、その後 updateIntervalSeconds ごと	待つか、再読み込みのエンドポイント
アラートのリソース	起動時	再起動（または、お使いのバージョンのドキュメントに従い、Admin API でプロビジョニングを再実行）
プラグインアプリの設定	起動時	再起動、または再読み込みのエンドポイント

再起動せずに再読み込みする

これらの admin のエンドポイントは、プロビジョニングのファイルを再読み込みします。POST を使い、Grafana の admin ユーザーでの Basic 認証が必要です。API トークンは Admin API では機能しません。

BASE=http://localhost:3000
AUTH="admin:$GRAFANA_ADMIN_PASSWORD"

curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/dashboards/reload
curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/datasources/reload
curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/plugins/reload
curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/notifications/reload

成功した呼び出しは、設定が再読み込みされたことを示す JSON のメッセージを返します。admin の認証情報が必要なため、これらのエンドポイントを公開しないでください。それ以外のことには、再起動が常に安全です。

Grafana が実際に読み込んだものを確認する

ファイルと API のビューを比較します。

# ヘルス
curl -s $BASE/api/health

# 有効なサーバー設定（機密の値はマスクされる）
curl -s -u "$AUTH" $BASE/api/admin/settings | jq '.paths, .server'

# データソース。プロビジョニングされたものには読み取り専用のフラグが付く
curl -s -u "$AUTH" $BASE/api/datasources | jq '.[] | {name, uid, type, readOnly}'

# データソースの接続性
curl -s -u "$AUTH" $BASE/api/datasources/uid/prometheus/health

# ダッシュボードとフォルダー
curl -s -u "$AUTH" "$BASE/api/search?type=dash-db" | jq '.[] | {title, uid, folderTitle}'
curl -s -u "$AUTH" $BASE/api/folders | jq '.[] | {title, uid}'

# アラート
curl -s -u "$AUTH" $BASE/api/v1/provisioning/alert-rules | jq '.[] | {uid, title}'
curl -s -u "$AUTH" $BASE/api/v1/provisioning/contact-points | jq '.[].name'
curl -s -u "$AUTH" $BASE/api/v1/provisioning/policies | jq .

プロビジョニングしたものがこれらの一覧に欠けている場合は、ログがその理由を教えてくれます。

ログを読む

プロビジョニングのメッセージは、名前が provisioning で始まるロガーから出力されます。デバッグ中は、詳細度を上げます。

# docker compose
GF_LOG_LEVEL=debug docker compose up -d grafana
docker compose logs grafana | grep -i provision

# kubernetes
kubectl logs deploy/grafana -n monitoring -c grafana | grep -i provision

メッセージの中のファイル名を探してください。Grafana は、解析に失敗したファイルや、拒否したリソースを示します。

Grafana に届く前にファイルを確認する

ほとんどのエラーは CI で検出できます。

# YAML の構文
yamllint grafana/provisioning

# JSON の構文と必須フィールド
jq empty dashboards/**/*.json
jq -e '.uid and .title' dashboards/*/*.json >/dev/null

# ダッシュボードの UID の重複
jq -r '.uid' dashboards/*/*.json | sort | uniq -d

# プロビジョニングされるすべてのファイルが apiVersion: 1 で始まっているか？
grep -L '^apiVersion: 1' grafana/provisioning/*/*.yaml

安価なエンドツーエンドのテストは、CI で同じファイルから使い捨ての Grafana を起動し、/api/health を待ち、上の API の出力に対してアサートすることです。

よくある問題と修正

データソースやダッシュボードが現れない。 プロビジョニングのフォルダーが、Grafana が探す場所にマウントされていません。[paths] provisioning（デフォルトは /etc/grafana/provisioning）がマウントと一致していること、サブフォルダー名がちょうど datasources、dashboards、alerting、plugins であることを確認します。

ファイルの読み取りで「Permission denied」。 公式イメージは root 以外のユーザーとして実行されるため、マウントされたファイルは、そのユーザーが読み取れる必要があります。全員が読めるようにする（chmod -R a+rX）か、ボリュームの所有権を合わせます。

ダッシュボードが「Dashboard title cannot be empty」で失敗する。 JSON が API のエンベロープ（{"dashboard": {...}}）で包まれています。プロビジョニングされるファイルには、ダッシュボードのモデル自体が含まれている必要があります。

ダッシュボードは読み込まれるが、パネルがデータソースが見つからないと言う。 パネルが、プロビジョニングされていない UID を参照しているか、ファイルにエクスポートからの ${DS_...} のプレースホルダーが残っています。データソースのファイルで uid を設定し、ダッシュボードの JSON で同じ UID を使います。

2 つのダッシュボードが競合する、または 1 つが元に戻り続ける。 uid を共有しているか、同じフォルダーで同じタイトルを使っています。すべての UID を、インストール全体で一意にします。UI での編集が上書きされ続ける場合、それはファイルが優先されているのであり、プロバイダーが allowUiUpdates: true を持たない限り、設計どおりです。

ファイルを削除したのにダッシュボードがまだある。 プロバイダーが disableDeletion: true を持っているか、ダッシュボードが手作業でフォルダーに移動されました。API で削除するか、disableDeletion をオフにします。

複数インスタンスの構成で、データソースの変更が無視される。 複数の Grafana レプリカがあると、インスタンスは、ファイルの version が保存されているものと同じかそれ以上のときだけ、データソースを更新します。ファイルを変更するときは、version を上げます。

環境変数が置換されない。 補間は、キーではなく値に適用されます。ダッシュボードの JSON、アラートルールのアノテーション、クエリのモデル、ミュートタイミング、テンプレートでは機能しません。コンテナ内で変数が実際に設定されていることを確認してください（docker compose exec grafana env | grep NAME）。

アラートのインポートの競合。 手作業の編集で、同じ UID や名前のリソースが存在します。手作業で作ったものを削除するか、ファイルの delete... ブロックに追加してから、再起動します。

再構築後にシークレットが機能しなくなった。 secret_key が変わったため、保存されたシークレットを復号できません。元のキーを復元するか、認証情報が必要なデータソースを再プロビジョニングします。

admin パスワードが変更されなかった。 admin_password は、データベースの初回作成時にのみ適用されます。grafana cli admin reset-admin-password を使うか、ボリュームを再作成します。

Helm や Operator のリソースが同期されない。 チャートでは、サイドカーのコンテナのログで、ラベルや namespace の不一致を確認します。Operator では、リソースに kubectl describe を実行し、そのステータス条件を読みます。

信頼できる変更の手順

1. ブランチでファイルを変更します。
2. CI が上のリンターを実行し、ファイルから使い捨ての Grafana を起動します。
3. マージします。配信メカニズムが Grafana を再起動または調整します。
4. /api/health と確認コマンドを確認します。
5. おかしな動作をしたら、commit を revert します。ファイルが真実なので、revert すれば以前の状態が復元されます。