ファイルからシークレットを読み込む

多くの EMQX 設定項目には機密性の高い値が含まれます。例として、SSLリスナーのキーのパスフレーズ、ブリッジやコネクターのパスワード、OIDCクライアントシークレット、S3のシークレットアクセスキー、APIキーなどがあります。これらの値を emqx.conf に直接埋め込んだり、APIリクエストに含めたりすることを避けるために、EMQX はシークレット型フィールドに対して file:// URL プレフィックスをサポートしています。EMQX は起動時および設定のリロード時に参照されたファイルからシークレットを読み込みます。

構文

シークレットとしてドキュメント化されているフィールド（またはダッシュボードのツールチップに file:// オプションが記載されているフィールド）には、以下の形式を使用してください。

file://<ファイルへのパス>

パスは絶対パスでも、EMQX の作業ディレクトリからの相対パスでもかまいません。ファイルの内容全体がシークレット値として使用されますが、1つの変換が行われます。

• 末尾の空白文字は削除されます。末尾の改行、復帰、スペース、タブ文字はすべて取り除かれます。先頭および内部の内容はそのまま使用されます。

例：

# ファイルから読み込むSSLリスナーのキーのパスフレーズ
listeners.ssl.default.ssl_options.password = "file://etc/certs/key-passphrase"

# ファイルから読み込むMQTTブリッジのパスワード
bridges.mqtt.upstream.password = "file:///run/secrets/upstream-mqtt-password"

クラスターでの考慮事項

EMQXをクラスターで運用する場合、設定を読み込むすべてのノードがファイルパスを解決できる必要があります。

• 設定を読み込むすべての EMQX ノードにファイルが存在している必要があります。同じパスはノードごとに異なるファイルを指し示します。EMQX はノード間でファイルをコピーしません。
• ファイルの内容はノード間で一致しているべきです。そうでないと、同じ設定項目に対してノードごとに異なるシークレット値が使用されてしまいます。
• ダッシュボードや REST API 経由で設定された場合、変更は file://... 文字列としてすべてのノードに伝播され、各ノードが自身のファイルを開きます。

一般的なパターンとしては、EMQX 起動前にデプロイメントツール（Kubernetes Secrets、Ansible、構成管理ツールなど）を使ってシークレットファイルをプロビジョニングし、すべてのノードで同じパスに配置します。

適用される箇所

file:// の形式は、設定スキーマがシークレット型を使用している箇所で利用可能です。主な例は以下の通りです。

• SSL/TLSリスナー：listeners.<type>.<name>.ssl_options.password（キーのパスフレーズ）。詳細は Enable SSL/TLS を参照してください。
• ブリッジおよびコネクター：パスワード、APIキー、シークレットアクセスキー、JWTトークン、service_account_json のようなサービスアカウントJSON認証情報。
• クラスターリンク：cluster.links[].password。
• ダッシュボードSSO（OIDC）：dashboard.sso.oidc.secret。
• ライセンス：license.key（ライセンス文字列自体）。詳細は License Configuration を参照してください。
• AI補完：ai.completion_profile.api_key。

特定のフィールドが file:// を受け入れる場合、そのフィールドのダッシュボードのツールチップに明示的に記載されています。

ロギングとマスキング

EMQX はログやHTTP APIレスポンスからシークレット値をマスキングします。シークレットが file://... URL として設定されている場合、EMQX はファイルの内容ではなくパス自体をログに記録します。これにより、運用者はどのファイルをノードが読み込んでいるかを確認できます。ファイルから抽出されたシークレット値がログに出力されることはありません。

file:// を使わない方がよい場合

設定フィールドが通常の string 型（シークレット型でない）である場合、値の先頭に file:// を付けてもファイル参照としては扱われず、そのままの文字列として解釈されます。file:// がサポートされているかどうかは、各フィールドのスキーマタイプを確認してください。