EMQX Enterprise ローリングアップグレード
クラスター展開において、EMQX ノードはダウンタイムなしで1台ずつアップグレードできます。このプロセスをローリングアップグレードと呼びます。クライアントセッションのスムーズな移行を実現するために、EMQX Enterprise のクラスターリバランシング機能を使用して、アップグレード前にノードからクライアントを退避させることが可能です。クラスターリバランシングの詳細についてはこちらをご覧ください。
EMQX 5.9以降へのアップグレードに関する重要なライセンス通知
バージョン5.9.0以降、EMQX Enterpriseは従来のオープンソース版とエンタープライズ版を分離したモデルから、Business Source License (BSL) 1.1の下でリリースされています。
TIP
ライセンス変更の詳細については、EMQX ライセンスFAQをご参照ください。
EMQXのアップグレード手順（バイナリの置き換えなど）は従来のバージョンアップと似ていますが、5.9.0では特にクラスター展開に関して重要なライセンス変更があります。5.9より前のオープンソース版からのアップグレードや、単一ノード展開からクラスター展開へのアップグレードを行う場合は、以下の重要な変更点にご注意ください。
- 新しいライセンスモデル: EMQX 5.9.0以降はデフォルトでEMQX Community Licenseが適用されます。このデフォルトライセンスはすべての機能を有効にしますが、単一ノードでの展開に制限されます。
- クラスター機能の制限: 従来のオープンソース版ではクラスター機能がサポートされていましたが、新モデルではEMQX 5.9.0以降のデフォルトではクラスター機能が許可されていません。クラスター展開を維持したい場合は、商用ライセンスの取得が必要です。
- ライセンス設定の必須化: クラスター内でEMQX 5.9.0以降のノードを起動する前に、各ノードで商用ライセンスを設定しておく必要があります。ライセンスが設定されていないか誤って設定されている場合、ノードはクラスター内で正常に動作しません。
TIP
emqx.confにライセンス設定を追加した場合、ダッシュボード、HTTP API、CLIからのランタイム設定変更はノード再起動後に失われます。これは、起動時の設定読み込みにおいてemqx.confと環境変数が最優先されるためです。
5.0以降のサポートされるローリングアップグレードパス
以下は5.0以降でサポートされるローリングアップグレードパスのマトリックスです。読みやすさのため表を分割しています。後期v5バージョン（5.8～5.10）は両方に記載されています。
- バージョン番号の末尾に
?（例：6.3?）がついているものは将来リリース予定です。 - ✅: サポート済み、またはサポート予定。
- ⚠️: サポートされているが制限あり。
- ❌: サポートされていません。
詳細はリリースノートをご確認ください。
v5内（5.0 – 5.10）
| From\To | 5.1 | 5.2 | 5.3 | 5.4 | 5.5 | 5.6 | 5.7 | 5.8 | 5.9 | 5.10 |
|---|---|---|---|---|---|---|---|---|---|---|
| 5.0 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️[1] | ❌[2] |
| 5.1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌[2] |
| 5.2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌[2] | |
| 5.3 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌[2] | ||
| 5.4 | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ | |||
| 5.5 | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ | ||||
| 5.6 | ✅ | ✅ | ✅ | ✅ | ✅ | |||||
| 5.7 | ✅ | ✅ | ✅ | ✅ | ||||||
| 5.8 | ✅ | ⚠️[3] | ⚠️[3] | |||||||
| 5.9 | ✅ | ✅ | ||||||||
| 5.10 | ✅ |
- [1] アップグレード前に古いリミッター設定を設定ファイル（
etc/emqx.confおよびdata/configs/cluster-override.conf）から削除してください。 - [2] 5.4以前のルーティングテーブルは削除されます。まず5.9にアップグレードし、その後5.10以降にアップグレードする前にクラスター全体を再起動（ローリングではなく）してください。
- [3] OpenTelemetryヘッダー設定のサポートは5.8.7で導入されました。5.8.7以降の5.8系バージョンは5.9.1または5.10.1へのローリングアップグレードが必要です。もしくはアップグレード時にOpenTelemetry連携のヘッダー設定を削除してください。
v6へのアップグレード（5.8 – 6.3?）
| From\To | 5.8 | 5.9 | 5.10 | 6.0 | 6.1 | 6.2 | 6.3? |
|---|---|---|---|---|---|---|---|
| 5.8 | ✅ | ⚠️[3] | ⚠️[3] | ⚠️[4] | ⚠️[4] | ⚠️[4] | ⚠️[4] |
| 5.9 | ✅ | ✅ | ⚠️[4] | ⚠️[4] | ⚠️[4] | ⚠️[4] | |
| 5.10 | ✅ | ⚠️[4] | ⚠️[4] | ⚠️[4] | ⚠️[4] | ||
| 6.0 | ✅ | ✅ | ✅ | ✅ | |||
| 6.1 | ✅ | ✅ | ✅ | ||||
| 6.2 | ✅ | ✅ | |||||
| 6.3? | ✅ |
- [4] v5からv6へのアップグレード後、永続化されたセッション状態は失われます。クライアントが再接続すると、新しいノード上のセッションはクリーンな状態として表示されます。
EMQX 5.10以降のローリングアップグレードに関する注意点
EMQX 5.10.0以降は、v2 ルーティングストレージスキーマのみがサポートされています。5.4.0以前のデフォルトであった旧式の v1 スキーマは互換性がありません。そのため、特に以前のバージョンから段階的にアップグレードされたクラスターで v1 スキーマを使用している場合、5.10.0以降へのローリングアップグレードはできません。
重要
クラスターがまだ v1 ルーティングスキーマを使用している場合は、アップグレード完了のためにクラスター全体の再起動が必要です。
現在のルーティングスキーマの確認
以下のコマンドでEMQXクラスターが使用しているルーティングスキーマを確認してください。
$ emqx eval 'emqx_router:get_schema_vsn()'出力が v2 であれば、通常のローリングアップグレードが可能です。
出力が v1 の場合は、以下の手順でクラスター全体の再起動を伴うアップグレードを行ってください。
v1 ルーティングスキーマのアップグレード手順
v1 スキーマのクラスターをEMQX 5.10.0以降にアップグレードする場合は、以下の手順に従ってください。
- クラスター内のすべてのノードを停止します。
- 設定ファイルに定義されている
broker.routing.storage_schemaオプションをすべて削除します。 - すべてのノードを5.10.0以降のバージョンにアップグレードします。
- コアノードを先に起動します。
- レプリカントノードを起動します。
ローリングアップグレードの一般的な手順
クラスター内の各ノードをダウンタイムなしでアップグレードするには、以下の手順を実行します。
- クラスターリバランシングを使ってノードからクライアントを退避させる（任意）。
- 旧バージョンのノードを停止する。
- ノードの設定ファイルとデータディレクトリをバックアップする。
- 新しいバージョンのEMQXをインストールする。
- 新しいバージョンのノードを起動する。
コアノードとレプリカントノードのアップグレード
コア/レプリカント構成のクラスターでは、クラスターの安定性を保つためにノードを交互にアップグレードします。
- まず1台のコアノードからアップグレードを開始します。
- 次にレプリカントノードの一部（例えばコアノードが3台なら約3分の1）をアップグレードします。
- これを繰り返し、すべてのノードがアップグレードされるまで交互に進めます。
この方法により、レプリカントは常に互換性のあるコアノードに接続できる状態を維持できます。
注意
ローリングアップグレード中にクラスター全体の設定変更は行わないでください。ダッシュボード、HTTP API、CLIからの設定変更はクラスター内のすべてのノードに適用されます。ローリングアップグレード中の設定変更はノード間の同期不整合を引き起こす可能性があります。
RPMおよびDEBパッケージを使用したローリングアップグレード
RPMまたはDEBパッケージを使用している場合は、新しいバージョンのパッケージをインストールするだけでEMQXをアップグレードできます。
Dockerを使用したローリングアップグレード
Dockerを使用している場合は、新しいバージョンのイメージをプルし、コンテナを再起動するだけでEMQXをアップグレードできます。
オープンソース版からエンタープライズ版へのローリングアップグレード
EMQXオープンソース版を使用していて、EMQXエンタープライズ版にアップグレードする場合、手順はオープンソース版の新バージョンへのアップグレードと同じです。
EMQXオープンソース版とEMQXエンタープライズ版のインストールおよびアップグレード手順に違いはありません。唯一の追加ステップは、アップグレード後にエンタープライズ版ノードで手動でライセンスを設定する必要があることです。すべてのノードがアップグレードされる前に、クラスター全体にライセンスキーを適用することはできません。
例として、etc/base.hocon（アップグレード対象バージョンがe5.8.5より前の場合はetc/emqx.conf）に以下の行を追加します。
license.key = "your license"注意
emqx.confにライセンス設定を追加した場合、ダッシュボード、HTTP API、CLIからのランタイム設定変更はノード再起動後に失われます。これは、起動時の設定読み込みにおいてemqx.confと環境変数が最優先されるためです。