# EMQX Enterprise ローリングアップグレード

クラスター展開において、EMQX ノードはダウンタイムなしで1台ずつアップグレードできます。このプロセスをローリングアップグレードと呼びます。クライアントセッションのスムーズな移行を実現するために、EMQX Enterprise のクラスターリバランシング機能を使用して、アップグレード前にノードからクライアントを退避させることが可能です。クラスターリバランシングの詳細については、[こちら](../../guides/cluster/rebalancing.md)をご参照ください。

## EMQX 5.9以降へのアップグレードに関する重要なライセンス通知
バージョン5.9.0以降、EMQX Enterpriseは従来のオープンソース版とエンタープライズ版を分離したモデルから、Business Source License（BSL）1.1の下でリリースされています。

::: tip

ライセンス変更の詳細については、[EMQX ライセンスFAQ](https://www.emqx.com/en/content/license-faq)をご覧ください。

:::

EMQXのアップグレード手順（バイナリの置き換えなど）は従来のバージョンアップと似ていますが、5.9.0では特にクラスター展開に関して重要なライセンス変更があります。5.9より前のオープンソース版からアップグレードする場合や、単一ノード展開からクラスター展開へアップグレードする場合は、以下の重要な変更点にご注意ください。

1. **新しいライセンスモデル**：EMQX 5.9.0以降はデフォルトでEMQX Community Licenseが適用されます。このデフォルトライセンスはすべての機能を有効にしますが、展開は単一ノードに制限されます。
2. **クラスター機能の制限**：以前のオープンソース版ではクラスターがサポートされていましたが、新モデルではEMQX 5.9.0以降のデフォルト設定ではクラスターは許可されていません。クラスター機能を維持したい場合は、[商用ライセンス](./license.md#apply-for-a-license)を取得する必要があります。
3. **ライセンス設定の必須化**：アップグレード中にEMQX 5.9.0以降のノードをクラスターで起動する前に、各ノードに商用ライセンスを[設定](./license.md#update-and-configure-license-settings)する必要があります。ライセンスが設定されていない、または誤って設定されている場合、ノードはクラスター内で正常に動作しません。

::: 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へのアップグレード後、Durableセッション状態は失われます。クライアントが再接続すると、新ノード上のセッションはクリーンな状態として表示されます。

## EMQX 5.10以降のローリングアップグレードに関する注意点

EMQX 5.10.0以降は、_v2_ルーティングストレージスキーマのみがサポートされています。5.4.0以前のデフォルトであった旧_v1_スキーマは非互換となりました。そのため、特に古いバージョンから段階的にアップグレードされたクラスターで_v1_スキーマを使用している場合、5.10.0以降へのローリングアップグレードはできません。

::: tip 重要

クラスターがまだ_v1_ルーティングスキーマを使用している場合は、アップグレード完了のためにクラスター全体の再起動が必要です。

:::

### 現在のルーティングスキーマの確認

以下のコマンドで、EMQXクラスターが使用しているルーティングスキーマを確認してください。
```
$ emqx eval 'emqx_router:get_schema_vsn()'
```

出力が`v2`であれば、通常のローリングアップグレードを実施できます。

出力が`v1`の場合は、以下の手順でクラスター全体の再起動を伴うアップグレードを行ってください。

### _v1_ルーティングスキーマのアップグレード手順

_v1_スキーマを使用しているクラスターをEMQX 5.10.0以降にアップグレードするには、以下の手順を実行してください。

1. クラスター内の**すべての**ノードを停止します。
2. 設定ファイル内で定義されている`broker.routing.storage_schema`オプションをすべて削除します。
3. すべてのノードを5.10.0以降のバージョンにアップグレードします。
4. コアノードを先に起動します。
5. レプリカントノードを起動します。

## ローリングアップグレードの一般的な手順

クラスター内の各ノードをダウンタイムなしでアップグレードするには、以下の手順に従ってください。

1. クラスターリバランシングを使ってノードからクライアントを退避させます（任意）。
2. 古いバージョンのノードを停止します。
3. ノードの設定ファイルとデータディレクトリを[バックアップ](../../guides/backup-restore.md)します。
4. 新しいバージョンのEMQXをインストールします。
5. 新しいバージョンのノードを起動します。

**コアノードとレプリカントノードのアップグレード**

コア/レプリカント構成のクラスターでは、クラスターの安定性を保つためにノードを交互にアップグレードします。

- まず1台のコアノードをアップグレードします。
- 次に、レプリカントノードの一部（例えばコアノード3台なら約3分の1）をアップグレードします。
- コアノードとレプリカントノードを交互にアップグレードし、すべてのノードを更新します。

この方法により、レプリカントは常に互換性のあるコアに接続できる状態が維持されます。

:::tip 注意
ローリングアップグレード中にクラスター全体の設定変更は行わないでください。ダッシュボード、HTTP API、CLIからの設定変更はクラスター内のすべてのノードに適用されます。アップグレード中に設定を変更するとノード間で設定の不整合が発生する可能性があります。
:::

## RPMおよびDEBパッケージを使用したローリングアップグレード

RPMまたはDEBパッケージを使用する場合は、新しいバージョンのパッケージをインストールするだけでEMQXをアップグレードできます。

## Dockerを使用したローリングアップグレード

Dockerを使用する場合は、新しいバージョンのイメージをプルしてコンテナを再起動するだけでEMQXをアップグレードできます。

## オープンソース版からエンタープライズ版へのローリングアップグレード

EMQXオープンソース版を使用していてEMQX Enterprise版にアップグレードする場合、手順はオープンソース版の新バージョンへのアップグレードと同じです。

EMQXオープンソース版とEMQX Enterprise版のインストールおよびアップグレード手順に違いはありません。追加の手順として、アップグレード後に各Enterprise版ノードで手動で[ライセンスを設定](./license.md)する必要があります。すべてのノードがアップグレードされる前にクラスター全体にライセンスキーを適用することはできません。

例として、`etc/base.hocon`（アップグレード対象バージョンが`e5.8.5`より前の場合は`etc/emqx.conf`）に以下の行を追加します。
```
license.key = "your license"
```

:::tip 注意
`emqx.conf`にライセンス設定を追加した場合、ダッシュボード、HTTP API、CLIからのランタイム変更はノード再起動後に失われます。これは起動時の設定読み込みで`emqx.conf`と環境変数が最優先されるためです。
:::