Feature Gates
Starting in EMQX 6.3.0, feature gates are deployment-time controls that enable or disable optional EMQX features. They are resolved only when EMQX starts and cannot be changed at runtime.
Feature gates are configured by the EMQX_FEATURES environment variable and are designed for deployment policy. They are not stored in HOCON configuration files, are not persisted to cluster.hocon, and cannot be changed from the Dashboard, REST API, or CLI. To change the enabled feature set, update EMQX_FEATURES in the deployment environment and restart EMQX.
Configure Feature Gates
Set EMQX_FEATURES to one of the following values:
| Value | Description |
|---|---|
| Unset or empty | Uses the FULL preset. This preserves the default EMQX behavior. |
FULL | Enables all optional features. |
ESSENTIAL | Starts EMQX with only the core applications. All optional features are disabled. |
| Custom feature list | Enables the listed features and their dependencies. Use lowercase feature names separated by commas, spaces, or both. |
Examples:
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 and "dashboard auth" have the same effect. If you use spaces to separate feature names, wrap the whole value in quotes to prevent the shell from splitting it.
Do not mix a preset with feature names. For example, EMQX_FEATURES=ESSENTIAL,metrics is invalid.
WARNING
Invalid values prevent EMQX from starting. If a feature name is unknown, EMQX logs invalid_feature_specification with reason set to unknown_feature and exits with a non-zero status.
Available Features
The following optional features can be used in a custom EMQX_FEATURES list:
| Feature | Description |
|---|---|
dashboard | Dashboard UI, REST API, Dashboard role-based access control, and Dashboard single sign-on. |
auth | Authentication and authorization chains and backends. |
data_integration | Rule engine, connectors, actions, sources, and data bridges. |
message_transformation | Message transformation. |
schema_validation | Schema validation. |
schema_registry | Schema registry and schema definitions used by related features. |
gateways | Non-MQTT protocol gateways. |
cluster_link | Cluster linking. |
multi_tenancy | Multi-tenancy and namespace management. |
ai | AI features, including AI completion and Agent-to-Agent registry. |
metrics | Prometheus metrics export. |
mqtt_extensions | MQTT extensions such as delayed publish, topic rewrite, topic metrics, auto subscription, slow subscribers, MQTT Streams, and Message Queue. |
file_transfer | File Transfer over MQTT. |
gcp_device | Migration compatibility shim for Google IoT Core. |
exhook | External gRPC hooks. |
opentelemetry | OpenTelemetry exporter. |
Feature Dependencies
Some features require other features to work. When you enable a feature, EMQX automatically enables its dependencies.
| Feature | Automatically Enabled Dependencies |
|---|---|
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 |
For example, setting EMQX_FEATURES=metrics enables metrics, dashboard, and auth.
Core Applications
The ESSENTIAL preset disables optional features, but EMQX still starts the core applications required for broker operation and management. Core applications include the MQTT broker, configuration system, CLI, license validation, plugin framework, durable storage, audit log, node rebalance, retainer, TLS PSK, outbound telemetry, and shared resource or bridge framework applications.
Existing feature-specific configuration sections can remain in configuration files when the corresponding feature gate is disabled. EMQX does not start the applications behind disabled features, so those configuration sections are not used until the feature is enabled again.
Inspect Enabled Features
In the Dashboard, click Monitoring -> Cluster Overview -> Nodes and check the Feature Preset column. The column shows whether each node started with the full, essential, or custom preset. custom means that EMQX_FEATURES contains an explicit feature list. Stopped nodes and nodes running versions earlier than 6.3 do not report a preset.
The Dashboard shows only the preset. To inspect the exact enabled and disabled feature lists, use the startup log or REST API.
EMQX logs the resolved feature state during startup:
feature_gates_resolvedThe log entry includes the resolved preset, enabled feature list, and disabled feature list.
When the dashboard feature is enabled, you can also query the resolved state through the REST API:
curl -u <API_KEY>:<SECRET_KEY> http://localhost:18083/api/v5/featuresExample response:
{
"preset": "custom",
"enabled": ["auth", "dashboard", "metrics"],
"disabled": ["ai", "cluster_link", "data_integration"]
}The exact lists depend on the EMQX edition, version, and configured feature set.
TIP
GET /api/v5/features is served by the Dashboard and management API applications. If the dashboard feature is disabled, inspect the resolved feature set from the startup log instead.
Cluster Deployment Considerations
For operational consistency, configure the same EMQX_FEATURES value on all nodes in a cluster. A mixed-feature cluster can expose different REST APIs, background applications, and cross-node behavior on different nodes.
When you use Docker Compose, Kubernetes, or another orchestration system, set EMQX_FEATURES in the shared deployment manifest so added and restarted nodes receive the same value.