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

多くの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://...文字列としてすべてのノードに伝播され、各ノードが自身のファイルを開きます。

一般的なパターンとしては、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 6.3.0以降、node.cookieおよび環境変数オーバーライドのEMQX_NODE__COOKIEはfile://を受け入れます。これは文字列型フィールドのデフォルト動作に対する明示的な例外です。

emqx.confにノードクッキーをプレーンテキストで保存したくない場合は、node.cookieをファイルURLに設定してください。

node.cookie = "file:///run/secrets/emqx-cookie"

または、EMQX_NODE__COOKIEを設定します。

export EMQX_NODE__COOKIE='file:///run/secrets/emqx-cookie'

パスは通常のファイルまたはFIFO（名前付きパイプ）を参照できます。EMQXは起動時に一度だけノードクッキーを解決し、設定のリロード時にはファイルやFIFOを再読み込みしません。

FIFOを使用する場合、オーケストレーターは起動時にemqx ctlなどの他のemqxコマンドを呼び出す前に毎回FIFOにクッキーを書き込む必要があります。ノード起動後に呼び出されるコマンドは、FIFOを再度読み込まずに稼働中のノードからクッキーを取得します。

起動スクリプトはファイル内容の末尾の改行文字を削除します。参照パスが存在しない、ファイルが空、または解決されたクッキーにバックスラッシュ、シングルクォート、ダブルクォート、スペースが含まれている場合はノードは起動に失敗します。

EMQXは解決済みのクッキーを生成されたdata/configs/vm.*.argsファイルに書き込まず、直接Erlang VMに渡します。クラスター展開時はすべてのノードにファイルまたはFIFOをプロビジョニングし、各ノードが同じクッキーを読み込むようにしてください。詳細はSet Node Cookieを参照してください。

ロギングとマスキング

EMQXはシークレット型フィールドの値をログやHTTP APIレスポンスでマスキングします。file://値の場合、ファイルパスはログに記録されますが、内容は記録されません。解決されたシークレット値がログに出力されることはありません。

file://を使用しないほうがよい場合

node.cookieのように明示的にドキュメント化されたフィールドを除き、プレーンなstring型フィールドはfile://値をファイル参照としてではなく文字列として扱います。file://がサポートされているかどうかはスキーマの型やフィールドのドキュメントを確認してください。