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

Jenkins接続問題の診断：ネットワークとエージェントの問題

ポート、ファイアウォール、インバウンドエージェント、SSH、Java、ログを確認して、Jenkinsコントローラーとエージェントの接続をトラブルシューティングします。

Jenkins接続問題の診断：ネットワークとエージェントの問題

Jenkinsは、中央コントローラーとその実行環境（エージェントまたはノード）間の堅牢な通信に大きく依存しています。この接続が失敗すると、ビルドが停止し、パイプラインが中断され、継続的インテグレーションが停止します。これらの問題を診断するには、体系的なアプローチが必要であり、多くの場合、最初にネットワークトポロジーに焦点を当て、次にエージェントの構成とプロトコルの失敗に焦点を当てます。

この包括的なガイドでは、厄介なファイアウォールの問題、誤って構成されたJNLPポート、エージェントの起動失敗など、最も一般的なJenkins接続問題をトラブルシューティングするためのステップバイステップの手順を提供し、安定した運用と信頼性の高いCI/CDパイプラインを迅速に復元するのに役立ちます。

1. Jenkinsコントローラーとエージェントの通信を理解する

トラブルシューティングの前に、Jenkinsコントローラーがエージェントとどのように通信するかを理解することが不可欠です。Jenkinsは2つの主要な方法を提供し、それぞれに固有の診断要件があります。

1.1 Javaネットワーク起動プロトコル（JNLP）

JNLPモデルでは、Jenkinsエージェントがコントローラーへの接続を開始します。これは推奨される最も一般的なアプローチです。エージェントはコントローラーの特定のポートに接続します。このポートは現在、インバウンドエージェントTCPポートと呼ばれています。

  • 方向： エージェントがコントローラーに接続します。
  • 必要なポート： コントローラーのインバウンドエージェントTCPポート（デフォルトは多くの場合50000、または動的に割り当てられます）。

1.2 セキュアシェル（SSH）

SSHモデルでは、Jenkinsコントローラーがエージェントへの接続を開始します。これには、エージェントマシンでSSHサーバーが実行されている必要があります。

  • 方向： コントローラーがエージェントに接続します。
  • 必要なポート： エージェントのSSHポート（通常は22）。
  • 要件： SSH認証情報（キーまたはパスワード）がJenkinsで正しく構成されている必要があります。

2. 初期のネットワークとファイアウォールの診断

ネットワークの問題、特にファイアウォールの制限は、接続問題の最も頻繁な原因です。エージェントが突然オフラインになったり、新しいエージェントの接続に失敗した場合は、ここから始めてください。

2.1 必要なポートが開いていることを確認する

通信モデルに基づいて、必要なポートでトラフィックが流れることができることを確認する必要があります。

接続タイプ 送信元 宛先 必要なポート ステータス確認
Webインターフェース ユーザー/エージェント コントローラー 8080（またはカスタム） ブラウザアクセス
インバウンドエージェント エージェント コントローラー 50000（またはカスタム） telnet または nc
SSH（コントローラー -> エージェント） コントローラー エージェント 22（またはカスタム） ssh または telnet

2.2 Telnet/Netcatを使用した到達可能性テスト

接続元のマシンから宛先マシンに対して、必要なポートでtelnetまたはnc（Netcat）を使用します。接続が成功すると、ネットワークの到達可能性が確認され、ローカルファイアウォールがポートをブロックしていないことが確認されます。

インバウンドエージェントの到達可能性チェック（エージェントからコントローラーへ）

# <CONTROLLER_IP>と<JNLP_PORT>を置き換えてください
telnet <CONTROLLER_IP> 50000

# 成功時の期待される出力：
# Connected to <CONTROLLER_IP>.
# Escape character is '^]'.

# 失敗時の期待される出力：
# Trying <CONTROLLER_IP>...
# telnet: connect to address <CONTROLLER_IP>: Connection refused

ヒント： 「Connection Refused」エラーは、ネットワークパスは開いているが、サービス（Jenkins）がそのポートでリッスンしていないか、コントローラーのローカルファイアウォールがブロックしていることを示します。接続がタイムアウトした場合、マシン間のファイアウォールが原因である可能性が高いです。

2.3 固定JNLPポートを設定する

JNLPを使用している場合、あいまいさを避け、ファイアウォールルールを簡素化するために、固定ポートを構成することをお勧めします。固定ポートを設定しない限り、Jenkinsはランダムなインバウンドエージェントポートを使用する可能性があり、セキュリティ設定が複雑になります。

  1. Manage Jenkins > Security（または古いJenkinsバージョンではConfigure Global Security）に移動します。
  2. Agentsの下で、TCP port for inbound agentsのオプションを見つけます。
  3. Fixedを選択し、ポート（例：50000）を指定します。
  4. このポートがコントローラーマシンのホストオペレーティングシステムファイアウォール（例：iptables、firewalld、またはWindowsファイアウォール）で開かれていることを確認します。

3. JNLPエージェントの問題のトラブルシューティング

ネットワークチェックが合格した場合、問題は通常、認証、構成、または環境の不一致に関連しています。

3.1 コントローラーでエージェントログを確認する

