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

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

構文

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

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

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

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

例：

# ファイルから読み込む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://...文字列としてすべてのノードに伝播し、各ノードが自身のファイルを開きます。

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

適用箇所

file://方式は設定スキーマでシークレット型が使われている箇所で有効です。主な例は以下の通りです。

• SSL/TLSリスナー: listeners.<type>.<name>.ssl_options.password（キーのパスフレーズ）。詳細はEnable SSL/TLSを参照してください。
• ブリッジおよびコネクター: パスワード、APIキー、シークレットアクセスキー、JWTトークン、サービスアカウントJSON認証情報（service_account_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://がサポートされているかは、各フィールドのスキーマタイプを確認してください。