# 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.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以降へのローリングアップグレードはできません。

::: 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エンタープライズ版にアップグレードする場合、手順はオープンソース版の新バージョンへのアップグレードと同じです。

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

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

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