DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ

RabbitMQ接続障害の解決：ステップバイステップのトラブルシューティングガイド

タイムアウト、接続拒否、TLS問題、認証情報、vhost、制限に関する実践的なRabbitMQ接続トラブルシューティングチェックリスト。

RabbitMQ接続障害の解決：ステップバイステップのトラブルシューティングガイド

RabbitMQは堅牢で広く使われているメッセージブローカーですが、最も回復力のあるシステムでも時折接続性の問題が発生します。接続障害は開発者や運用チームが直面する最も一般的なハードルの一つであり、「接続が拒否されました」や「接続がタイムアウトしました」といった曖昧なエラーとして現れることがよくあります。

この包括的なガイドでは、これらの接続問題を診断し解決するための体系的なステップバイステップのアプローチを提供します。ネットワーク、サービスステータス、設定、認証レイヤーを系統的にチェックすることで、根本原因を効率的に特定し、クライアントアプリケーションとRabbitMQクラスター間の安定した通信を復元できます。

一般的なエラータイプの違いを理解することは効果的なトラブルシューティングの第一歩です。拒否された接続はサーバーがリクエストを積極的に拒否したことを意味し、タイムアウトはクライアントがサーバーに到達できなかったことを意味します。

1. 接続エラータイプの理解

手順に入る前に、クライアントエラーメッセージが障害ポイントについて何を示しているかを認識することが重要です。

接続タイムアウト

タイムアウトエラーは、クライアントアプリケーションがソケット接続を確立しようとしたが、指定された期間内に応答がなかった場合に発生します。これは通常、リクエストがRabbitMQアプリケーションレイヤーに到達する前にブロックが発生していることを示します。

考えられる原因： ネットワーク、DNS、ファイアウォールの問題。

接続拒否

接続拒否エラーは、サーバーがTCP接続要求を積極的に拒否した場合に発生します。これはリクエストがサーバーホストに到達したことを確認しますが、特定のポートが閉じているか、そのポートで実行されているサービスが接続試行を拒否したことを示します。

考えられる原因： サービスが実行されていない、ポートが間違っている、認証/アクセス制御の問題。

2. ステップバイステップのトラブルシューティングプロトコル

ネットワークレイヤー（ステップ2.1）から始めて、アプリケーションレイヤー（ステップ2.5）まで進みます。

2.1. ネットワーク到達可能性とDNSの確認

ここでの目標は、クライアントマシンがRabbitMQサーバーのIPアドレスと物理的に通信でき、ホスト名を正しく解決できることを確認することです。

  1. ホスト名解決の確認： クライアントがRabbitMQホスト名を正しいIPアドレスに解決することを確認します。

    ping rabbitmq.yourdomain.com

  2. 基本的なIP接続性： 単純な到達可能性を確認します。

    ping <RabbitMQ Server IP>

  3. ポートアクセシビリティ（重要なテスト）： telnetまたはnetcat (nc)を使用して、クライアントから特定のRabbitMQポート（デフォルトAMQPポート：5672）が開いていてリッスンしているかをテストします。

    # 成功した場合、画面が空白になるか、接続メッセージが表示されます。
# 失敗した場合、問題はネットワークまたはファイアウォールに関連している可能性があります。
telnet <RabbitMQ Server IP> 5672

トラブルシューティングのヒント：ファイアウォールのブロック

telnetテストが失敗したが、サーバーが実行中の場合（後で確認）、ファイアウォールが接続をブロックしている可能性があります。ローカルマシンのファイアウォール（iptables、firewalld）と外部セキュリティグループ（AWS、Azure、GCP）の両方を確認します。

2.2. RabbitMQサービスの健全性の確認

ネットワークレイヤーがクリアな場合、RabbitMQサービスがサーバー上でアクティブに実行されていることを確認します。

  1. サービスのステータス確認： ディストリビューションのサービス管理ツールを使用します。

    # Systemdシステムの場合
