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.9.0および5.10.0より後のリリースです。5.8系で5.8.7以降を使用している場合は、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と環境変数が最優先されるためです。