Grafana のサーバーの動作は、INI ファイルと、それを上書きする環境変数で制御されます。ルールを知っていれば、設定全体をリポジトリに保管して、手作業では何も変更しないようにできます。このガイドでは、ファイルの場所、優先順位の仕組み、値とシークレットの注入方法、そして最もよく触れる設定を説明します。

設定の場所

• defaults.ini は Grafana に同梱されており、すべてのデフォルトを保持しています（tarball のインストールでは conf/ にあります）。決して編集しないでください。どのようなオプションが存在するかの、最良のリファレンスです。
• grafana.ini は、ご自身の設定ファイルです。Linux のパッケージでは /etc/grafana/grafana.ini で、公式の Docker イメージも同じパスを読み取ります。tarball のインストールでは、conf/custom.ini を使います。別のファイルを指すには --config を渡します。
• GF_ で始まる環境変数は、その両方を上書きします。

優先順位は、低いものから高いものの順に、defaults.ini、ご自身の grafana.ini、GF_* 環境変数（とコマンドラインのフラグ）です。変更したいオプションだけをファイルに記述してください。そうすれば diff が小さく保たれます。

INI ファイルでは、; で始まる行はコメントなので、オプションを有効にするには、先頭の ; を削除します。

;http_port = 3000   # 無視される
http_port = 3000    # 有効

ファイルや環境を変更した後は、Grafana を再起動してください。

環境変数による上書き

パターンは GF_<SECTION>_<KEY> で、セクションとキーは大文字にし、. や - は _ に置き換えます。

GF_SECURITY_ADMIN_USER=owner          # [security] admin_user
GF_SERVER_ROOT_URL=https://grafana.example.com   # [server] root_url
GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey        # [auth.google] client_secret
GF_FEATURE_TOGGLES_newNavigation=true            # [feature_toggles] newNavigation
GF_DEFAULT_INSTANCE_NAME=my-instance             # 最上位の instance_name、セクションなし

環境変数は、コンテナや Kubernetes に自然に適合します。同じファイルをすべての環境で共有しつつ、環境固有の値（URL、パスワード）はプラットフォームから渡せるからです。

ファイル内での変数展開

オプションの値は、$__env{} や $__file{} のプロバイダー、または ${NAME} の短縮形で、環境変数やファイルを参照できます。

[paths]
logs = $__env{LOGDIR}/grafana

[security]
admin_password = ${GF_ADMIN_PASSWORD}
secret_key = $__file{/run/secrets/grafana_secret_key}

[database]
password = $__file{/etc/secrets/gf_sql_password}

$__file{} はファイルを読み取り、先頭と末尾の空白を取り除くため、ファイルとしてマウントされた Docker や Kubernetes のシークレットに適しています。Grafana Enterprise には、$__vault{} プロバイダーもあります。公式の Docker イメージはさらに、変数名の __FILE サフィックスも受け付けます（たとえば GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password）。これはシークレットのガイドで説明します。

実用的なベースライン

小規模な、本番に近い構成のための短い grafana.ini です。

[paths]
provisioning = /etc/grafana/provisioning

[server]
protocol = http
http_port = 3000
domain = grafana.example.com
root_url = https://grafana.example.com/
; /grafana から提供する場合は、root_url にサブパスを追加し、これを有効にする
; serve_from_sub_path = true

[database]
type = postgres
host = postgres:5432
name = grafana
user = grafana
password = $__file{/run/secrets/grafana_db_password}

[security]
admin_user = admin
admin_password = $__file{/run/secrets/grafana_admin_password}
secret_key = $__file{/run/secrets/grafana_secret_key}
cookie_secure = true

[users]
allow_sign_up = false

[analytics]
reporting_enabled = false
check_for_updates = false

[log]
mode = console
level = info

知っておく価値のある点：

• データベース。 デフォルトは SQLite で、単一のインスタンスやテストには問題ありません。本番には PostgreSQL や MySQL を使い、Grafana のレプリカが複数ある場合は、常にそうしてください。
• root_url は公開アドレスと一致している必要があります。そうでないと、アラート通知のリンクや OAuth のリダイレクトが間違ったものになります。サブパスの下で Grafana を提供するリバースプロキシの背後では、そのパスを root_url に追加し、serve_from_sub_path = true を設定します。
• admin_password は、Grafana が最初にデータベースを作成するときにだけ適用されます。後で設定を変更しても、既存の admin ユーザーのパスワードは変わりません。
• secret_key は、Grafana がデータソース用に保存するシークレットを暗号化します。変更すると、以前に保存されたシークレットが読めなくなり、データソースを再度プロビジョニングする必要があります。明示的に設定し、軽々しくローテーションしないでください。
• [paths] provisioning は、Grafana がプロビジョニングフォルダーを探す場所です。パッケージでのデフォルトは /etc/grafana/provisioning です。

メールアラート用の SMTP

[smtp]
enabled = true
host = smtp.example.com:587
user = grafana@example.com
password = $__file{/run/secrets/smtp_password}
from_address = grafana@example.com
from_name = Grafana
startTLS_policy = OpportunisticStartTLS

あるいは、同じことを GF_SMTP_ENABLED=true、GF_SMTP_HOST=... などで行います。オプション名は、お使いのバージョンの defaults.ini で確認してください。

feature toggle

実験的な機能やオプトインの機能は、専用のセクションでオンにします。

[feature_toggles]
; お使いのバージョンのドキュメントに従って、必要な toggle を列挙する
newNavigation = true

UI ではなく、ファイルや環境を優先してください。そうすれば、再構築しても設定が残ります。toggle はリリース間で現れたり消えたりするため、アップグレードのたびに確認してください。

有効な設定を検証して調べる

Grafana を起動した後、設定したものと有効なものを比較できます。

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD http://localhost:3000/api/admin/settings | jq '.server'

この管理用のエンドポイントは、マージされた設定を返し、機密性のあるキーの値はマスクされます。環境変数が実際に効果を持ったことを確認する、最も手早い方法です。そうでない場合は、変数のスペル（大文字、アンダースコア）と、そのオプションが defaults.ini に存在することを確認してください。

Git に保管する

• grafana.ini と、プレースホルダーの値を持つ .env.example を commit します。
• 実際のシークレットはリポジトリの外に置きます。ファイルとしてマウントする、環境変数として注入する、または暗号化して commit します（シークレットのガイドを参照）。
• Grafana をアップグレードするときは、defaults.ini の変更を確認してください。新しいリリースでは、オプションが追加され、ときには古いものが非推奨になります。