sudo systemctl status rabbitmq-server
# またはOSに応じて
sudo service rabbitmq-server status

    アクション： サービスが停止している場合、再起動します：sudo systemctl start rabbitmq-server。

  2. ノードステータスの確認： 管理CLIツールを使用して、実行中のノードの内部健全性を確認します。

    sudo rabbitmqctl status

    running_applicationsリストを確認して、必要なコンポーネントがアクティブであることを確認します。

  3. サーバーログの確認： 接続拒否はしばしばログに詳細なメッセージを残します。主要なログファイルを確認します（場所はインストールによって異なり、多くの場合/var/log/rabbitmq/）。 バインディング、ポート競合、起動時のクラッシュに関連するエラーを探します。

2.3. サーバー設定とリッスンポートの検証

サービスが実行中であっても、期待されるインターフェースやポートでリッスンしていない可能性があります。

  1. リッスンインターフェースの確認： RabbitMQは正しいネットワークインターフェースでリッスンするように設定されている必要があります。127.0.0.1（localhost）にのみバインドされている場合、リモートクライアントは接続できません。

  2. アクティブなポートの確認： RabbitMQサーバー上のシステムツールを使用して、プロセスが標準のAMQPポート（5672）および/またはTLSポート（使用する場合）にバインドされていることを確認します。

    # ssまたはnetstatを使用してリッスン中のTCPソケットをリスト
sudo ss -tulpn | grep 5672
# 期待される出力は、プロセスが0.0.0.0または正しいサーバーIPでリッスンしていることを示すはずです。

2.4. 認証と認可の失敗

クライアントがハンドシェイクを試みた直後に接続拒否が発生する場合、特にネットワーク接続が確認されている場合、問題はユーザー資格情報または権限である可能性があります。

一般的な認証問題

  1. 誤った資格情報： クライアントアプリケーションが使用するユーザー名とパスワードを再確認します。資格情報は大文字と小文字を区別します。
  2. ゲストユーザー制限： デフォルトのguestユーザーは通常、localhostからの接続のみに制限されています。クライアントがguestを使用してリモート接続している場合、拒否されます。
  3. VHost権限： 接続するユーザーは、アクセスしようとしている仮想ホスト（vhost）に対して適切な権限（configure、write、read）が設定されている必要があります。

認証のトラブルシューティング

rabbitmqctlツールを使用して、ユーザー設定と権限を確認します。

# すべてのユーザーをリスト
sudo rabbitmqctl list_users

# 特定のvhost（例：デフォルトの'/'）の権限を確認
sudo rabbitmqctl list_permissions -p /

# 例：新しいリモート対応ユーザーの作成（必要な場合）
# 1. ユーザーを追加
sudo rabbitmqctl add_user my_remote_app strongpassword
# 2. VHost '/'に権限を設定
sudo rabbitmqctl set_permissions -p / my_remote_app ".*" ".*" ".*"

⚠️ セキュリティのベストプラクティス

本番アプリケーションではデフォルトのguestユーザーに依存しないでください。各クライアントアプリケーションまたはマイクロサービスに対して、特定の制限された権限を持つ専用ユーザーを作成します。

2.5. クライアント側の環境と設定

問題が接続を試みるアプリケーション自体に完全にある場合もあります。

  1. 設定の確認： アプリケーションの設定ファイルまたは環境変数で、ホスト名、ポート番号、資格情報のタイポを確認します。
  2. クライアントライブラリのバージョン： クライアントライブラリ（例：PythonのPika、Node.jsのamqplib）が最新であり、RabbitMQサーバーバージョンと互換性があることを確認します。
  3. TLS/SSLの不一致： RabbitMQがTLSを要求するように設定されている場合、クライアントはSSL/TLSを使用し、正しい証明書を提供するように設定されている必要があります。クライアントがTLS専用ポートに対してプレーンなAMQP接続を試みると、接続は失敗します。
  4. 接続プーリング/スロットリング： 断続的な障害が発生している場合、クライアントアプリケーションが急速に接続を開閉していないか確認します。これにより、OSのファイル記述子制限やブローカーが設定した接続制限に達する可能性があります。

