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

Jenkinsエージェントの一般的な接続問題と解決策のトラブルシューティング

Jenkinsエージェントで「オフライン」や「接続拒否」の問題に遭遇していませんか？この包括的なガイドでは、一般的な接続問題に対する段階的な解決策を提供します。ネットワーク、ファイアウォール、JNLP、SSH、およびエージェント設定の問題をトラブルシューティングする方法を学び、Jenkinsビルドエグゼキュータが常に利用可能で効率的に稼働するようにします。迅速な解決のための実践的なヒントとログ分析も含まれています。

29 ビュー

Jenkinsエージェント接続問題のトラブルシューティングと解決策

Jenkinsエージェント（ノードまたはエグゼキュータとも呼ばれます）は、ビルドジョブを実行するCI/CDパイプラインの重要なコンポーネントです。エージェントがオフラインになったり、接続に失敗したりすると、自動化ワークフロー全体が停止する可能性があります。このガイドでは、最も一般的な接続問題を診断および解決し、Jenkinsインフラストラクチャが堅牢であり続け、ビルドジョブが中断なく実行されるようにする方法を説明します。

エージェントが到達不能になる理由を理解することは、効果的なトラブルシューティングの最初のステップです。これらの問題は、ネットワーク構成ミス、エージェント設定の誤り、ファイアウォール制限、またはJenkinsコントローラー自体の問題に起因する可能性があります。これらの領域を体系的にチェックすることで、根本原因を迅速に特定し、解決策を実装できます。

Jenkinsエージェント切断の一般的な原因

いくつかの要因により、エージェントがオフラインになる可能性があります。特定の問題を特定することが、潜在的な原因を絞り込む鍵となります。

  • エージェントが到達不能: Jenkinsコントローラーがエージェントへの接続を確立できません。
  • 接続拒否: エージェントマシンが、コントローラーからの接続試行を積極的に拒否します。
  • 接続成功後にエージェントがオフラインと報告: エージェントは接続されていましたが、その後接続が切断されました。
  • JSchエラー（SSHベースのエージェントの場合）: SSH接続に使用されるJava Secure Channelライブラリに関連する特定のエラー。

ネットワークとファイアウォールに関する問題

ネットワーク接続は、エージェント接続問題の最も頻繁な原因です。Jenkinsコントローラーがエージェントマシンに到達でき、その逆も同様であることを確認することが不可欠です。

ネットワーク到達可能性の検証

Jenkins固有の設定に入る前に、基本的なネットワーク接続を確認してください。

  1. エージェントへのPing: Jenkinsコントローラーマシンから、エージェントマシンのIPアドレスまたはホスト名をpingします。
    bash ping <agent-hostname-or-ip>
  2. エージェントポートへのTelnet: Jenkinsがエージェントに接続するために使用するポートが開いており、リッスンしているかテストします。JNLPエージェントの場合、通常はポート50000です。SSHエージェントの場合、SSHポート（デフォルト22）です。
    bash telnet <agent-hostname-or-ip> <agent-port>
    接続がタイムアウトしたり拒否されたりする場合は、ポートをブロックしているネットワークまたはファイアウォール問題の可能性があります。

ファイアウォール設定

Jenkinsコントローラー、エージェントマシン、または中間ネットワークデバイスのいずれかのファイアウォールが、必要なポートをブロックする可能性があります。

  • Jenkinsコントローラーファイアウォール: コントローラーがエージェントのポートへの接続を開始できることを確認してください。
  • エージェントマシンファイアウォール: エージェントマシンのファイアウォール（例：ufw、firewalld、Windowsファイアウォール）が、JenkinsコントローラーのIPアドレスからのエージェントのポートへの着信接続を許可していることを確認してください。
  • ネットワークファイアウォール: ネットワークに内部ファイアウォールがある場合は、コントローラーとエージェント間のトラフィックが許可されていることを確認してください。

例：エージェント（ufwを使用するLinux）でポート50000を許可する

# 特定のIP（Jenkinsコントローラー）からの接続を許可する
sudo ufw allow from <jenkins-controller-ip> to any port 50000

