Skip to content

Hot Upgrade (Relup) ​

このプラグインは、実行中のEMQXノードに対して.relup形式のコード変更指示を適用することで、VMを再起動せずにパッチリリースを展開できるようにします。

オペレーターは各ノードでemqx ctl relup ... CLIを使って操作します。クラスター全体への展開はオペレーターの責任であり(オーケストレーション機能は組み込まれていません)。

使用タイミング ​

Hot Upgradeは以下の場合に適しています:

  • 適用したいホップがemqx ctl relup list-supported-pathsでリストされている(宣言された{from, target}ホップのみサポート)。
  • 次のノードに進む前にターゲットノードを検証できる。
  • data/のバックアップがある。適用済みホップのインプレースロールバックはありません(ロールバック参照)。

これらを満たせない場合は、通常のローリング再起動を行ってください。

オペレーターのワークフロー ​

1. プラグインのインストール ​

以下のDownloadセクションからEMQXバージョンに合ったtarballをダウンロードし、ダッシュボード(またはREST API / CLI)から他のプラグインと同様にインストールします。

2. アップグレードパスのサポート確認 ​

bash
emqx ctl relup list-supported-paths

出力にはこのプラグインバージョンのpriv/relup/にバンドルされた{from, target}ホップが表示されます。ホップが存在しない場合、そのパスのHot Upgradeは利用できません。通常の再起動ベースのアップグレードに戻ってください。

3. 各ノードにターゲットリリースをステージング ​

各ノードでEMQXプロセスが読み取れるパスに以下の2ファイルをコピーします:

  • emqx-enterprise-<TargetVsn>-<os>-<arch>.tar.gz:EMQXターゲットリリースのtarball
  • <tarball>.sha256:sha256ダイジェスト。標準のsha256sum形式(<digest> <filename>)が受け入れられます。

4. アップグレードのトリガー ​

各ノードで以下を実行します:

bash
emqx ctl relup upgrade <TarballPath> [--force]

ハンドラーは以下を行います:

  • <TarballPath>.sha256と実際のダイジェストを照合し、不一致の場合は展開を拒否。
  • data/patches/に*.beamファイルが存在する場合は継続を拒否。このディレクトリはvm.args -paでコードパスの先頭に追加されるため、アップグレードターゲットのモジュールより優先されます。ターゲットリリースにホットパッチ済みの修正が含まれている場合でも、古いbeamファイルが読み込まれる可能性があります。パッチファイルを削除するか、ターゲットリリース上に適用済みのまま維持したい場合のみ--forceを指定してください。
  • tarballを展開し、releases/emqx_varsからREL_VSNを読み込みます。
  • priv/relup/*.relupで該当する{from, target}ホップを検索し、宣言されたコード変更指示とアップグレード後のコールバックを実行します。

5. ノードの検証 ​

次の点を確認してから次に進みます:

  • emqx ctl statusでノードが稼働中であること。
  • <RootDir>/relup/currentがターゲットバージョンと一致し、<RootDir>/relup/<TargetVsn>/にbin/、erts-*/、lib/、releases/が存在すること。

次回のemqx startまたはrestart時に、bin/emqxラッパーがrelup/currentを検出し、展開済みツリー(新しいERTS、新しいbinスクリプト、新しいlib)にexecします。元の<RootDir>はdata/、etc/、log/、plugins/の権威として残ります。

6. 成功後のクリーンアップ ​

クラスター全体がターゲットバージョンに移行したら、手動でステージングしたtarballとその.sha256サイドカーを削除してください。プラグインはソースパスを追跡しないため、プラグイン側での状態クリアは不要です。

アップグレード履歴 ​

各ノードはemqx_relup_logテーブル(ディスクバック、ローカル内容)に独自の監査ログを保持します。履歴はプラグインアンインストール後も残り、再インストールで再接続されます。

CLIで確認・削除可能です:

bash
emqx ctl relup logs           # 最近のアップグレード試行を表示
emqx ctl relup logs-clear     # このノードのログ行をすべて削除

ロールバック ​

適用済みホップのインプレースロールバックはありません。Hot UpgradeはライブVMに対してcode_changesを実行し、post_upgrade_callbacksでディスク上のデータを変更している可能性があるため、これを元に戻すことはプラグインでサポートされていません。

実用的なフォールバックパス:

  • 次回再起動前に、アップグレードが成功したが新コードに問題があり、ディスク上のデータが旧リリースと互換性がある場合:

    bash
    rm <RootDir>/relup/current
    # 必要に応じて: rm -rf <RootDir>/relup/<TargetVsn>/
    emqx restart

    ラッパーは元の<RootDir>/bin/emqxツリーにフォールバックします。これは起動パスのみ回復し、アップグレード時のVM内のライブ状態は失われています。

  • それ以外の場合は、アップグレード前に取得したdata/(mnesia、設定など)のバックアップから復元し、旧EMQXリリースを再インストールしてください。この点を考慮してアップグレードウィンドウを計画してください。

ホップの作成(開発者向けメモ) ​

新しいホップを追加するには、必要な各リリースに対して:

  1. priv/relup/<from>-to-<to>.relupを追加し、そのホップのcode_changesとpost_upgrade_callbacksを宣言します。プラグインソースのpriv/relup/README.mdにスキーマ、サポートされる命令、アップグレード後コールバックの契約が記載されています。特に新しいEMQXのemqx_post_upgradeにpr_NNNNN_*コールバックを追加する場合、relupホップはコールバック呼び出し前にそのモジュールをリロードするか、このプラグイン内にemqx_post_upgrade_<TargetVsn>.erlとしてコールバックを同梱する必要があります。
  2. このプラグインのVERSIONを更新して再公開します。

プラグインは起動時にすべてのpriv/relup/*.relupを検証し、不正なエントリは警告ログを出しスキップします。致命的エラーにはなりません。

Download ​

各EMQXリリース用のtarball:

EMQX VersionPlugin VersionPackage
6.3.01.0.2emqx_relup-1.0.2.tar.gz (sha256)
6.3.11.0.2emqx_relup-1.0.2.tar.gz (sha256)
6.3.21.0.2emqx_relup-1.0.2.tar.gz (sha256)
6.3.31.0.3emqx_relup-1.0.3.tar.gz (sha256)