3. 高度な診断ツール

持続的な問題には、管理プラグインとネットワークパケット検査を活用します。

RabbitMQ管理プラグイン（ポート15672）

管理インターフェースにアクセスできる場合（ブラウザ経由）、ブローカーのステータス、開いているポート、リアルタイムのログ情報を確認でき、CLIでは得られない手がかりを提供することがよくあります。

ネットワークトレース（Wireshark/tcpdump）

複雑なネットワーク問題の場合、クライアントまたはサーバーマシンでパケットアナライザーを使用して、接続試行がどこで失敗しているかを正確に確認します。

  • クライアントがSYNパケットを送信し、何も返ってこない場合、ファイアウォールが問題です。
  • クライアントがSYNパケットを送信し、RST/ACKパケットを受信した場合、サーバーが積極的に接続を拒否しています（おそらくサービスまたはバインディング）。
# 例：サーバー側でポート5672を監視するためにtcpdumpを実行
sudo tcpdump -i eth0 port 5672 -nn

クライアントエラーをより注意深く読む

クライアントライブラリは、RabbitMQ接続障害をすべて同じように表現するわけではありません。JavaクライアントはAuthenticationFailureExceptionを報告する場合があります。Pikaを使用するPythonサービスはAMQPConnectionErrorまたはProbableAuthenticationErrorを表示する場合があります。Node.jsサービスはソケットが閉じたことだけをログに記録する場合があります。ブローカー設定を変更する前に、正確なエラー、タイムスタンプ、ターゲットホスト、ターゲットポート、および障害がAMQPハンドシェイクの前か後かをキャプチャします。

そのタイミングが重要です。

ソケットがまったく開けない場合、まだDNS、ルーティング、ファイアウォール、リスナー、またはポートの領域にいます。TCP接続が開き、AMQPネゴシエーション中に閉じる場合、TLS、プロトコルバージョン、資格情報、vhost権限、またはブローカー側の接続制限を調べます。接続が成功し、数分後に切断される場合、ハートビート、ロードバランサー、NATタイムアウト、クライアント接続の変動、およびリソースアラームを調査します。

私は通常、最初にこれら4つの事実を尋ねます：

クライアントホスト：
ブローカーホスト：
ポート：
正確なエラーとタイムスタンプ：

次に、タイムスタンプをRabbitMQログと照合します。ブローカーログにエントリがまったくない場合、接続試行はおそらくRabbitMQに到達していません。ブローカーログに認証またはvhostエラーが記録されている場合、ネットワークはすでに証明されており、問題はより上位のスタックにあります。

高速な決定木

本番環境がダウンしている場合、この順序を使用します。レイヤー間を行き来するのを避けます。

  1. クライアントからブローカーホスト名を解決します。
  2. クライアントからTCPポートを開きます。
  3. RabbitMQがそのポートとインターフェースでリッスンしていることを確認します。
  4. 同じタイムスタンプでRabbitMQログを確認します。
  5. TLSが関係する場合、TLSモードと証明書を検証します。
  6. ユーザー名、パスワード、vhost、および権限を検証します。
  7. 接続制限、ファイル記述子、メモリアラーム、ディスクアラームを確認します。
  8. ロードバランサー、プロキシ、Kubernetesサービス、またはセキュリティグループを確認します。

例：

getent hosts rabbitmq.internal
nc -vz rabbitmq.internal 5672
nc -vz rabbitmq.internal 5671

可能な場合はtelnetの代わりにncを使用します。これは多くのサーバーイメージにインストールされており、スクリプト用によりクリーンな終了コードを提供するためです。TCP接続が成功しても、認証が機能することを証明するものではありません。それは、クライアントがそのポートでリッスンしている何かに到達できることだけを証明します。