JNLPエージェントを起動しようとするときは、Jenkins自体が提供するログを確認してください。特定のエージェント構成ページに移動し、Logセクションを表示します。これにより、最も明確なエラーメッセージが得られることがよくあります。

  • java.net.ConnectExceptionやhudson.remoting.ChannelClosedExceptionなどの一般的なエラーを探します。

3.2 エージェント引数が正しいことを確認する

Jenkinsが提供するコマンド（java -jar agent.jar ...コマンド）を使用してエージェントを手動で起動する場合は、パラメータが正しいことを確認してください。

# JNLP起動のコマンド構造例
java -jar agent.jar -jnlpUrl http://<JENKINS_URL>/computer/<AGENT_NAME>/slave-agent.jnlp -secret <SECRET_TOKEN> -workDir "/path/to/workspace"
  • JNLP URLを確認する： URLが正しいコントローラーのホスト名とポートを使用していることを確認してください。Jenkinsがリバースプロキシの背後にある場合は、Jenkins URL構成が外部URLを反映していることを確認してください。
  • シークレットトークンを確認する： ノードが再構成されると、トークンは期限切れになるか変更されます。最新の.jarをダウンロードし、エージェントの起動ページで提供されている最新のシークレットを使用してください。

4. SSHエージェントの問題のトラブルシューティング

SSHを使用してエージェントを起動している場合、接続障害は通常、認証またはシェル環境の問題に起因します。

4.1 Jenkins外部でSSH接続を確認する

Jenkinsで構成されているものと同じユーザー名と認証情報を使用して、コントローラーからエージェントマシンへの接続を試みます。

ssh -i /path/to/keyfile jenkins_user@<AGENT_IP>
  • これが失敗した場合、問題は環境にあります。SSHサービスがダウンしているか、ユーザー認証情報/キーが間違っているか、キーのパーミッションが緩すぎる（chmod 600 keyfile.pem）かのいずれかです。

4.2 SSH認証方法を確認する

  1. キー： Jenkins認証情報マネージャーに保存されている秘密キーに対応する公開キーが、エージェントユーザーの~/.ssh/authorized_keysファイルに正しく追加されていることを確認してください。
  2. パスワード： パスワードを使用している場合は、エージェントのSSHサーバーがパスワード認証を許可するように構成されていることを確認してください（セキュリティ上推奨されません）。

4.3 SSHエージェント起動タイムアウト

SSH接続は成功したがエージェントの起動に失敗した場合、Jenkinsが初期化スクリプトの実行を試みている間にタイムアウトしている可能性があります。エージェント構成ページでSSH接続タイムアウト設定を増やしてください。

5. 一般的なエージェント環境の障害

ネットワーク接続が確立された後でも、エージェントのオペレーティング環境が正しくない場合、エージェントは失敗する可能性があります。

5.1 Java環境（重要）

Jenkinsエージェントは、agent.jarファイルを実行するために互換性のあるJavaランタイム環境（JRE/JDK）を必要とします。

  • Javaの存在を確認する： エージェントマシンでjava -versionを実行します。
  • JAVA_HOMEを確認する： Jenkinsエージェント構成のJAVA_HOMEまたはPath to JDK変数が、エージェントマシン上の有効なJavaインストールディレクトリを指していることを確認してください。

5.2 ワークスペースとユーザー権限

Jenkinsがエージェントの実行に使用するユーザーアカウント（SSHログインまたはシステムサービス経由）には、定義されたリモートルートディレクトリ（ワークスペース）に対する読み取りおよび書き込み権限が必要です。

  • アクション： リモートルートディレクトリ（例：/home/jenkins/workspace）の所有権と権限を確認します。

5.3 時刻同期

まれですが、コントローラーとエージェントマシン間の大幅な時刻のずれは、SSL/TLSハンドシェイクの失敗を引き起こし、接続の切断や拒否につながる可能性があります。両方のマシンがネットワークタイムプロトコル（NTP）を介して同期されていることを確認してください。

要点とチェックリスト

Jenkinsの接続トラブルシューティングは、ネットワークの境界から内側に向かって、除外のプロセスです。ファイアウォールを体系的にチェックし、telnetなどのツールを使用してポートの到達可能性を確認し、通信プロトコル（JNLPまたはSSH）が正しく認証および構成されていることを確認することで、接続の問題を迅速に特定して解決できます。

トラブルシューティングチェックリスト：

  1. ネットワークファイアウォール： 必要なポート（JNLPの場合は50000+、SSHの場合は22）で双方向のトラフィックが許可されていますか？
  2. ローカルファイアウォール： コントローラー/エージェントで実行されているOSファイアウォール（Windows/Linux）がポートをブロックしていますか？
  3. プロトコルテスト： 接続元マシンから宛先の関連ポートへのtelnetは成功しますか？
  4. Java： 互換性のあるJavaバージョンがエージェントにインストールされており、パスは正しいですか？
  5. 認証： SSHキー/パスワードは有効ですか、またはJNLPシークレットトークンは最新ですか？

すべての接続試行が失敗した場合は、Jenkinsコントローラーのログ（多くの場合、サービスジャーナルまたは/var/log/jenkins/jenkins.logから入手可能）を確認し、リモーティングとJavaのスタックトレースを調べてください。