grafana

Grafana の運用

Grafana は、バージョン管理され、個別に認可されるリソースの集合として扱い、各リソースに明確な所有者を定めます。変更を提案する前に、対象、リソースの由来、実際に適用されるルーティングを確認します。サーバーが正常に稼働していることや、魅力的なダッシュボードがあることは、プロビジョニング、クエリ、アラート評価、通知配信が機能している証拠にはなりません。

運用上の取り決め

1. API やワークフローを選択する前に、Grafana のバージョン、エディション、デプロイモード、組織、フォルダーまたは名前空間、認証方式、現在の権限範囲を特定します。
2. 既存のファイルプロビジョニング、Terraform／プロバイダーの状態、Git Sync、Grafana Operator のリソース、API／UI で管理されているオブジェクトを一覧化します。変更前に、各リソース UID の正式な所有者を 1 つ定めます。
3. 操作前に対象、範囲、ロールバック手順を確認します。読み取り専用の調査は確認なしで進められます。
4. ダッシュボード、フォルダー、データソース、アラート、ユーザー／RBAC、プラグイン、サーバー設定の変更は、それぞれ別個の認可範囲として扱います。
5. サービスアカウントトークン、パスワード、secureJsonData、復号されたレシーバー設定、OAuth シークレット、署名キー、SMTP 認証情報、Webhook のシークレット値を表示、コミット、または保存しないでください。サポートされているセキュアな設定フィールドは、認可されたシークレット管理方式で保持し、記録するのは秘匿化したメタデータのみとします。
6. アクセスできる場合は、実際のデータソースに対してダッシュボードとアラートのクエリを検証します。アクセスできない場合は、オフラインであるという制約を明記し、意味的な正しさを主張しないでください。
7. 要求された境界を検証します。サーバーの健全性はダッシュボードのプロビジョニングを証明しません。ルールの発火はルーティングを証明しません。通知の配信は解決時の動作を証明しません。

使用しない場合

SLI、SLO、エラーバジェット、ページ通知の要否、重大度ポリシー、エスカレーション、インシデント対応の実践を定義するには、site-reliability-engineering を使用します。PromQL、LogQL、TraceQL、Flux、SQL、ストレージ、バックエンドの運用には、各データソースに固有のガイダンスを使用します。各インフラストラクチャのコントロールプレーンには、docker-compose、kubernetes、traefik、または platform-engineering を使用します。予防的なセキュリティ設計には secure-software-engineering を、認可された評価には security-audit-methodology を使用します。このスキルの対象は、Grafana 製品の動作と Grafana 側の統合です。

読み取り専用の調査

現在のアクセスで許可される範囲に限って情報を収集します。

grafana server -v
curl --fail --silent --show-error "$GRAFANA_URL/api/health"

コンテナー、パッケージ、Helm、または Cloud については、管理元のプラットフォームで読み取り専用のインベントリーを使い、イメージ／タグ、設定パス、デプロイモード、公開境界を確認します。プロセス環境や、シークレットを含む解決済み設定をダンプしないでください。認可されたサービスアカウントトークンがある場合は、対象のリソース種別を絞った GET リクエストを優先します。トークンはコマンド履歴やレポートに残さず、保護された環境または認証情報ストアを通じて渡します。

以下を記録します。

• バージョンとエディション：OSS、Enterprise、または Cloud。
• デプロイの管理者と永続化方式：パッケージ、コンテナー、Compose、Kubernetes、Helm、Operator、またはマネージドスタック。
• 組織、フォルダー、名前空間、対象環境。
• 認証方式と実効権限。
• セキュアなフィールドを含めずに、データソース UID と種類。
• ダッシュボード／フォルダー UID、アラートリソース、およびその由来。
• プロビジョニングプロバイダー、監視対象パス、ポーリング間隔、削除／編集設定、所有権の重複。
• ロールバック元と、安全にテストできる境界。

エンドポイントを選択する前に、API とバージョンの調査を参照してください。Grafana 12 では新しい /apis モデルが導入されました。一方、従来の /api ルートは Grafana 13 から非推奨化が始まりますが、現時点では完全な一対一の代替手段はありません。

タスクの振り分け

必要な作業	最初に読むもの
バージョン、エディション、認証、組織、リソース API、権限の範囲を確認する	API とバージョンの確認
ダッシュボード、パネル、変数、単位、変換、リンク、注釈、ライブラリパネル、JSON、アクセシビリティを設計またはレビューする	ダッシュボードの設計
ルール評価、ラベル、コンタクトポイント、ポリシー、グルーピング、サイレンス、ミュート時間、テンプレート、通知配信を構築または診断する	アラートとルーティング
ファイルプロビジョニング、Terraform、Git Sync、API、Foundation SDK、Operator の所有権を選択または調整する	プロビジョニングと GitOps
空白のパネル、クエリ／認証の失敗、プロビジョニングのドリフト、評価の失敗、通知の欠落、プロキシ／認証の問題を診断する	トラブルシューティング
認証情報、ユーザー、サービスアカウント、RBAC、プラグイン、削除、共有、本番環境に影響する変更を扱う	セキュリティと変更管理
根拠、バージョンの最新性、現在の調査結果、更新ルールを確認する	ソースインデックス