ブローカー上：

sudo ss -ltnp | grep -E '5671|5672|15672'
sudo rabbitmq-diagnostics listeners
sudo rabbitmq-diagnostics status

rabbitmq-diagnostics listenersは特に便利です。RabbitMQが開いたと認識しているリスナーを表示するためです。ssとRabbitMQが一致しない場合、コンテナ、名前空間、または間違ったホストの問題を見ている可能性があります。

ローカルホストバインディングとコンテナの驚き

よくある接続障害の一つは、ローカルテストが成功した後に発生します。誰かがブローカーマシンからlocalhost:5672でRabbitMQを確認し、別のホストにアプリをデプロイすると、アプリが拒否されます。

ブローカーがループバックのみでリッスンしている可能性があります。サーバー自体からは問題なく見えますが、別のマシンからは到達できません。

次のような出力を確認します：

sudo ss -ltnp | grep 5672

127.0.0.1:5672が表示される場合、リモートクライアントは使用できません。通常、ネットワーク設計に応じて、RabbitMQをサーバーアドレスまたはすべてのインターフェースにバインドする必要があります。AMQPをインターネットに広く公開しないでください。プライベートインターフェースにバインドし、ファイアウォールルールまたはセキュリティグループを使用して接続できるクライアントを制限します。

コンテナは別のレイヤーを追加します。RabbitMQはコンテナ内でリッスンしているかもしれませんが、ホストポートが公開されていない可能性があります。Dockerでは、次を確認します：

docker ps
docker port <rabbitmq-container>

Kubernetesでは、サービスのセレクター、エンドポイント、ターゲットポート、およびポッドの readiness を確認します：

kubectl get svc,endpoints -n messaging
kubectl describe svc rabbitmq -n messaging
kubectl get pods -n messaging -o wide

サービスにエンドポイントがない場合、RabbitMQは単独では正常でも、サービスによって選択されていない可能性があります。これは多くの場合、ラベルの不一致または readiness プローブの失敗から発生します。

TLSの不一致は接続問題のように見える

TLSの失敗は、ランダムなRabbitMQの不安定性として誤読されることがよくあります。最も基本的な間違いは、TLSポートにプレーンAMQPで接続するか、プレーンAMQPポートにTLSで接続することです。標準AMQPは通常5672にあり、AMQPSは通常5671にありますが、環境によって異なる場合があります。

クライアントマシンから、TLSリスナーを直接テストします：

openssl s_client -connect rabbitmq.internal:5671 -servername rabbitmq.internal

証明書の検証エラー、ホスト名の不一致、期限切れの証明書、または不足している中間証明書を探します。証明書の共通名またはサブジェクト代替名がクライアントが使用するホスト名と一致しない場合、より厳格なクライアントは接続を拒否します。

また、ブローカーがクライアント証明書を要求しているかどうかを確認します。相互TLSが有効な場合、サーバー証明書のみを信頼するクライアントは、自身の証明書を提示しなかったために失敗する可能性があります。

アプリケーション設定では、ssl=trueのような漠然とした設定を避け、それらが何をするかを理解してください。CAファイル、クライアント証明書、クライアントキー、サーバー名検証、およびポートを確認します。openssl s_clientテストが成功しても完全なAMQPテストではありませんが、証明書の問題をRabbitMQユーザーの問題から迅速に分離します。

認証はパスワードだけではない

RabbitMQ認証にはいくつかの要素があります：

  • ユーザー名が存在すること。
  • パスワードが正しいこと。
  • 制限が適用されている場合、ユーザーがその場所から接続を許可されていること。
  • 要求された仮想ホストが存在すること。
  • ユーザーがその仮想ホストに対する権限を持っていること。

