EMQX Cloud V4 to V6 Upgrade Guide

As an EMQX Dedicated deployment user, you can upgrade EMQX from V4 to V6. To check the current EMQX version, open the deployment details page and click Settings to view the deployment information.

Building on the stability and efficiency of V4, EMQX V6 delivers comprehensive enhancements to authentication and authorization, monitoring metrics, retained messages, and data integration. It also introduces or enhances capabilities such as Namespaces, Log Trace, Event History, BigQuery data integration, and Snowflake Streaming data integration. For more information, see What's New.

Availability

EMQX V6 is available only for Dedicated and Dedicated Flex Broker deployments. Serverless deployments do not support EMQX version selection.

Before You Upgrade

1. Contact us at least three days in advance to schedule the upgrade. We will discuss the upgrade considerations and maintenance window with you.
2. Read and understand this guide in full, especially the incompatible changes. If you have any questions, contact us through a support ticket.
3. Our SRE team will perform a comprehensive assessment of your deployment. If special configurations or potential impacts are identified, they will be documented in the special-case notes so that you can decide whether to proceed.
4. If your business systems call the V4 HTTP API or use external authentication, external authorization, or complex data integrations, complete compatibility testing against a V6 environment before the upgrade.

Data Migration and Retained Configuration

The following configuration and data will be retained during the upgrade:

• MQTT endpoints and ports
• All authentication and authorization entries
• Data integration configuration, including resources, rules, and actions, subject to the compatibility notes below
• TLS certificate information
• Retained messages
• Network management configuration, including NAT Gateway, Internal Endpoint, PrivateLink, and VPC Peering

Incompatible Changes

• Feature removal: Device Shadow Service is no longer supported in V6.
• Special configuration changes: Special configurations previously requested through support tickets, such as additional ports or ACL allowlists, may be affected. The SRE team will explain the specific impact before the upgrade.
• HTTP API changes:

  • The API prefix changes from /api to /api/v5.

  • API Keys and Secret Keys from V4 cannot be migrated. After the upgrade, create new credentials and update the API endpoint and authentication information in your business systems.

  • Several API paths have changed, including those for message publishing, client queries, and node management.

  • In addition to path changes, some APIs have incompatible request bodies, response structures, HTTP status codes, error codes, field names, field types, and time formats.

    These changes may affect the API parsing logic in existing business systems. Complete compatibility testing before the upgrade.

  • For details, compare the following documents:

    • V4 API Documentation
    • Latest API Documentation
• External authentication changes: Configuration fields and query-response requirements have changed. Update your configuration according to the External Authentication and Authorization documentation.
• Data integration compatibility:
  • Resources that are not bound to any rule will not be retained. Before the upgrade, check whether these resources are still required.
  • Fallback actions configured under rules will not be retained. The V6 data integration architecture no longer supports fallback actions.
  • Empty actions that are not associated with any resource or action will be deleted automatically during the upgrade.
  • Some Rule SQL statements that use WHERE are not compatible with the new version and may need to be updated manually. For example, to determine whether a field exists, V4 uses <> "undefined", while the new version uses is_null.

Upgrade Impact

1. The upgrade is expected to take 15–25 minutes, including approximately 5–15 minutes of service downtime.
2. A two-hour maintenance window will be created for the upgrade. Service unavailability caused by the upgrade or compatibility issues during this window is excluded from SLA availability calculations.
3. All client connections will be disconnected one or two times during the upgrade. Make sure automatic reconnection is enabled on your clients.
4. Sessions created with clean session = false cannot be retained. Clients will create new sessions after reconnecting.

Post-Upgrade Process

Post-Upgrade Validation

1. After the upgrade, the EMQX Cloud SRE team will check the deployment logs and metrics.
2. Perform comprehensive business validation, especially the following checks:
   • HTTP API calls use the new paths and newly created API Key and Secret Key
   • HTTP API response structures remain compatible with your business-system parsing logic
   • Built-in and external authentication and authorization operate correctly
   • Data integration connectors, rules, Sources, and Sinks operate correctly
   • Client connections, subscriptions, and message publishing and delivery operate correctly
   • TLS connections and custom certificates operate correctly
3. If you identify any issue, contact us immediately for assistance.

Rollback

• A 24-hour rollback window is available before you confirm the upgrade. During this window, the deployment can be rolled back from V6 to V4.
• Rollback is expected to take 15–25 minutes, including approximately 3–5 minutes of service interruption.
• All client connections will be disconnected one or two times during rollback.
• Sessions created with clean session = false cannot be retained.

Detailed V6 Core Feature Changes

This section describes the feature enhancements, architectural improvements, and corresponding console changes introduced when upgrading from V4 to V6.

Enhanced Certificate Management

V6 deployments include a one-way TLS certificate by default—a wildcard certificate for the deployment endpoint domain. You can connect over TLS directly through ports 8883 and 8084. A custom TLS certificate replaces the default certificate on these ports. After the custom certificate is deleted, the certificate for the default deployment endpoint is restored.

HTTP API Changes

• The API endpoint changes from https://xxx/api to https://xxx/api/v5.
• API Keys and Secret Keys from V4 cannot be migrated and must be recreated after the upgrade.
• In addition to API path changes, some APIs have incompatible request bodies, response structures, HTTP status codes, error codes, field names, field types, and time formats.