# または任意のIPから許可する（セキュリティが低い）
sudo ufw allow 50000

# ファイアウォールルールをリロードする
sudo ufw reload

例：エージェント（firewalldを使用するLinux）でポート22を許可する

# 特定のソースIPからSSHサービスを永続的に許可する
sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="<jenkins-controller-ip>" port protocol="tcp" port="22" accept'

# ファイアウォールルールをリロードする
sudo firewall-cmd --reload

ヒント: セキュリティ向上のため、常に特定のIPアドレスからの接続を許可することを優先してください。

Jenkinsエージェント設定の問題

Jenkins内またはエージェント自体の設定ミスは、接続問題の一般的な原因です。

JNLPエージェント設定

Java Network Launch Protocol（JNLP）エージェントは、専用ポートを使用してJenkinsコントローラーと通信します。主な設定は、エージェントの起動方法とコントローラーの利用可能なポートに関係します。

Jenkins UIでエージェントがオフライン

Jenkins UIでエージェントがオフラインとして表示される場合、コントローラーが接続を確立または維持できなかったことを意味します。

  1. エージェント起動方法を確認する: エージェントが正しく起動するように構成されていることを確認します。一般的な方法には以下があります。
    • マスターに接続してエージェントを起動: これにはエージェント側からの手動起動が必要です。
    • SSH経由でエージェントを起動: SSH認証情報とホスト設定を通じて構成されます。
    • 組み込みノードプロパティを使用してエージェントを起動: 特定のシナリオ向け。
  2. JNLPポートの可用性を検証する: Jenkinsコントローラーは、構成されたJNLPポート（デフォルト50000）でリッスンする必要があります。Manage Jenkins -> System -> Advanced -> File -> TCP port for JNLP agents に移動し、設定されていてアクセス可能であることを確認してください。

JNLPエージェント起動時に「接続拒否」

これは、JenkinsコントローラーのJNLPポート（デフォルト50000）が開いていないか、エージェントマシンからアクセスできないことを意味することがよくあります。コントローラーのファイアウォールルールを確認し、ポートが正しく構成されていることを確認してください。

ヒント: Jenkinsコントローラーを再起動すると、一時的なJNLPポートの問題が解決することがあります。

SSHエージェント設定

SSHを使用してエージェントに接続する場合、いくつかの要因が問題を引き起こす可能性があります。

  1. SSH認証情報の誤り: SSH接続のためにJenkinsで構成されたユーザー名、パスワード、または秘密鍵を確認してください。秘密鍵が正しくフォーマットされている（例：PEM形式）こと、および正しい権限があることを確認してください。
  2. エージェントでSSHサーバーが実行されていない: エージェントマシンでSSHデーモン（sshd）が実行されていることを確認してください。
    bash # エージェントマシンで sudo systemctl status sshd # または sudo service ssh status
    実行されていない場合は、起動してください。
    bash sudo systemctl start sshd sudo systemctl enable sshd
  3. SSHポートの不一致: JenkinsでSSH用に構成されたポートが、SSHサーバーがリッスンしているポート（デフォルト22）と一致していることを確認してください。
  4. エージェントホスト名/IP解決: Jenkinsコントローラーは、エージェントのホスト名またはIPアドレスを解決できる必要があります。
  5. SSHキーの権限: エージェントマシンでは、Jenkinsが接続するユーザーの~/.ssh/authorized_keysファイルに正しい権限（通常は600）が必要です。

例：SSH接続を手動でテストする

Jenkinsコントローラーマシンから、Jenkinsで構成されたのと同じ認証情報とポートを使用してエージェントにSSHしてみます。

ssh -p <ssh-port> <jenkins-user>@<agent-hostname-or-ip>

この手動SSHコマンドが失敗した場合、問題はJenkinsのSSH設定の外、おそらくエージェントのネットワーク、ファイアウォール、またはSSHサーバー設定にあります。

エージェント作業ディレクトリの権限

