# EMQX Cloud V4 から V6 へのアップグレードガイド

EMQX Dedicated デプロイメントをご利用の方は、EMQX を V4 から V6 にアップグレードできます。現在の EMQX バージョンを確認するには、デプロイメント詳細ページを開き、**設定** をクリックしてデプロイメント情報を表示してください。

V4 の安定性と効率性を基盤に、EMQX V6 は認証・認可、監視メトリクス、保持メッセージ、データ統合の包括的な強化を実現しています。また、ネームスペース、ログトレース、イベント履歴、BigQuery データ統合、Snowflake ストリーミングデータ統合などの新機能や機能強化も導入しています。詳細は [新機能](https://docs.emqx.com/en/cloud/latest/new_features.html) をご参照ください。

::: tip 利用可能範囲

EMQX V6 は Dedicated および Dedicated Flex ブローカーのデプロイメントでのみ利用可能です。サーバレスデプロイメントでは EMQX バージョンの選択はサポートされていません。

:::

## アップグレード前の準備

1. アップグレードのスケジュール調整のため、少なくとも3日前に [お問い合わせ](./feature/tickets.md) ください。アップグレードの注意点やメンテナンスウィンドウについてご相談します。
2. 本ガイドを全て読み、特に互換性のない変更点を理解してください。ご不明点があればサポートチケットでお問い合わせください。
3. SRE チームがデプロイメントの包括的な評価を行います。特別な設定や影響がある場合は特記事項として記載し、アップグレードの継続可否をご判断いただけます。
4. ビジネスシステムが V4 の HTTP API を呼び出している場合や外部認証・外部認可、複雑なデータ統合を利用している場合は、アップグレード前に V6 環境で互換性テストを完了してください。

## データ移行および保持される設定

アップグレード中に以下の設定およびデータは保持されます。

- MQTT エンドポイントおよびポート
- すべての認証および認可エントリー
- データ統合設定（リソース、ルール、アクションを含む。ただし互換性に関する注意事項あり）
- TLS 証明書情報
- 保持メッセージ
- ネットワーク管理設定（NAT ゲートウェイ、内部エンドポイント、PrivateLink、VPC ピアリングを含む）

## 互換性のない変更点

- **機能削除**：デバイスシャドウサービスは V6 でサポートされません。
- **特別設定の変更**：サポートチケット経由で以前に依頼された特別設定（追加ポートや ACL 許可リストなど）は影響を受ける可能性があります。SRE チームがアップグレード前に具体的な影響を説明します。
- **HTTP API の変更**：
  - API プレフィックスが `/api` から `/api/v5` に変更されます。
  - V4 の API キーおよびシークレットキーは移行できません。アップグレード後に新しい認証情報を作成し、ビジネスシステムの API エンドポイントと認証情報を更新してください。
  - メッセージパブリッシュ、クライアント照会、ノード管理など、複数の API パスが変更されています。
  - パスの変更に加え、一部 API はリクエストボディ、レスポンス構造、HTTP ステータスコード、エラーコード、フィールド名、フィールド型、時間フォーマットが互換性を持ちません。

    これらの変更は既存のビジネスシステムの API 解析ロジックに影響を与える可能性があります。アップグレード前に必ず互換性テストを行ってください。
  - 詳細は以下のドキュメントを比較してください：
    - [V4 API ドキュメント](https://docs.emqx.com/en/cloud/v4/api/dedicated.html)
    - [最新 API ドキュメント](https://docs.emqx.com/en/cloud/latest/api/dedicated.html)
- **外部認証の変更**：設定フィールドおよびクエリ・レスポンス要件が変更されています。[外部認証と認可](https://docs.emqx.com/en/cloud/latest/deployments/custom_auth.html) ドキュメントに従って設定を更新してください。
- **データ統合の互換性**：
  - ルールに紐づかないリソースは保持されません。アップグレード前にこれらのリソースが必要か確認してください。
  - ルールに設定されたフォールバックアクションは保持されません。V6 のデータ統合アーキテクチャではフォールバックアクションをサポートしません。
  - リソースやアクションに紐づかない空のアクションはアップグレード時に自動削除されます。
  - `WHERE` を使った一部のルール SQL 文は新バージョンと互換性がなく、手動で更新が必要な場合があります。例えば、フィールドの存在判定は V4 では `<> "undefined"` を使いますが、新バージョンでは `is_null` を使います。

## アップグレードの影響

1. アップグレードには 15～25 分かかり、そのうち約 **5～15 分** はサービス停止が発生します。
2. アップグレードのために **2時間** のメンテナンスウィンドウが設けられます。この期間中のサービス停止や互換性問題によるサービス不可は SLA の可用性計算から除外されます。
3. アップグレード中にクライアント接続は 1～2 回切断されます。クライアント側で自動再接続が有効になっていることを確認してください。
4. `clean session = false` で作成されたセッションは保持されません。クライアントは再接続後に新しいセッションを作成します。

## アップグレード後の対応

### アップグレード後の検証

1. アップグレード後、EMQX Cloud SRE チームがデプロイメントのログとメトリクスを確認します。
2. 以下を中心に包括的なビジネス検証を実施してください：
   - HTTP API 呼び出しが新しいパスおよび新規作成した API キー・シークレットキーを使用しているか
   - HTTP API のレスポンス構造がビジネスシステムの解析ロジックと互換性があるか
   - 組み込みおよび外部の認証・認可が正常に動作しているか
   - データ統合のコネクター、ルール、ソース、シンクが正常に動作しているか
   - クライアント接続、サブスクライブ、メッセージのパブリッシュおよび配信が正常に動作しているか
   - TLS 接続およびカスタム証明書が正常に動作しているか
3. 問題が見つかった場合は速やかにご連絡ください。

### ロールバック

- アップグレード確定前に 24 時間のロールバック期間があり、この期間内は V6 から V4 へロールバック可能です。
- ロールバックには 15～25 分かかり、そのうち約 3～5 分のサービス停止が発生します。
- ロールバック中もクライアント接続は 1～2 回切断されます。
- `clean session = false` で作成されたセッションは保持されません。

## V6 コア機能の詳細な変更点

このセクションでは、V4 から V6 へのアップグレードで導入される機能強化、アーキテクチャ改善、および対応するコンソールの変更について説明します。

### 強化された証明書管理

V6 デプロイメントでは、デフォルトで一方向 TLS 証明書（デプロイメントエンドポイントドメインのワイルドカード証明書）が含まれています。ポート 8883 と 8084 で TLS 接続が可能です。カスタム TLS 証明書をこれらのポートに適用できます。**カスタム証明書を削除すると、デフォルトのデプロイメントエンドポイント証明書に戻ります。**

### HTTP API の変更

- API エンドポイントが `https://xxx/api` から `https://xxx/api/v5` に変更されます。
- V4 の API キーおよびシークレットキーは移行できず、アップグレード後に再作成が必要です。
- API パスの変更に加え、一部 API はリクエストボディ、レスポンス構造、HTTP ステータスコード、エラーコード、フィールド名、フィールド型、時間フォーマットが互換性を持ちません。

ビジネスシステムが既存の V4 API レスポンス構造に依存している場合は、アップグレード前に必ず互換性テストを実施してください。詳細は [最新 API ドキュメント](https://docs.emqx.com/en/cloud/latest/api/dedicated.html) の認証セクションをご参照ください。

### アクセス制御の改善

- **Authentication & ACL** 機能は **Access Control** に名称変更されました。
- 組み込み認証・認可データと外部認証・認可設定は移行されます。
- 外部認証と外部認可はそれぞれ **External Authentication** と **External Authorization** に分離され、エントリーポイントはそれぞれ **Client Authentication** の下の **External Authentication** と **Client Authorization** の下の **External Authorization** に移動しました。
- 認証チェーン内の認証メカニズムの優先順位は手動で調整可能です。
- クライアント ID、ユーザー名、全ユーザーの3レベルでデフォルトのクライアント認可ルールを設定可能です。クライアントまたはユーザー名の認可情報は対応するタブに表示されます。

### 監視機能の再設計

- 旧 Monitoring ページのリアルタイムメトリクスは Metrics ページに移動し、リアルタイムメトリクスや時系列データを閲覧できます。
- 旧 Monitoring ページのクライアントおよびサブスクリプション管理は、Monitoring 配下の別ページである **Clients** および **Subscriptions** に分割されました。
- 新たに保持メッセージ管理ページが追加され、保持メッセージのクエリおよび削除が可能です。

### データ統合アーキテクチャのアップグレード

#### ルール、ソース、シンクのアーキテクチャ

::: tip 互換性に関する注意

V6 へのアップグレード後、以下のルール互換性にご注意ください：

- 空のアクションはアップグレード時に自動削除されます。
- `WHERE` を使った一部のルール SQL 文は V6 と互換性がなく、手動で更新が必要な場合があります。例として、フィールドの存在判定は V4 では `<> "undefined"`、V6 では `is_null` を使用します。

:::

- ルールとアクションは論理的に分離され、より柔軟な設定が可能です。
- シンクは外部サービスへデータを送信します。
- ソースは外部サービスから EMQX へデータを取り込みます。V4 の MQTT Subscribe プラグインに類似しています。
- フォールバックアクションはサポートされなくなりました。

#### データ統合サポートの拡充

- 新たなデータ転送統合には Elasticsearch、Azure Event Hubs、Amazon Kinesis、SysKeeper Forwarder が含まれます。
- 新たなデータ永続化統合には Apache IoTDB、GreptimeDB、Amazon S3 が含まれます。
- Kafka Consumer や MQTT Source などの統合を通じてメッセージキューや MQTT サービスからデータを取り込めます。
- V6 では BigQuery および Snowflake ストリーミングデータ統合も導入されています（以下の V6 固有機能参照）。

#### Smart Data Hub のアップグレード

Smart Data Hub はインテリジェントなデータ処理の統合ソリューションです。スキーマ管理、データ検証、リアルタイムデータ変換を行い、MQTT データストリーム処理を簡素化し、データ標準化とビジネス統合を向上させます。

V4 デプロイメントでスキーマレジストリを設定している場合、アップグレード後に Smart Data Hub が自動的に有効になります。

### V6 固有の機能

::: tip 注意

以下の機能は EMQX V6 をサポートする Dedicated および Dedicated Flex デプロイメントのみで利用可能です。実際の利用可否は V6 のマイナーバージョン、リージョン、コンソールに表示されるオプションによります。

:::

| V6 固有機能 | 実用的な価値 |
| --- | --- |
| ネームスペース | マルチテナントシナリオでのリソースおよび権限の分離を提供します。ルール、コネクター、アクションなどのリソースをテナント、チーム、事業部門ごとに整理でき、テナント間の影響を減らし、共有クラスターでの運用を簡素化します。 |
| ログトレース | 特定のクライアント、トピック、クライアント IP アドレス、ルール ID に対するデバッグログを収集できます。全デプロイメントの詳細ログを有効にすることなく、対象を絞ったトラブルシューティングに役立ちます。 |
| イベント履歴 | 最近の接続、認証、サブスクリプションイベントを保持し、接続失敗、予期しない切断、認証失敗、サブスクリプションの未反映などの診断に利用できます。 |
| BigQuery データ統合 | ルールエンジンと BigQuery シンクを通じて MQTT データを BigQuery に書き込み、SQL 分析やレポーティングに活用できます。 |
| Snowflake ストリーミングデータ統合 | ルールエンジンと Snowflake ストリーミングシンクを通じて低レイテンシでデータを Snowflake テーブルに書き込み、リアルタイムに近いデータ取り込みや分析、ビジネスインサイトに適しています。 |

#### ネームスペース

ネームスペースはマルチテナント管理とリソース分離を強化します。管理者はテナント、部門、事業部門ごとにリソース範囲を分割し、各ネームスペース内でルール、コネクター、アクションを独立して管理できます。複数のチームや顧客が1つのデプロイメントを共有する場合、ネームスペースは誤操作によるリソース変更やテナント間の影響を減らします。

#### ログトレース

ログトレースはコンソールから特定の MQTT クライアント、トピック、クライアント IP アドレス、ルール ID に対するデバッグレベルログを収集できます。全デプロイメントの詳細ログを有効にするよりも影響範囲が限定され、正常なワークロードへの影響が少なく、特定のクライアントやトピック、ルール処理経路に関する問題の再現や診断に適しています。

#### イベント履歴

イベント履歴は最近のクライアント接続、認証、サブスクリプションイベントを記録します。以下の調査に利用可能です：

- クライアント接続失敗や予期しない切断
- クライアント認証失敗
- サブスクリプションの作成失敗や反映されない状態
- 接続およびサブスクリプションのタイムライン

#### BigQuery データ統合

ルールエンジンが MQTT メッセージをフィルタリング・処理し、BigQuery シンクが Google BigQuery に書き込みます。この統合は大量の IoT データに対する SQL 分析、データウェアハウジング、レポーティングに適しています。

#### Snowflake ストリーミングデータ統合

Snowflake ストリーミングシンクは MQTT データを低レイテンシで Snowflake テーブルに書き込みます。リアルタイムに近いデータ取り込み、分析、ビジネスインサイトに適しています。

#### MQTT ソースの強化

V6 の MQTT ソースは共有サブスクリプショントピックをサポートし、重複メッセージを削減します。また、MQTT 5.0 のサブスクライブオプションである **No Local** や **Retain As Published** に対応し、リモート MQTT サービスからのデータブリッジに柔軟性を提供します。

## アップグレードの確定

上記のアップグレード範囲と潜在的リスクを十分に理解した上で、アップグレードスケジュールの確定のためにご連絡ください。アップグレード全体を通じて技術サポートを提供し、成功に導きます。