デフォルトのguestユーザーは、典型的なRabbitMQインストールではlocalhostに制限されています。これは意図的な安全上のデフォルトです。リモートアプリがguestを使用する場合、デフォルトアカウントを弱める代わりに専用ユーザーを作成します。

便利なチェック：

sudo rabbitmqctl list_users
sudo rabbitmqctl list_vhosts
sudo rabbitmqctl list_permissions -p /
sudo rabbitmqctl authenticate_user app_user 'the-password'

権限は、configure、write、read操作の正規表現です。ユーザーは認証できても、チャネルを開いたりキューを宣言したりするときに失敗する場合があります。単純なアプリケーションvhostの場合、次のように権限を付与するかもしれません：

sudo rabbitmqctl add_vhost app_prod
sudo rabbitmqctl add_user app_service 'use-a-secret-manager'
sudo rabbitmqctl set_permissions -p app_prod app_service '^app\.' '^app\.' '^app\.'

この例では、app.で始まるリソースのみを許可します。多くのチュートリアルでは便利さからすべてに.*を使用しますが、本番環境の権限は通常、より狭くする必要があります。

時々動作する場合

断続的な接続障害には異なる考え方が必要です。ほとんどの接続が機能するが一部が失敗する場合、制限と中間ボックスを探します。

RabbitMQはファイル記述子を使い果たす可能性があります。オペレーティングシステムは一時ポートを使い果たす可能性があります。クライアントが多すぎる短命な接続を作成する可能性があります。ロードバランサーは、ハートビート設定がロードバランサーのタイムアウトより長い場合、アイドル接続を閉じる可能性があります。

ブローカー側のカウントを確認します：

sudo rabbitmqctl list_connections name peer_host peer_port state channels recv_cnt send_cnt
sudo rabbitmqctl list_channels connection number user vhost
sudo rabbitmq-diagnostics status

同じアプリから数千の接続が表示される場合、アプリはメッセージごとまたはWebリクエストごとに接続を開いている可能性があります。RabbitMQ接続は長期間存続することを意図しています。プロセスごとに1つの接続または小さなプールを使用し、クライアントライブラリの推奨に従って同時作業用にチャネルを作成します。

ハートビートも静かな原因です。クライアントのイベントループがブロックされている場合、ハートビートを見逃し、RabbitMQが接続を閉じる可能性があります。プロキシがアイドルTCP接続を60秒後に静かに切断し、RabbitMQのハートビートがはるかに長い場合、クライアントは公開しようとしたときにのみ切断された接続を発見する可能性があります。ハートビートとロードバランサーのアイドルタイムアウト設定を調整して、障害が迅速かつ意図的に検出されるようにします。

エスカレーション前にキャプチャすべきもの

簡単なチェックで解決しない場合、次の人が推測せずに助けられるように十分な証拠を収集します：

date -u
hostname -f
getent hosts rabbitmq.internal
nc -vz rabbitmq.internal 5672
nc -vz rabbitmq.internal 5671
sudo rabbitmq-diagnostics listeners
sudo rabbitmq-diagnostics status
sudo rabbitmqctl list_connections name user vhost peer_host state

シークレットを削除したアプリケーション接続文字列、クライアントライブラリ名とバージョン、RabbitMQバージョン、および両側の正確なログ行を追加します。ほとんどの難しい接続ケースは、クライアントとブローカーのタイムスタンプが一致すると簡単になります。

最終確認

RabbitMQ接続障害を階層化された問題として扱います。最初にDNS、次にTCP到達可能性、次にブローカーリスナー、次にTLS、最後に資格情報とvhost権限を証明します。タイムアウトは通常、リクエストがターゲットパスから有用な応答を得られていないことを意味します。接続拒否は通常、何かが応答したが、期待されるリスナーまたはアクセスパスが間違っていることを意味します。これら2つのケースを分離しておけば、ほとんどのインシデントをはるかに迅速に絞り込むことができます。