If your business systems depend on existing V4 API response structures, complete compatibility testing before the upgrade. For details, see the Authentication section in the latest API documentation.

Access Control Improvements

• The Authentication & ACL feature is renamed Access Control.
• Built-in authentication and authorization data, together with external authentication and authorization configurations, will be migrated.
• External authentication and authorization are separated into External Authentication and External Authorization. Their entry points are moved to External Authentication under Client Authentication and External Authorization under Client Authorization, respectively.
• The priority of authentication mechanisms in the authentication chain can be adjusted manually.
• Default client authorization rules can be configured at three levels: client ID, username, and all users. Authorization information for a client or username is displayed under the corresponding tab.

Monitoring Redesign

• Real-time metrics from the former Monitoring page are moved to the Metrics page, where you can view real-time metrics or time-series data.
• Client and subscription management from the former Monitoring page are moved to separate Clients and Subscriptions pages under Monitoring.
• A new retained-message management page allows retained messages to be queried and deleted.

Data Integration Architecture Upgrade

Rule, Source, and Sink Architecture

Compatibility Notes

After upgrading to V6, note the following rule compatibility changes:

• Empty actions are deleted automatically during the upgrade.
• Some Rule SQL statements that use WHERE are not compatible with V6 and may need to be updated manually. For example, to determine whether a field exists, V4 uses <> "undefined", while V6 uses is_null.

• Rules and actions are logically separated for more flexible configuration.
• Sinks send data to external services.
• Sources ingest data from external services into EMQX, similar to the MQTT Subscribe plugin in V4.
• Fallback actions are no longer supported.

Expanded Data Integration Support

• New data-forwarding integrations include Elasticsearch, Azure Event Hubs, Amazon Kinesis, and SysKeeper Forwarder.
• New data-persistence integrations include Apache IoTDB, GreptimeDB, and Amazon S3.
• Data can be ingested from message queues and MQTT services through integrations such as Kafka Consumer and MQTT Source.
• V6 also introduces BigQuery and Snowflake Streaming data integrations, as described in V6-Specific Capabilities below.

Smart Data Hub Upgrade

Smart Data Hub is a unified solution for intelligent data processing. It can manage schemas, validate data, and transform data in real time. It simplifies MQTT data-stream processing and improves data standardization and business integration.

If Schema Registry is configured in your V4 deployment, Smart Data Hub will be enabled automatically after the upgrade.

V6-Specific Capabilities

Note

The following capabilities are available only for Dedicated and Dedicated Flex deployments that support EMQX V6. Actual availability depends on the V6 minor version, region, and options displayed in the console.

V6-Specific Capability	Practical Value
Namespaces	Provide resource and permission isolation for multi-tenant scenarios. Rules, connectors, actions, and other resources can be organized by tenant, team, or business unit, reducing cross-tenant impact and simplifying operations in a shared cluster.
Log Trace	Collect debug logs for a specific client, topic, client IP address, or rule ID without enabling verbose logging for the entire deployment. This is useful for targeted troubleshooting.
Event History	Retain recent connection, authentication, and subscription events to diagnose connection failures, unexpected disconnections, authentication failures, and subscriptions that do not take effect.
BigQuery Data Integration	Write MQTT data to BigQuery through the rule engine and a BigQuery Sink for SQL analytics and reporting.
Snowflake Streaming Data Integration	Write data to Snowflake tables with low latency through the rule engine and a Snowflake Streaming Sink.

Namespaces

Namespaces enhance multi-tenant management and resource isolation. Administrators can divide resource scopes by tenant, department, or business unit and independently manage rules, connectors, and actions within each namespace. When multiple teams or customers share one deployment, namespaces reduce accidental resource changes and cross-tenant impact.

Log Trace

Log Trace allows users to collect debug-level logs from the console for a specific MQTT client, topic, client IP address, or rule ID. Compared with enabling verbose logging for the entire deployment, it provides a more precise scope with less impact on normal workloads and is suitable for reproducing and diagnosing issues involving a specific client, topic, or rule-processing path.

Event History

Event History records recent client connection, authentication, and subscription events. It can be used to investigate:

• Client connection failures or unexpected disconnections
• Client authentication failures
• Subscriptions that fail to be created or do not take effect
• Connection and subscription timelines

BigQuery Data Integration

The rule engine filters and processes MQTT messages before a BigQuery Sink writes them to Google BigQuery. This integration is suitable for SQL analytics, data warehousing, and reporting on large volumes of IoT data.

Snowflake Streaming Data Integration

The Snowflake Streaming Sink writes MQTT data to Snowflake tables with low latency. It is suitable for near-real-time data ingestion, analytics, and business insights.

MQTT Source Enhancements

The V6 MQTT Source supports shared subscription topics to reduce duplicate messages. It also supports MQTT 5.0 subscription options such as No Local and Retain As Published, providing greater flexibility when bridging data from a remote MQTT service.

Upgrade Confirmation

After you fully understand the upgrade scope and potential risks described above, contact us to confirm the upgrade schedule. We will provide technical support throughout the process to help ensure a successful upgrade.