EMQX 4.4 と EMQX 5.1 間の互換性のない変更点

EMQX 5.0 シリーズでは、旧バージョンの EMQX との互換性に影響を与える可能性のある複数の変更が導入されています。これらの破壊的変更は EMQX 5.1 のリリースノートにも記載されています。

本ドキュメントは、EMQX 4.x から EMQX 5.1 へのアップグレードを計画しているユーザー向けに、発生しうる問題点を理解していただくためのものです。

TIP

1. 5.1 へのアップグレードを行う前に、4.4 の最新バージョンへのアップグレードを推奨します。
2. 5.0 シリーズのより高いバージョンへアップグレードする場合は、本ドキュメントに従いまず 5.1 へアップグレードし、その後に更に高いバージョンへアップグレードしてください。

概要

EMQX 4.4 と比較して、EMQX 5.1 へのアップグレードでは、特に様々な概念や仕組みにおいて大幅な変更が加えられており、EMQX 2.x から 3.x、3.x から 4.x へのアップグレード時の変更を上回る規模となっています。

まとめると、以下の点に注意が必要です：

1. 設定ファイルおよび HTTP API に大幅な変更があります。既存の設定やこれらのインターフェースに依存したコードは移行が必要です。
2. MQTT プロトコルのコア機能（Pub/Sub、Retainer、Shared Subscription など）はクライアントプログラムとの互換性を維持していますが、管理インターフェースに若干の変更があります。
3. 認証、認可、データ統合、プロトコルアクセスに関するその他の機能は、それぞれの機能に応じた移行が必要です。
4. 一部の概念が変更されています。例えば、プラグインの新バージョンが導入され、旧バージョンとは大きく異なります。旧バージョンのモジュールの概念は完全に廃止されました。
5. クラスター探索のための mcast や、データ統合のリソースタイプとしての EMQX Bridges など、一部機能の削除に注意してください。

HTTP API

以前はダッシュボードの Applications で API アクセス認証情報を管理していましたが、現在は API Key を使って認証情報を作成します。認証情報は API Key と Secret Key からなり、それぞれ HTTP Basic 認証のユーザー名とパスワードとして使用できます。Secret Key は作成時に一度だけ表示され、その後は取得できません。

• ポート 8081 は閉じられ、すべての API リクエストはポート 18083 を使用します。
• HTTP API へのアクセスにユーザー名/パスワードは使えず、API Key の使用が必須です。
• API の基本パスは /api/v4 から /api/v5 に変更されました。ポート 18083 とパス /api/v5 を使って API を呼び出してください。
• 時刻関連のフィールドは 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.conf、listeners.conf、zones.conf など複数ファイル。
    • 動的更新は Mnesia に保存。動的更新を有効にするとファイルによる設定変更は不可。
  • EMQX 5.1：
    • 静的設定は emqx.conf。
    • 動的更新は cluster.hocon。

デフォルトリスナーの変更

名称	説明	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 は Authentication（認証）、ACL は Authorization（認可） と呼ばれます。

データ移行

4.x からの認証方式や対応データソースはほぼ維持されており、使い方に若干の変更があります。多くの Authenticator/Authorizer は 4.x のデータベースをそのまま 5.x で利用可能で、既存データの移行は不要です。

実行順序の固定化

複数の認証器や認可チェッカーが同時に有効な場合、起動順ではなく設定ファイルやダッシュボードで指定した固定の順序で実行されます。実行順序は設定可能です。

変数展開構文の変更

従来は Auth プラグインで %u のような構文を使い、SQL 文や Redis クエリ、HTTP リクエストにクライアント情報を動的に埋め込んでいました。
現在は ${username}、${clientid} のような ${} 構文を使い、ルール SQL と統一されています。

対応プレースホルダーの詳細は以下を参照してください：

• Authentication Placeholders
• Authorization Placeholders

使用例

# 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 認証
  • EMQX 4.x では HTTP ステータスコードのみを使用し、本文は破棄されていました（例：200 は許可、403 は拒否）。
  • EMQX 5.x では HTTP 認証が再設計され、HTTP 本文を活用します。詳細は 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 を参照してください。

• HTTP

  • EMQX 4.x では HTTP ステータスコードのみを使用し、本文は破棄されていました（"ignore" ケースを除く）。例：200 は許可、403 は拒否。
  • EMQX 5.0 では HTTP 認可が再設計され、HTTP 本文を活用します。詳細は HTTP リクエストとレスポンス を参照してください。

• MySQL、PostgreSQL

  • ストレージスキーマが変更されました。
  • EMQX 4.4 では、クエリは [Allow, IpAddr, Username, ClientId, Access, Topic] の順で列を取得する必要がありました（名前は任意）。
  • EMQX 5.1 では、クエリは permission, action, topic の列を任意の順序で、かつ正確な名前で取得する必要があります。IpAddr, Username, ClientId などの「誰が」部分はクエリに含めることが推奨されます。

• MongoDB

  • ストレージスキーマが変更されました。

  • EMQX 4.4 では、結果のドキュメントは Redis や JWT と同様にアクションキーごとにトピックリストを含んでいました：

    {
      "publish": ["t1", "t2"],
      "subscribe": ["t3", "t4"],
      "pubsub": ["t5", "t6"]
    }

  • EMQX 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 ブリッジ機能は削除。
• Tablestore、DolphinDB、Lindorm、SAP Event Mesh のデータブリッジは未対応。
• MQTT ブリッジプラグイン（emqx_bridge_mqtt）は削除。代わりにデータ統合の組み込み MQTT データブリッジを使用。

完全な互換性レポートは Data Integration Incompatibility Between EMQX 5.1 with 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）のクライアントは、ダッシュボードの Connections ページや GET /clients API には表示されず、Management -> Gateways または 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 で実装されていますが、設計・実装が未完成のため本番環境での使用は推奨されません。

完全な互換性レポートは Gateway Incompatibility between e4.4 and e5.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

詳細は Logs を参照してください。

Prometheus

プラグイン emqx_statsd は削除されました。旧プラグイン emqx_prometheus は 5.x でネイティブ機能に統合され、Prometheus のスクレイピングエンドポイントはデフォルトで有効化されており、認証なしでメトリクスを取得できます。

curl コマンドでメトリクスを確認できます：

curl -f "http://127.0.0.1:18083/api/v5/prometheus/stats"

プッシュゲートウェイを有効にする場合は Integrate with 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	新規