安全なワークフロー

1. 運用上の成果を定義する

対象者、判断事項、リソース UID、正式な所有者、対象環境、想定される中断、検証方法、ロールバックを明確にします。ダッシュボードの場合は、可観測性の手法または問いを明示します。アラートの場合は、所有者、重大度の根拠、ランブック／ダッシュボードへのリンク、想定されるルート、ノイズのリスクを明示します。

2. 内容を変更する前に所有権を調整する

稼働中のオブジェクトを、書き込みを行う可能性のあるすべての手段と照らし合わせます。その手段で変更できるというだけの理由で、プロビジョニング済みのリソースを別の手段から編集しないでください。ファイルまたはオブジェクトを変更する前に、プロバイダー経路の重複、UID またはタイトルの重複、Terraform／API のドリフト、上書きされる UI 編集、削除またはプルーニングの動作を検出します。

3. 表示より先に意味を検証する

既知の時間範囲で代表的なクエリを実行します。メトリクス／ログ／トレースの種類、単位、ラベル、集計、カーディナリティ、null／データなしの動作、タイムゾーン、更新間隔、クエリコストを確認します。デフォルト値、しきい値、更新間隔、上位 N 件の上限、最小トラフィックのしきい値は、対象の証拠、承認済みポリシー、または明示的な測定目標から導き出します。そうでない場合は、もっともらしい値を選ぶのではなく未確定のままにします。繰り返し使うパネルや多次元アラートでは、次元の集合に上限を設け、それが実用的な範囲に保たれることを証明します。

4. 所有者を通じてプレビューし、適用する

正式なソースと、サポートされている中で最も範囲の狭い操作を使用します。差分と、シークレットをマスキングしたエクスポート済みバックアップを確認します。ポリシーツリーの置き換え、prune、プロバイダーソースの削除、UID の再利用、RBAC の変更、プラグインのインストール、データソース／ダッシュボードの削除を行う場合は、変更を加える直前に明示的な確認を得る必要があります。

5. 影響を受ける各プレーンを検証する

プレーン	最低限の証拠
サーバー	バージョン情報を含むプロセスが応答し、データベースの正常性が報告される。範囲を限定したログに、新たな障害ループがない
プロビジョニング	UID／パスごとに所有者が 1 つだけである。調整が完了する。複数回のスキャンにわたって重複／ドリフトの警告がない
データソース	認証済みのヘルスチェック／クエリテストが、想定した時間範囲と代表的なデータで成功する
ダッシュボード	クエリの意味が正しい。単位／ラベル／空の状態が正しく表示される。リンクと変数がコンテキストを維持する
アラート評価	想定される正常、保留中、発火、データなし／エラー、復旧時の動作を確認するか、未テストであることを明示する
通知ルーティング	実際のラベルが意図したポリシー／コンタクトポイントを選択する。グルーピングとミュートの動作を確認する
通知配信	制御されたテストが意図した受信先に届く。許可されている場合、解決通知も確認する
アクセス	意図したロールで操作できる。より低い権限のロールでは操作できない。シークレットがマスキングされている

承認の境界

パスワードのリセット、ユーザー・組織・チーム・サービスアカウント・RBAC の変更、プラグインのインストールまたは削除、データソース・ダッシュボード・フォルダー・アラートルール・コンタクトポイント・ポリシーの削除、通知ポリシーの置き換え、実際の通知テスト、プロビジョニングの再読み込みまたはサービスの再起動、シークレットのローテーション、匿名／公開共有の変更、またはデータベースの直接復旧を行う前に、明示的な承認が必要です。バックアップを取得し、サポート対象の代替手段をすべて試した後、ユーザーが文書化された復旧手順を明示的に承認しない限り、Grafana のデータベースを直接編集してはいけません。

完了条件

依頼されたリソースまたは診断が、既知の Grafana のバージョンと所有者に紐づけられ、関連するクエリまたはルートが承認された最も強い境界で検証され、シークレットが公開されず、ロールバックが可能な状態であれば、タスクは完了です。認証済み API インベントリ、実際のデータソースクエリ、アラートの発報、レシーバーへの配信、解決済み通知、アクセシビリティテスト、再読み込み／再起動後の永続性、本番環境での動作など、実施していない、より強い境界をすべて列挙してください。