EMQX 4.4 から EMQX 5.1 への非互換変更点
EMQX 5.0 シリーズでは、旧バージョンの EMQX との互換性に影響を与えるいくつかの変更が導入されています。これらの破壊的変更は EMQX 5.1 のリリースノートにも記載されています。
本ドキュメントは、EMQX 4.x から EMQX 5.1 へのアップグレードを計画している EMQX ユーザーが、発生しうる問題点を理解するためのものです。
TIP
- 5.1 へのアップグレードを行う前に、4.4 の最新バージョンへアップグレードすることを推奨します。
- 5.0 シリーズのより高いバージョンへアップグレードする場合は、本ドキュメントに従いまず 5.1 へのアップグレードを完了させ、その後に更なるバージョンアップを行ってください。
概要
EMQX 4.4 と比較して、EMQX 5.1 へのアップグレードでは、特に各種概念や仕組みにおいて大幅な変更が加えられており、これは EMQX 2.x から 3.x、3.x から 4.x へのアップグレード時の変更を上回る規模です。
まとめると、以下の点に注意が必要です。
- 設定ファイルと HTTP API に大きな変更があります。既存の設定やこれらのインターフェースに依存したコードは移行が必要です。
- コア MQTT プロトコル機能（Pub/Sub、Retainer、Shared Subscription を含む）はクライアントプログラムと完全互換ですが、管理インターフェースには若干の変更があります。
- 認証、認可、データ統合、プロトコルアクセスに関連するその他の機能は、それぞれの機能に応じて移行が必要です。
- 一部の概念が変更されています。例えば、プラグインの新バージョンが導入され、旧バージョンとは大きく異なります。旧バージョンのモジュールの概念は完全に廃止されました。
mcastによるクラスター探索や、データ統合のリソースタイプとしてのEMQX Bridgesなど、いくつかの機能が削除されています。
HTTP API
以前はダッシュボードのApplicationsで API アクセス認証情報を管理していましたが、現在は**API Key** を使って認証情報を作成します。認証情報は API Key と Secret Key からなり、それぞれ HTTP ベーシック認証のユーザー名とパスワードとして使用できます。Secret Key は作成時に一度だけ表示され、その後は取得できません。
- ポート 8081 は閉鎖され、すべての API リクエストはポート 18083 を使用します。
- HTTP API へのアクセスにはユーザー名/パスワードは使えず、API Key の使用が必須です。
- API の基本パスは
/api/v4から/api/v5に変更されました。ポート 18083 で/api/v5経由で呼び出してください。 - 時刻関連フィールドはタイムゾーン付きの RFC3339 形式を使用します。
データフォーマットの変更
レスポンスが成功した場合、ビジネスステータスコード code はデータと共に返されなくなり、エラー発生時には対応する 4xx/5xx の HTTP ステータスコードとエラーメッセージが返されます。
すべての可能なエラーコードは GET /error_codes で取得可能です。
レスポンスフォーマットの比較例
成功時のレスポンス
# 4.x
## HTTP StatusCode = 200
GET /api/v4/rules/my_rule
{ "code": 0, "data": { ... } }
# 5.1
## HTTP StatusCode = 200
GET /api/v5/rules/my_rule
{ ... }エラー時のレスポンス
# 4.x
## HTTP StatusCode = 200
GET /api/v4/rules/my_rule
{ "code": 404, "message": "Not Found" }
# 5.1
## HTTP StatusCode = 404
GET /api/v5/rules/my_rule
{ "code": "NOT_FOUND", "message": "Rule Id Not Found" }主な API の変更点
API は大幅に変更され、一部は互換性を持たせています。以下はよく使われる API の比較表です。
互換性についての注意
- 互換：旧 API パスとパラメータを使用可能、または旧 API を維持。
- 部分互換：API パスは変わらないが、一部フィールドが変更。
- 非互換：API パスおよびフィールドが変更。
API 互換性表
| 4.x | 5.x | 互換性 | 備考 |
|---|---|---|---|
| Publish/Subscribe | |||
POST /mqtt/publish | POST /publish | 互換 | |
POST /mqtt/publish_batch | POST /publish/bulk | 互換 | |
POST /mqtt/subscribe | POST /clients/{clientid}/subscribe | 互換 | |
POST /mqtt/subscribe_batch | POST /clients/{clientid}/subscribe/bulk | 互換 | |
POST /mqtt/unsubscribe | POST /clients/{clientid}/unsubscribe | 互換 | |
POST /mqtt/unsubscribe_batch | POST /clients/{clientid}/unsubscribe/bulk | 互換 | |
| Clients/Topics/Subscriptions | |||
GET /clients | GET /clients | 部分互換 | |
GET /routes{/topic} | GET /topics{/topic} | 非互換 | routes が topics に改名 |
GET /subscriptions | GET /subscriptions | 部分互換 | |
GET /subscriptions/{clientid} | GET /clients/{clientid}/subscriptions | 非互換 | |
| Node/Stats/Metrics | |||
GET /nodes | GET /nodes | 部分互換 | |
GET /brokers | - | 非互換 | GET /nodes に統合 |
GET /stats | GET /stats | 部分互換 | |
GET /metrics | GET /metrics | 部分互換 | |
| Users/Alarms | |||
GET /users | GET /users | 部分互換 | |
GET /alarms{/activated} | GET /alarms?activated={true,false} | 非互換 | |
GET /alarms{/deactivated} | GET /alarms?activated={true,false} | 非互換 |
設定ファイル
フォーマット：
- EMQX 4.x：
path.to.key = valueのフラット形式。 - EMQX 5.1：
path{to{ key = value }}のネスト形式をサポート。
- EMQX 4.x：
ソース：
- EMQX 4.x：
emqx.conf、listeners.conf、zones.confなど複数ファイル。- 動的更新は Mnesia に保存。動的更新を有効にするとファイルによる設定変更は不可。
- EMQX 5.1：
- 静的設定は
emqx.conf。 - 動的更新は
cluster.hocon。
- 静的設定は
- EMQX 4.x：
デフォルトリスナーの変更
| 名前 | 説明 | v4.4 ポート | 対応する v5.x ポート |
|---|---|---|---|
| MQTT-TCP | 内部（バックプレーン）MQTTリスナー | 11883 | -（削除） |
| Management-HTTP | REST API | 8081 | 18083（ダッシュボードポートと統合） |
プラグイン
旧公式プラグインは EMQX の組み込み機能に移行されました。4.x 用に開発されたカスタムプラグインは、EMQX 5.x で使用する前に適応が必要です。
公式プラグインと組み込み機能の比較表
| 4.x | 5.x |
|---|---|
| emqx_auth_http | 認証/認可 - HTTP データソース |
| emqx_auth_jwt | 認証/認可 - JWT |
| emqx_auth_mnesia | 認証/認可 - 組み込みデータベース |
| emqx_auth_mongo | 認証/認可 - MongoDB データソース |
| emqx_auth_mysql | 認証/認可 - MySQL データソース |
| emqx_auth_pgsql | 認証/認可 - PostgreSQL データソース |
| emqx_auth_redis | 認証/認可 - Redis データソース |
| emqx_sasl | 認証/認可 - MQTT 5 強化認証 |
| emqx_auth_ldap | - |
| emqx_rule_engine | データ統合 |
| emqx_bridge_mqtt | データブリッジ - MQTT ブリッジ |
| emqx_web_hook | データブリッジ - HTTP サーバ |
| emqx_coap | CoAP ゲートウェイ |
| emqx_dashboard | ダッシュボード |
| emqx_exhook | ExHook |
| emqx_exproto | ExProto ゲートウェイ |
| emqx_lwm2m | LwM2M ゲートウェイ |
| emqx_sn | MQTT-SN ゲートウェイ |
| emqx_stomp | STOMP ゲートウェイ |
| emqx_lua_hook | - |
| emqx_management | ダッシュボード |
| emqx_prometheus | Prometheus |
| emqx_psk_file | 認証 - PSK (psk_authentication.enable = true) |
| emqx_recon | 旧機能は CLI の emqx ctl observer で利用可能 |
| emqx_retainer | Retain |
| <!-- | emqx_telemetry |
ディストリビューションとクラスター
- クラスター作成のための
mcast探索戦略は非推奨となり、削除予定です。 - サービス探索の設定が変更され、
cluster.discoveryは cluster.discovery_strategy に変更されました。 - 新機能：cluster call。
- 内部 DB にオプションの最終的整合性が追加されました。
MQTT
- EMQX 5.0 では、MQTT クライアントは EMQX クラスターを単一のブラックボックスとして見られなくなりました（最終的整合性のため）。サブスクライブ確定後でも、他クライアントからのパブリッシュメッセージを受信するかどうかは保証されません。
- EMQX 5.0 では、キープアライブ（PING 受信）に完全な MQTT コントロールパケットが必要で、数バイトだけでは不十分です。
- EMQX 5.0 の TLS リスナーは
partial_chainとverify_peer_ext_key_usageをサポートしません。 - リトライ間隔は 5.0 で 30 秒ですが、4.4 では無効（0）です。4.4 のデフォルト設定ファイルには 30 秒のリトライ間隔があります。
MQTT over QUIC
MQTT over QUIC は 5.0 の新機能ですがデフォルトでは無効です。OS によっては libatomic の動的リンクが必要な場合があります。
認証 / 認可
完全な互換性レポートは Authentication / Authorization v4.4 to v5.1 Compatibility を参照してください。
すべての認証/認可プロバイダーは、旧フォーマットの代わりにプレースホルダーを使用します。EMQX 5.x では ${clientid} のようなプレースホルダーを使い、4.x の %c とは異なります。利用可能なプレースホルダーのセットも変更されています。
概念の変更
Auth は 認証、ACL は 認可 と呼ばれます。
データ移行
4.x の認証方式と対応データソースは維持されており、使用方法に若干の変更があります。ほとんどの認証者/認可者は、5.x へアップグレード後も 4.x のデータベースをそのまま利用可能で、既存データの移行は不要です。
実行順序の固定化
複数の認証者や認可チェックが同時に有効な場合、起動順ではなく設定ファイルやダッシュボードで指定した固定の順序で実行されます。実行順序は調整可能です。
変数展開構文
従来は %u などの構文でクライアント情報を SQL 文や Redis クエリ、HTTP リクエストに動的に埋め込んでいましたが、EMQX では新しい ${} 構文（例：${username}, ${clientid}）を使用し、ルール SQL と統一されています。
対応プレースホルダーの詳細は以下を参照してください。
使用例
# 4.x
# etc/emqx_auth_mysql.conf
auth.mysql.auth_query = select password from mqtt_user where username = '%u' limit 1
# 5.x
# emqx.conf
authentication = [
{
...
mechanism = "password_based"
backend = "mysql"
query = "SELECT password_hash, salt FROM mqtt_user where username = ${username} LIMIT 1"
}
]認証の非互換点
- スーパーユーザークエリは廃止されました。ハッシュ化された認証情報と
is_superuserフラグを返す単一のクエリに統合されています。 - HTTP 認証
- 4.x では HTTP ステータスコードのみを使用し、本文は破棄（例：
200は許可、403は拒否）。 - 5.x では HTTP 認証が再設計され、HTTP 本文を利用します。詳細は HTTP サービス認証 を参照してください。
- 4.x では HTTP ステータスコードのみを使用し、本文は破棄（例：
- SCRAM 認証
- 4.4 で唯一利用可能だった SHA1 ハッシュモードは廃止。SHA256/SHA512 ハッシュを使用します。
- 組み込みデータベース
- 設定ファイルに直接認証情報を記述できません。
- 認証情報テーブルはユーザー名またはクライアントIDのどちらか一方のタイプのみ保持します。
- Redis
HMGETとHGETコマンドのみサポート。query_timeoutは廃止。
- PostgreSQL
query_timeoutは廃止。encodingは廃止。
認可
ファイルベース
- ACL ルール
{allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"\]}は EMQX 5.1 では動作しません。詳細は issue #10735 を参照してください。
- ACL ルール
HTTP
- 4.x では HTTP ステータスコードのみ使用し本文は破棄（"ignore" ケースを除く）。例：
200は許可、403は拒否。 - 5.0 では HTTP 認可が再設計され、HTTP 本文を利用します。詳細は HTTP リクエストとレスポンス を参照してください。
- 4.x では HTTP ステータスコードのみ使用し本文は破棄（"ignore" ケースを除く）。例：
MySQL、PostgreSQL
- ストレージスキーマが変更されました。
- 4.4 では、クエリは
[Allow, IpAddr, Username, ClientId, Access, Topic]の順で任意の名前のカラムを取得する必要がありました。 - 5.1 では、クエリは
permission, action, topicの名前で任意の順序のカラムを取得しなければなりません。IpAddr, Username, ClientIdなどの「誰が」部分はクエリの一部として扱うことが推奨されます。
MongoDB
ストレージスキーマが変更されました。
4.4 では、結果ドキュメントは Redis や JWT と同様にアクションキーごとにトピックリストを含みます。
{ "publish": ["t1", "t2"], "subscribe": ["t3", "t4"], "pubsub": ["t5", "t6"] }5.1 では、ドキュメントは
permission, action, topicsフィールドを持つ個別のルールを含みます。topicsはトピックの配列である必要があります。
ルールエンジン
ルール SQL は EMQX 4.x の構文と完全互換ですが、ルール下のアクションは組み込みアクション（republish、console）とデータブリッジ（HTTP サーバ、MQTT ブリッジ）に分割されました。
データ統合
EMQX 5.1 ではデータ統合に関して概念的な改善が行われています。
- ルールと SQL テンプレートの完全互換性を確保。
- リソースやブリッジの設定項目名とフォーマットの多くが変更。
- 旧来の Rule -> Action -> Resources の流れが Rule -> Bridges に変更。
- Modules/Message Publish の機能は Bridges に統合。
- オフラインメッセージ保存、サブスクリプション取得、および EMQX Bridge 機能は削除。
- Tablestore、DolphinDB、Lindorm、SAP Event Mesh のデータブリッジは未対応。
- MQTT ブリッジプラグイン（
emqx_bridge_mqtt）は削除され、代わりにデータ統合の組み込み MQTT データブリッジを使用。
完全な互換性レポートは EMQX 5.1 と EMQX 4.4 のデータ統合非互換性 を参照してください。
HTTP サーバー
WebHook プラグイン（emqx_web_hook）はネイティブ機能に変換され、「HTTP サーバー」ブリッジとして呼ばれます。
オフラインメッセージ
EMQX Enterprise 4.x で提供されていた オフラインメッセージ は外部データベースベースです。EMQX は将来的に組み込みデータベースベースのネイティブオフラインメッセージを提供予定であり、5.x では外部データベースによるオフラインメッセージはサポートされません。
今後のネイティブオフラインメッセージ機能は性能向上と運用コスト削減を実現します。続報にご期待ください。
自動サブスクリプション（サーバーサイドサブスクリプション）
EMQX Enterprise 5.0.0 以降、外部データベースベースの 自動サブスクリプション は提供されていません。
データパーシステンス
MQTT メッセージのパーシステンス は EMQX 5.0 および 5.1 では未実装で、将来のバージョンでの対応が予定されています。
ゲートウェイ
EMQX 4.x では各種プロトコルを対応プラグインやモジュールで設定可能でしたが、EMQX 5.0 では新たにゲートウェイという概念を導入しました。
MQTT 以外のプロトコルクライアント（LwM2M、CoAP、STOMP、MQTT-SN）はダッシュボードの接続ページや GET /clients API には表示されず、管理 -> ゲートウェイ または GET /gateway/{name}/clients API で確認できます。
- 設定および管理方法は完全に非互換です。EMQX 5.0 は新しい設定フォーマットと管理方法を採用しています。
- 新しい設定フォーマット。
- ゲートウェイおよびゲートウェイクライアント管理用の新 HTTP API 追加。
- 各ゲートウェイは独立した認証方式を持ちます。
- JT/T 808、GB/T 32960、TCP、OCPP は EMQX 5.1 で未対応です。
- Stomp、MQTT-SN、ExProto は 4.x と完全互換で、機能も強化されています。
- CoAP と LwM2M のゲートウェイは 5.1.0 で実装されていますが、設計・実装が未完成のため本番環境での使用は推奨されません。
完全な互換性レポートは ゲートウェイの EMQX 4.4 と 5.1 の非互換性 を参照してください。
ログファイルフォーマット
EMQX 5.1 のログファイルは、EMQX 4.4 と同様のフラットログ形式か、よりインデクサーに適した構造化 JSON 形式のいずれかです。
また、多くのログフィールドは単語区切りにアンダースコアを使用し、検索しやすくなっています。例：
2022-06-29T16:58:53.235042+02:00 [info] foo: bar, msg: msg_for_human_to_read_but_also_easy_to_index
詳細は ログ を参照してください。
Prometheus
プラグイン emqx_statsd は削除されました。旧プラグイン emqx_prometheus は 5.x でネイティブ機能に統合され、Prometheus のスクレイピングエンドポイントはデフォルトで有効、認証不要です。
メトリクスを確認するには以下の curl コマンドを使用できます。
curl -f "http://127.0.0.1:18083/api/v5/prometheus/stats"プッシュゲートウェイを有効にしたい場合は、Prometheus 連携 を参照してください。
Prometheus メトリクスの変更点
| 4.4.x | 5.x | 説明 |
|---|---|---|
| emqx_client_auth_success_anonymous | emqx_client_auth_anonymous | 改名 |
| emqx_client_check_acl | emqx_client_authorize counter | 改名 |
| - | emqx_mria_last_intercepted_trans | 新規 |
| - | emqx_mria_replicants | 新規 |
| - | emqx_mria_server_mql | 新規 |
| - | emqx_mria_weight | 新規 |
| emqx_routes_count | emqx_topics_count | 改名 |
| emqx_routes_max | emqx_topics_max | 改名 |
| emqx_session_takeovered | emqx_session_takenover | 改名 |
| erlang_vm_ets_tables | - | 削除 |
| - | erlang_vm_memory_dets_tables | 新規 |
| - | erlang_vm_memory_ets_tables | 新規 |
| - | erlang_vm_msacc_alloc_seconds_total | 新規 |
| - | erlang_vm_msacc_aux_seconds_total | 新規 |
| - | erlang_vm_msacc_bif_seconds_total | 新規 |
| - | erlang_vm_msacc_busy_wait_seconds_total | 新規 |
| - | erlang_vm_msacc_check_io_seconds_total | 新規 |
| - | erlang_vm_msacc_emulator_seconds_total | 新規 |
| - | erlang_vm_msacc_ets_seconds_total | 新規 |
| - | erlang_vm_msacc_gc_full_seconds_total | 新規 |
| - | erlang_vm_msacc_gc_seconds_total | 新規 |
| - | erlang_vm_msacc_nif_seconds_total | 新規 |
| - | erlang_vm_msacc_other_seconds_total | 新規 |
| - | erlang_vm_msacc_port_seconds_total | 新規 |
| - | erlang_vm_msacc_send_seconds_total | 新規 |
| - | erlang_vm_msacc_sleep_seconds_total | 新規 |
| - | erlang_vm_msacc_timers_seconds_total | 新規 |
| - | erlang_vm_statistics_dirty_cpu_run_queue_length | 新規 |
| - | erlang_vm_statistics_dirty_io_run_queue_length | 新規 |
| erlang_vm_statistics_run_queues_length_total | erlang_vm_statistics_run_queues_length | 改名 |
| - | erlang_vm_wordsize_bytes | 新規 |