Jenkinsは、エージェントのファイルシステムで操作するために特定の権限を必要とします。Jenkinsがエージェントに接続するために使用するユーザー（またはエージェントプロセスを実行するユーザー）は、エージェントの構成済み作業ディレクトリへの書き込み権限が必要です。

  • 所有者と権限を確認する: エージェントで、Jenkinsホームディレクトリとそのサブディレクトリの所有権と権限を確認します。
    bash ls -ld /path/to/jenkins/agent/home ls -l /path/to/jenkins/agent/home
  • 権限を付与する（必要な場合）: Jenkinsが接続するユーザーが読み取りおよび書き込みアクセス権を持っていることを確認します。chownとchmodは注意して使用してください。

Jenkinsコントローラーの問題

問題がエージェントではなく、Jenkinsコントローラー自体にある場合があります。

コントローラーの過負荷

Jenkinsコントローラーが過負荷状態（多数のジョブ実行中、CPU/メモリ使用率が高い）の場合、エージェント接続の管理に苦労する可能性があります。コントローラーのリソース使用状況を監視してください。

JNLPポートの競合

JenkinsコントローラーのJNLPポート（デフォルト50000）が別のプロセスによって既に使用されている場合、エージェントは接続に失敗します。

  • ポート使用状況を確認する: コントローラーマシンで、netstatまたはssを使用して、どのプロセスがポートを使用しているかを確認します。
    bash sudo netstat -tulnp | grep 50000 # または sudo ss -tulnp | grep 50000
    別のプロセスが使用している場合は、Jenkinsまたは他のアプリケーションのいずれかを再構成して、異なるポートを使用する必要があります。

詳細トラブルシューティングとログ

標準的なチェックで問題が解決しない場合は、より詳細な調査が必要です。

Jenkinsコントローラーログ

エージェント接続に関連するエラーについて、Jenkinsコントローラーログを確認してください。これらのログには特定のエラーメッセージが含まれる場合があります。

  • 場所: 通常、$JENKINS_HOME/jenkins.logにあります。または、Manage Jenkins -> System Logからアクセスできます。
  • 確認すべきこと: エージェントのホスト名、IPアドレス、接続試行、JSch例外、またはConnection refusedエラーに言及しているメッセージ。

エージェントログ

エージェントが実行されているがオフラインと報告されている場合は、エラーがないかエージェントログを確認してください。

  • JNLPエージェント: エージェントプロセス自体が、コンソールまたは指定されたログファイルに出力する場合があります。
  • SSHエージェント: ログは、エージェントマシンの$JENKINS_HOME/agent.logにあるか、SSHレベルで接続が失敗した場合はsshdに関連している可能性があります。

デバッグログの有効化

非常にしつこい問題の場合は、関連するJenkinsコンポーネントのデバッグログを一時的に有効にすると、より詳細な情報が得られる場合があります。

  • JNLP/エージェント通信: Javaシステムプロパティを調整するか、Jenkinsのログ構成（Manage Jenkins -> System Log -> Log Recorders）を使用して、hudson.slavesまたは関連パッケージの詳細度を上げる必要がある場合があります。

まとめとベストプラクティス

Jenkinsエージェント接続のトラブルシューティングには、基本的なネットワークチェックから始め、Jenkins固有の設定に進む体系的なアプローチが必要です。

  • ネットワークの検証: 基本的なネットワーク到達可能性とポートアクセスを確保するために、常にpingとtelnet/ncから始めてください。
  • ファイアウォールの確認: コントローラーとエージェントの両方、およびネットワークファイアウォールで、必要なポートのトラフィックが許可されていることを確認してください。
  • 認証情報の検証: SSHキー、ユーザー名、パスワードを再確認してください。
  • エージェントサービスの確認: SSHエージェントの場合は、sshdが実行されていてアクセス可能であることを確認してください。
  • Jenkinsログの監視: コントローラーログは、接続失敗を理解するための主要な情報源です。
  • 特定IPの使用: 可能であれば、広範な範囲や0.0.0.0ではなく、特定のIPアドレスを使用するようにファイアウォールとJenkinsを構成してください。

これらの手順に従うことで、ほとんどの一般的なJenkinsエージェント接続問題を効果的に診断および解決し、CI/CDパイプラインをスムーズに実行し続けることができます。