このページの内容
RabbitMQのアップグレードはなぜ失敗するのか
「多くの企業が苦労している、あるいは忘れているのは、アップグレードを頻繁に行わないことです。アップグレードに数年かかることもあります。そして今のバージョンから最新版へ一気に移ろうとすると、予期しない問題が次々に起きます。本来は、段階を踏んでアップグレードすべきだったからです。」
— Jeff Sogolov(AceMQエンジニア)、Lucidyaとのセッションにて、2025年5月
3.xから4.xへの必須のアップグレードパスは?
rabbitmqctl enable_feature_flag allErlangの互換性はどうなっているか
- 3.12はErlang 25.x以上に対応
- 3.13にはErlang 26以上が必要(26.2を推奨)
- 4.xにも同様にErlang 26.2以上が必要
「Erlangは25から26.2へ直接アップグレードできます。26.2にしてしまえば、RabbitMQを3.13にアップグレードするときには、すでに適切なErlangが揃っています。その後3.13から4.1に上げる場合も、同じErlangのバージョンがそのまま使えます。」
— Jeff Sogolov(AceMQエンジニア)、Lucidyaとのセッションにて、2025年5月
戦略1:ローリングアップグレード(インプレース)
- ノード1を停止する(OSではなくサービスのみ)
- ノード1のErlangを必要なバージョンにアップグレードする
- ノード1のRabbitMQを目標バージョンにアップグレードする
- ノード1でRabbitMQサービスを起動する
- ノード1がクラスターに再参加し、正常であることを確認する
- ノード2と3でも同じ手順を繰り返す
戦略2:ブルーグリーンデプロイメント
- 目標とするRabbitMQとErlangのバージョンで新しいクラスター(グリーン)を構築する
- グリーンのクラスターに、ブルーのクラスターを指すフェデレーテッドキューのアップストリームを設定する
- コンシューマーをグリーンのクラスターに移すと、Federationがブルーからグリーンへ自動的にメッセージを取り込む
- すべてのコンシューマーがグリーンに移ったら、プロデューサーをグリーンに移す
- プロデューサーを移したら、Shovelプラグインを使ってブルーに残っているメッセージを移し切る
- ブルーのクラスターを廃止する
「ブルーグリーンならダウンタイムはゼロです。いつでも実施でき、メンテナンスモードも必要ありません。代償は、2つのクラスターを同時に稼働させることで、特にオンプレミスではそれを負担できない企業もあります。しかし、新しいクラスターを簡単に立ち上げられるAWSベースの環境であれば、非常に理にかなった方法です。」
— Jeff Sogolov(AceMQエンジニア)、Lucidyaとのセッションにて、2025年5月
アップグレード前のチェックリスト
- 現在のRabbitMQのバージョンを確認し、必要なアップグレードパスを特定する
- 目標バージョンと中間バージョンについて、Erlangの互換性マトリクスを確認する
- 現在のバージョンですべてのフィーチャーフラグを有効にする(rabbitmqctl enable_feature_flag all)
- Management API経由でクラスターの定義(トポロジー、ユーザー、権限)をバックアップする
- 本番環境に手を付ける前に、ステージング環境でアップグレードをエンドツーエンドで検証する
- ノードをオフラインにしたときのロードバランサーのヘルスチェックの挙動を確認する
- ステージング環境でノードの再起動を模擬し、クライアントの再接続の挙動をテストする
- ローリングアップグレードの場合は、最もトラフィックの少ない時間帯に実施を予定する
- 開始前にロールバック計画を文書化しておく
作業時間帯を確定する前に、より広い観点で準備状況を確認するには、RabbitMQ移行準備チェックリストをご覧ください。
3.xの環境を壊しかねないRabbitMQ 4.xの変更点
3.xから4.xへのアップグレードで失敗するケースのほとんどは、限られた数の変更点のいずれかが原因です。4.0のリリースノートを読んでいれば意外なものはありませんが、3.8や3.9の慣習のもとで成長してきた大規模な環境では、どれも見落としがちです。
- クラシックキューのミラーリングは廃止されました。ミラーリングされたクラシックキュー(
ha-modeとha-paramsのポリシーキー)は3.9で非推奨となり、4.0で削除されました。4.xのノードはクラシックキューをミラーリングしないため、レプリケーションをHAポリシーに頼っていたキューは、ポリシーが適用されなくなった時点で単一ノードのキューになります。これは、アップグレード後ではなくアップグレード前に対処しなければならない唯一の変更点です。ミラーリングされた各キューをクォーラムキューに移行してから、HAポリシーを削除してください。rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policyを実行すれば、まだ残っているかどうかがわかります。トレードオフについてはクラシックキューとクォーラムキューの比較の記事で解説しています。 - 一時的な非排他キューは非推奨になりました。接続に対して排他的でない非永続キューは非推奨機能として扱われ、設定によって拒否できます。4.xでもまだ動作しますが、すべての場所で永続キューを宣言し、本当に接続単位の状態には排他キューを使うよう計画してください。
- デフォルトのキュータイプ。仮想ホストで
default_queue_typeが設定されていない限り、x-queue-typeを指定せずにキューを宣言すると、引き続きクラシックキューになります。新しいワークロード向けにはvhostごとにquorumを設定し、キューを宣言するクライアントコードでは明示的にx-queue-typeを渡すようにして、vhostレベルのデフォルトで誰かが驚くことのないようにしてください。 - AMQP 1.0はコアプロトコルになりました。4.0では独立したAMQP 1.0プラグインは不要になり、1.0は同じリスナー上で0-9-1と並んでネイティブに実装されています。既存の0-9-1クライアントには影響しません。旧プラグインを使っていたチームは有効化済みプラグインの一覧から削除し、1.0を使いたいチームは、レガシーなものではなく、保守が続いている1.0のクライアントライブラリに移行してください。
- メタデータストアとしてのKhepri。Mnesiaに代わるRaftベースのKhepriは、3.13で実験的機能として提供され、4.xでサポート対象になりましたが、オプトイン方式です。
khepri_dbフィーチャーフラグを意図的に有効にするまで、ノードはアップグレード後もMnesiaを使い続けます。これはバージョンアップの副次的な変化ではなく、独自のテスト期間を設けた別の変更として扱ってください。 - フィーチャーフラグは、先にすべて有効にしておく必要があります。安定版フィーチャーフラグが1つでも無効のままになっている3.13クラスターには4.xのノードを参加させられず、4.xのノードはそのクラスターに対して起動を拒否します。最初のノードを移行する前に、すべてを有効にしてください。
- プラグインとマネジメントUI。3.x向けにコンパイルされたプラグインには、4.x向けのビルドが必要です。マネジメントプラグイン自体は引き継がれますが、ミラーリング関連の画面はなくなり、AMQP 1.0プラグインは何もしなくなります。コミュニティ製のプラグインは、動作すると決めつける前に必ず確認してください。
- MQTT 5。MQTT 5のサポートは3.13で追加され、4.xにも引き継がれています。3.12以前から移行する場合、MQTTクライアントはこのパスの過程でMQTT 5を利用できるようになります。
- Erlang。4.xにはErlang/OTP 26以降が必要です。ノードがまだOTP 25で動いている場合、Erlangのアップグレードはローリングアップグレードの一環として1台ずつ行います。目標バージョンを決める前に、Erlang 26のサポート終了とRabbitMQに関する解説をご覧ください。
3.13にとどまるべきか、4.xにアップグレードすべきか
3.13は最後の3.xシリーズです。そのコミュニティサポート期間は短く、終了すると、どの3.xバージョンにもアップストリームのセキュリティパッチは提供されなくなります。これが判断を左右する、ごまかしのない制約です。
3.13にとどまることが妥当なのは、ただ1つのケースだけです。運用中のバージョンにセキュリティ修正をバックポートする商用サポートや延長サポートの契約がある場合です。それがなければ、3.13クラスターはCVEの時限爆弾です。当社の延長LTSサポートは、3.8.xから3.13.xまでを対象にパッチをバックポートしており、お客様はアップストリームのスケジュールに縛られることなく、自社で管理するスケジュールで古いシリーズを運用できます。これは時間を稼ぐものであり、移行を計画する必要がなくなるわけではありません。
次の4つの条件がすべて満たされたら、アップグレードしてください。
- ミラーリングされたクラシックキューがなくなり、HAポリシーも残っていない。
- すべてのノードで、すべての安定版フィーチャーフラグが有効になっている。
- ErlangがOTP 26以降になっている、またはローリングアップグレード中にErlangを更新する準備ができている。
- クライアントアプリケーションが、クォーラムキューに対して正しく動作する保守中のライブラリバージョンを使っている(
x-delivery-limit、デッドレター、再接続を正しく処理できる)。
プラグインなしでAMQP 1.0を使いたい場合、古い3.xでMQTT 5を使いたい場合、あるいは4.xのクォーラムキューの改良点が必要な場合は、メンテナンス計画が示すよりも早くアップグレードしてください。改良点には、メッセージの優先度や、ポイズンメッセージが永遠に循環し続けるのを防ぐデフォルトの配信回数上限が含まれます。
3.8から3.12を使っている場合も答えは同じですが、パスは長くなります。まず3.13に移行して安定させてから、4.xに移行してください。当社はお客様に代わってその両方の段階を実施しており、RabbitMQのアップグレードとパッチ適用サービスもその前提で範囲を定めています。
使い続けることが安全かどうかは、それが可能かどうかとは別の問題です。RabbitMQ 3.xは今も安全に運用できるのかでは、サポート終了日とCVEのリスクをシリーズごとに検証しています。使い続ける場合は、RabbitMQ 3.x向け延長LTSサポートによって、アップグレードの機会を待つ間もバージョンにパッチを適用し続けられます。
当社が使っているローリングアップグレードの手順書
当社がお客様のクラスターで実施している手順は次のとおりです。3台または5台のノードからなるクラスターで、重要なものにはすべてクォーラムキューを使い、クライアントは接続が切れると再接続することを前提としています。
- 棚卸し。バージョン、Erlangのバージョン、有効なプラグイン、すべてのポリシーを記録します。任意のノードで
rabbitmq-diagnostics check_if_any_deprecated_features_are_usedとrabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policyを実行します。先に進む前に、どちらも問題なしという結果が返ってくる必要があります。 - すべての安定版フィーチャーフラグを有効にする。1台のノードで
rabbitmqctl enable_feature_flag allを実行すれば、クラスター全体に適用されます。rabbitmqctl list_feature_flagsで確認してください。disabledのままのものが1つでもあると、アップグレードできません。 - ミラーリングされたクラシックキューを、フローごとにクォーラムキューへ変換する。クォーラムキューへはその場で変換できません。フローごとに、クォーラムキューを宣言し、コンシューマーの接続先を変え、プロデューサーの接続先を変え、古いキューをドレインしてから削除します。ミスがあっても影響が環境全体ではなく1つのフローにとどまるよう、アプリケーション単位で行ってください。
- Erlangの目標バージョンを確認する。OTP 26以降のパッケージがすべてのノードで利用可能であること、そしてそれが使用する4.xビルドのテストに使われたバージョンであることを確認します。
- 定義をエクスポートし、バックアップを取る。
rabbitmqctl export_definitionsに加えて、すべてのノードでデータディレクトリのファイルシステムバックアップを取ります。ロールバックの境界を越えてしまった場合に再構築の元になるのが、この定義のエクスポートです。 - 1台ずつノードをアップグレードする。ノードを停止する前に
rabbitmq-upgrade await_online_quorum_plus_oneを実行し、このノードが離脱している間にどのクォーラムキューも過半数を失わないようにします。次にrabbitmq-upgrade drainでノードをメンテナンスモードにし、クライアントの接続を正常に閉じて、クォーラムキューのリーダーを他のノードに移します。サービスを停止し、必要に応じてErlangをアップグレードし、RabbitMQをアップグレードして起動し、クラスターに再参加したことを確認します。 - クォーラムキューのメンバーが追いつくのを待つ。最も負荷の高いキューで
rabbitmq-queues quorum_status <queue>を実行するか、次に停止する予定のノードでrabbitmq-diagnostics check_if_node_is_quorum_criticalを実行します。これが通るまで、次のノードの作業を始めないでください。 - クライアントが再接続したことを確認する。アップグレードしたノードの接続数が、マネジメントUI上で通常の水準に戻るはずです。再接続しないクライアントライブラリがあれば、次のノードに進む前に今すぐ修正してください。
- 残りの各ノードで繰り返す。この間、クラスターでは3.13と4.xが混在して動作します。最後のノードが完了するまで、ポリシーの変更、キューの追加、新しい機能の有効化は行わないでください。
- 4.xの新しいフィーチャーフラグを有効にする。最後のノードのアップグレードが終わったら、もう一度
rabbitmqctl enable_feature_flag allを実行します。ここがロールバックの境界です。4.x専用のフィーチャーフラグを有効にすると、ダウングレードの手段はなくなります。この手順より前の作業はすべて、ノードを3.13に戻すことで元に戻せます。
rabbitmqctl enable_feature_flag all
rabbitmq-upgrade await_online_quorum_plus_one
rabbitmq-upgrade drainクラスターが再構築できる程度に小さく、定義のエクスポートが信頼でき、DNSやロードバランサーでクライアントを移せる余裕がある場合は、ブルーグリーンが代替手段になります。クリーンな4.xクラスターと、切り戻し先として無傷の3.13クラスターの両方が手に入ります。何年もかけて文書化されていないポリシーが積み重なったクラスターには、当社はこちらの方式をお勧めしています。
どちらの方式でも、サポートが15分のP1応答でアップグレードの作業時間をカバーします。これが最も重要になるのは、手順6から手順10の間です。
よくある質問
RabbitMQ 3.13から4.xへ直接アップグレードできますか?
はい。すべての安定版フィーチャーフラグが有効になっていること、クラシックキューのミラーリングポリシーが残っていないこと、ErlangがOTP 26以降であることを条件に、3.13.xから4.0.xへのローリングアップグレードがサポートされています。3.12以前を使っている場合は、4.xへ一気に飛ぶことはできません。まず3.13にアップグレードしてそのフィーチャーフラグを有効にし、それから先へ進んでください。4.xのノードは、3.13のフィーチャーフラグがすべて有効になっているクラスターにしか参加できず、それより古いシリーズではこの条件を満たせないためです。
RabbitMQ 3.xを使い続けることはできますか?
可能ですが、安全に使い続けられるのは、セキュリティ修正をバックポートするサポート契約がある場合に限られます。3.x向けのアップストリームのパッチは、3.13のコミュニティサポート期間の終了とともに提供されなくなるからです。当社の延長LTSサポートは、まさにこうした状況に向けて、3.8.xから3.13.xまでを対象にCVEパッチをバックポートします。クライアントの移行、コンプライアンス上の凍結期間、キューの変換に、アップストリームのスケジュールが許す以上の時間が必要な場合は、使い続けることに意味があります。ただし、恒久的な状態とすべきではありません。4.xへの移行は自社のスケジュールで計画してください。
RabbitMQを無停止でアップグレードするにはどうすればよいですか?
1台ずつノードを更新するローリングアップグレードです。すべてのフィーチャーフラグを有効にし、ミラーリングされたクラシックキューを削除し、定義をエクスポートします。そのうえで各ノードについてrabbitmq-upgrade await_online_quorum_plus_oneを実行し、ノードをドレインし、ErlangとRabbitMQをアップグレードして再起動し、クォーラムキューのメンバーが追いつくのを待ってから次のノードに進みます。接続が切れたときに再接続するクライアントであれば、短時間の再接続が発生するだけで、サービス停止にはなりません。既存のクラスターが複雑すぎてその場でアップグレードできない場合は、新しい4.xクラスターを用意してクライアントを切り替えるブルーグリーン方式が選択肢になります。
RabbitMQ 4にはErlang 26が必要ですか?
はい。RabbitMQ 4.xにはErlang/OTP 26以降が必要です。3.13のノードがすでにOTP 26で動いていれば、Erlangの作業は不要です。OTP 25の場合は、RabbitMQパッケージと同じローリングアップグレードの作業時間内に、各ノードのErlangをアップグレードしてください。4.xの後続リリースでは最小要件が引き上げられるため、インストールする4.xのパッチリリースに対応する互換性表を必ず確認してください。サポート期間への影響については、Erlang 26のサポート終了に関する記事で解説しています。