DevOpsナレッジハブ
DevOpsナレッジハブ

Jenkinsの接続性の問題の診断：ネットワークおよびエージェントの問題

重要な接続トラブルシューティングの手順を習得し、Jenkins環境を復旧させましょう。このガイドは、Master-Agent間の通信に関する問題の診断と解決に焦点を当てており、ファイアウォールの設定、JNLPポートの設定、SSH認証の失敗など、重要なネットワーク側面を網羅しています。`telnet`のようなツールを使用して到達可能性を確認する方法を学び、一般的な環境の落とし穴を理解することで、Jenkinsエージェントをオンラインに保ち、CI/CDパイプラインがスムーズに実行されるようにします。

39 ビュー

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

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

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

1. Jenkins マスター・エージェント通信の理解

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

1.1 Java Network Launch Protocol (JNLP)

JNLP モデルでは、Jenkins エージェントがマスターへの接続を開始します。これは推奨される最も一般的なアプローチです。エージェントはマスター上の特定のポート（JNLP エージェントポート）に接続します。

  • 方向: エージェントがマスターに接続します。
  • 必要なポート: マスターの JNLP ポート（デフォルトは 50000、または動的に割り当てられる場合が多い）。

1.2 Secure Shell (SSH)

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

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

2. 初期ネットワークおよびファイアウォール診断

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

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

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

接続タイプ 送信元 宛先 必要なポート ステータスチェック
Web インターフェイス ユーザー/エージェント マスター 8080（またはカスタム） ブラウザアクセス
JNLP (エージェント → マスター) エージェント マスター 50000（またはカスタム） telnet または nc
SSH (マスター → エージェント) マスター エージェント 22（またはカスタム） ssh または telnet

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

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

JNLP 到達可能性チェック（エージェントからマスターへ）

# <MASTER_IP> および <JNLP_PORT> を置き換えてください
telnet <MASTER_IP> 50000

# 期待される成功出力:
# Connected to <MASTER_IP>.
# Escape character is '^]'.

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

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

2.3 固定 JNLP ポートの設定

JNLP を使用している場合、あいまいさを避け、ファイアウォールルールを簡素化するために、固定ポートを設定することをお勧めします。デフォルトでは、Jenkins は動的ポート範囲を使用する可能性があり、これはセキュリティ設定を複雑にします。

  1. Jenkins の管理 > ノードとクラウドの管理 > グローバルセキュリティの設定 に移動します。
  2. エージェントの下にある、インバウンドエージェント用の TCP ポートオプションを見つけます。
  3. 固定を選択し、ポート（例：50000）を指定します。
  4. このポートが、マスターマシン上のホストオペレーティングシステムファイアウォール（例：iptables、firewalld、または Windows ファイアウォール）で開かれていることを確認します。

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

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

3.1 マスター上のエージェントログの確認

JNLP エージェントの起動を試みる際に、Jenkins 自体が提供するログを確認します。特定のエージェント設定ページに移動し、ログセクションを表示します。これには、最も明確なエラーメッセージが表示されることがよくあります。

  • 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 がリバースプロキシの後ろにある場合は、マスター設定が外部 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 Credentials Manager に保存されている秘密キーに対応する公開キーが、エージェントユーザーの ~/.ssh/authorized_keys ファイルに正しく追加されていることを確認します。
  2. パスワード: パスワードを使用している場合、エージェント上の SSH サーバーがパスワード認証を許可するように設定されていることを確認します（セキュリティ上推奨されません）。

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

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

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

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

5.1 Java 環境（重要）

Jenkins エージェントは、agent.jar ファイルを実行するために互換性のある Java Runtime Environment（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 ハンドシェイクの失敗を引き起こし、接続の切断または拒否につながる可能性があります。両方のマシンが Network Time Protocol（NTP）を介して同期されていることを確認します。

まとめと次のステップ

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

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

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

すべての接続試行が失敗した場合は、システムログ（マスター上の /var/log/jenkins/jenkins.log）を確認して、根本的な設定問題を示す可能性のある詳細な Java スタックトレースを確認してください。