Feature Gates
EMQX 6.3.0以降、Feature Gatesはデプロイ時にオプションのEMQX機能を有効化または無効化するための制御機構です。これらはEMQX起動時にのみ解決され、ランタイム中に変更することはできません。
Feature GatesはEMQX_FEATURES環境変数で設定され、デプロイポリシー向けに設計されています。HOCON設定ファイルには保存されず、cluster.hoconにも永続化されません。また、ダッシュボード、REST API、CLIから変更することもできません。有効な機能セットを変更するには、デプロイ環境のEMQX_FEATURESを更新し、EMQXを再起動してください。
Feature Gatesの設定
EMQX_FEATURESに以下のいずれかの値を設定します。
| 値 | 説明 |
|---|---|
| 未設定または空 | FULLプリセットが使用されます。これはデフォルトのEMQX動作を維持します。 |
FULL | すべてのオプション機能を有効化します。 |
ESSENTIAL | コアアプリケーションのみでEMQXを起動します。すべてのオプション機能は無効化されます。 |
| カスタム機能リスト | 指定した機能とその依存関係を有効化します。小文字の機能名をカンマ、スペース、またはその両方で区切って指定してください。 |
例：
export EMQX_FEATURES=FULL
export EMQX_FEATURES=ESSENTIAL
export EMQX_FEATURES=dashboard,auth
export EMQX_FEATURES="dashboard auth"
export EMQX_FEATURES=dashboard,auth,data_integration,metricsdashboard,authと"dashboard auth"は同じ効果です。スペースで区切る場合は、シェルが分割しないように全体を引用符で囲んでください。
プリセットと機能名を混在させることはできません。例えば、EMQX_FEATURES=ESSENTIAL,metricsは無効です。
WARNING
無効な値を設定するとEMQXは起動しません。未知の機能名がある場合、EMQXはinvalid_feature_specificationをログに記録し、reasonにunknown_featureを設定して非ゼロステータスで終了します。
利用可能な機能
カスタムEMQX_FEATURESリストで使用可能なオプション機能は以下の通りです。
| 機能 | 説明 |
|---|---|
dashboard | ダッシュボードUI、REST API、ダッシュボードのロールベースアクセス制御、ダッシュボードのシングルサインオン。 |
auth | 認証および認可チェーンとバックエンド。 |
data_integration | ルールエンジン、コネクター、アクション、ソース、データブリッジ。 |
message_transformation | メッセージ変換。 |
schema_validation | スキーマ検証。 |
schema_registry | スキーマレジストリおよび関連機能で使用されるスキーマ定義。 |
gateways | 非MQTTプロトコルのゲートウェイ。 |
cluster_link | クラスターリンク。 |
multi_tenancy | マルチテナンシーおよびネームスペース管理。 |
ai | AI機能（AI補完やAgent-to-Agentレジストリを含む）。 |
metrics | Prometheusメトリクスのエクスポート。 |
mqtt_extensions | 遅延パブリッシュ、トピック書き換え、トピックメトリクス、自動サブスクリプション、スロースブスクライバー、MQTTストリーム、メッセージキューなどのMQTT拡張。 |
file_transfer | MQTTによるファイル転送。 |
gcp_device | Google IoT Coreの移行互換シム。 |
exhook | 外部gRPCフック。 |
opentelemetry | OpenTelemetryエクスポーター。 |
機能の依存関係
一部の機能は他の機能を必要とします。機能を有効化すると、EMQXは自動的に依存機能も有効化します。
| 機能 | 自動的に有効化される依存機能 |
|---|---|
data_integration | schema_registry |
message_transformation | schema_registry |
schema_validation | schema_registry |
ai | schema_registry |
gateways | auth |
gcp_device | auth |
metrics | dashboard, auth |
opentelemetry | dashboard |
例えば、EMQX_FEATURES=metricsを設定すると、metrics、dashboard、authが有効化されます。
コアアプリケーション
ESSENTIALプリセットはオプション機能を無効化しますが、EMQXはブローカーの動作と管理に必要なコアアプリケーションを起動します。コアアプリケーションにはMQTTブローカー、設定システム、CLI、ライセンス検証、プラグインフレームワーク、耐久ストレージ、監査ログ、ノードリバランス、リテイナー、TLS PSK、アウトバウンドテレメトリー、共有リソースやブリッジフレームワークのアプリケーションが含まれます。
対応するFeature Gateが無効化されている場合でも、既存の機能固有の設定セクションは設定ファイルに残せます。EMQXは無効化された機能に関連するアプリケーションを起動しないため、それらの設定セクションは機能が再度有効化されるまで使用されません。
有効化された機能の確認
ダッシュボードで Monitoring -> Cluster Overview -> Nodes をクリックし、Feature Preset列を確認してください。この列には各ノードがfull、essential、またはcustomプリセットで起動しているかが表示されます。customはEMQX_FEATURESに明示的な機能リストが含まれていることを意味します。停止中のノードや6.3未満のバージョンのノードはプリセットを報告しません。
ダッシュボードはプリセットのみを表示します。正確な有効・無効の機能リストを確認するには、起動ログまたはREST APIを使用してください。
EMQXは起動時に解決された機能状態をログに記録します。
feature_gates_resolvedログエントリには解決されたpreset、enabled機能リスト、disabled機能リストが含まれます。
dashboard機能が有効な場合は、REST API経由で解決状態を問い合わせることも可能です。
curl -u <API_KEY>:<SECRET_KEY> http://localhost:18083/api/v5/featuresレスポンス例：
{
"preset": "custom",
"enabled": ["auth", "dashboard", "metrics"],
"disabled": ["ai", "cluster_link", "data_integration"]
}正確なリストはEMQXのエディション、バージョン、設定された機能セットによって異なります。
TIP
GET /api/v5/featuresはダッシュボードおよび管理APIアプリケーションで提供されます。dashboard機能が無効な場合は、起動ログから解決された機能セットを確認してください。
クラスター展開時の注意点
運用の一貫性を保つため、クラスター内のすべてのノードで同じEMQX_FEATURES値を設定してください。機能が混在したクラスターでは、ノードごとに異なるREST API、バックグラウンドアプリケーション、ノード間の動作が現れる可能性があります。
Docker Compose、Kubernetes、その他のオーケストレーションシステムを使用する場合は、共有のデプロイメントマニフェストにEMQX_FEATURESを設定し、追加および再起動されたノードが同じ値を受け取るようにしてください。