EMQX Enterprise ローリングアップグレード
クラスター構成でのデプロイメントにおいて、EMQX ノードはダウンタイムなしで1台ずつアップグレードできます。このプロセスをローリングアップグレードと呼びます。クライアントセッションのスムーズな移行を実現するために、EMQX Enterprise のクラスターリバランシング機能を使用して、アップグレード前にノードからクライアントを退避させることが可能です。クラスターリバランシングの詳細についてはこちらをご参照ください。
EMQX 5.9以降へのアップグレードに関する重要なお知らせ
バージョン5.9.0以降、EMQX Enterpriseは従来のオープンソース版と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以降のサポートされているローリングアップグレードパスのマトリックスです。
- バージョン番号の末尾に
?が付くもの（例：6.1?）は将来のリリース予定です。 - ✅: サポート済み、またはサポート予定。
- ⚠️: サポートはあるが制限あり。
- ❌: サポートなし。
- 🔄: 将来バージョンでの完全サポート予定。
詳細はリリースノートをご覧ください。
| From\To | 5.1 | 5.2 | 5.3 | 5.4 | 5.5 | 5.6 | 5.7 | 5.8 | 5.9 | 5.10 | 6.0 | 6.1? |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 5.0 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️[1] | ❌[2] | ❌[2] | ❌[2] |
| 5.1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌[2] | ❌[2] | ❌[2] |
| 5.2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌[2] | ❌[2] | ❌[2] | |
| 5.3 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌[2] | ❌[2] | ❌[2] | ||
| 5.4 | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | |||
| 5.5 | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ||||
| 5.6 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | |||||
| 5.7 | ✅ | ✅ | ✅ | ✅ | ⚠️[4] | ⚠️[4] | ||||||
| 5.8 | ✅ | ⚠️[3] | ⚠️[3] | ⚠️[4] | ⚠️[4] | |||||||
| 5.9 | ✅ | ✅ | ⚠️[4] | ⚠️[4] | ||||||||
| 5.10 | ✅ | ⚠️[4] | ⚠️[4] | |||||||||
| 6.0 | ✅ | ✅ | ||||||||||
| 6.1? | ✅ |
- [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統合のヘッダー設定を削除してください。
- [4] v5からv6へのアップグレード後、Durableセッション状態は失われます。クライアントが再接続すると、新しいノードで作成されたセッションはクリーン状態として表示されます。
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をアップグレードできます。
オープンソース版からEnterprise版へのローリングアップグレード
オープンソース版のEMQXを実行していてEnterprise版にアップグレードする場合、アップグレード手順はオープンソース版の新バージョンへのアップグレードと同じです。
EMQXのオープンソース版とEnterprise版のインストールおよびアップグレードに違いはありません。 唯一の特別な点は、アップグレード後にEnterprise版ノードに対して手動でライセンス設定を行う必要があることです。 すべてのノードがアップグレードされる前に、クラスター全体にライセンスキーを適用することはできません。
例えば、etc/base.hocon（アップグレード対象バージョンがe5.8.5以前の場合はetc/emqx.conf）に以下の行を追加します。
license.key = "your license"注意
emqx.confにライセンス設定を追加した場合、ダッシュボード、HTTP API、CLIからのランタイム設定変更はノード再起動後に失われます。 これはemqx.confおよび環境変数が起動時の設定読み込みで最優先されるためです。