Jenkins 에이전트 연결 문제 및 해결 방법

일반적인 Jenkins 에이전트 연결 문제 및 해결 방법

Jenkins 에이전트(노드 또는 실행기라고도 함)는 빌드 작업을 실행하는 CI/CD 파이프라인의 중요한 구성 요소입니다. 에이전트가 오프라인 상태가 되거나 연결에 실패하면 전체 자동화 워크플로우가 중단될 수 있습니다. 이 가이드는 가장 일반적인 연결 문제를 진단하고 해결하여 Jenkins 인프라를 견고하게 유지하고 빌드 작업이 중단 없이 실행되도록 안내합니다.

에이전트가 연결할 수 없게 되는 이유를 이해하는 것이 효과적인 문제 해결의 첫 번째 단계입니다. 이러한 문제는 네트워크 구성 오류, 잘못된 에이전트 설정, 방화벽 제한 또는 Jenkins 컨트롤러 자체의 문제에서 비롯될 수 있습니다. 이러한 영역을 체계적으로 확인하여 문제의 근본 원인을 신속하게 파악하고 해결책을 구현할 수 있습니다.

Jenkins 에이전트 연결 끊김의 일반적인 원인

여러 요인으로 인해 에이전트가 오프라인 상태가 될 수 있습니다. 특정 증상을 파악하는 것이 잠재적 원인을 좁히는 열쇠입니다.

에이전트 연결 불가: Jenkins 컨트롤러가 에이전트에 연결을 설정할 수 없습니다.
연결 거부됨: 에이전트 머신이 컨트롤러의 연결 시도를 적극적으로 거부합니다.
연결 성공 후 오프라인 보고: 에이전트가 연결되었지만 이후 연결이 끊어졌습니다.
JSch 오류(SSH 기반 에이전트의 경우): SSH 연결에 사용되는 Java Secure Channel 라이브러리와 관련된 특정 오류입니다.

네트워크 및 방화벽 문제

네트워크 연결은 에이전트 연결 문제의 가장 빈번한 원인입니다. Jenkins 컨트롤러가 에이전트 머신에 도달할 수 있는지, 그 반대도 마찬가지인지 확인하는 것이 가장 중요합니다.

네트워크 연결 확인

Jenkins별 구성을 자세히 살펴보기 전에 기본 네트워크 연결을 확인하십시오.

에이전트 Ping: Jenkins 컨트롤러 머신에서 에이전트 머신의 IP 주소 또는 호스트 이름을 ping 해봅니다.
bash ping <agent-hostname-or-ip>
에이전트 포트로 Telnet: Jenkins가 에이전트에 연결하는 데 사용하는 포트가 열려 있고 수신 대기 중인지 테스트합니다. JNLP 에이전트의 경우 일반적으로 포트 50000입니다. SSH 에이전트의 경우 SSH 포트(기본값 22)입니다.
bash telnet <agent-hostname-or-ip> <agent-port>
연결이 시간 초과되거나 거부되면 포트를 차단하는 네트워크 또는 방화벽 문제가 있을 가능성이 높습니다.

방화벽 구성

Jenkins 컨트롤러, 에이전트 머신 또는 중간 네트워크 장치의 방화벽이 필요한 포트를 차단할 수 있습니다.

Jenkins 컨트롤러 방화벽: 컨트롤러가 에이전트 포트로 연결을 시작할 수 있는지 확인합니다.
에이전트 머신 방화벽: 에이전트 머신(예: ufw, firewalld, Windows Firewall)의 방화벽이 Jenkins 컨트롤러의 IP 주소로부터의 에이전트 포트에 대한 수신 연결을 허용하는지 확인합니다.
네트워크 방화벽: 네트워크에 내부 방화벽이 있는 경우 컨트롤러와 에이전트 간의 트래픽이 허용되는지 확인합니다.

예: 에이전트에서 포트 50000 허용(Linux 및 `ufw` 사용 시)

# 특정 IP(Jenkins 컨트롤러)로부터의 연결 허용
sudo ufw allow from <jenkins-controller-ip> to any port 50000

# 또는 모든 IP 허용(보안 수준 낮음)
sudo ufw allow 50000

# 방화벽 규칙 다시 로드
sudo ufw reload

예: 에이전트에서 포트 22 허용(Linux 및 `firewalld` 사용 시)

# 특정 소스 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에 에이전트가 오프라인으로 표시되면 컨트롤러가 연결을 설정하거나 유지할 수 없었음을 의미합니다.

에이전트 시작 방법 확인: 에이전트가 올바르게 시작되도록 구성되었는지 확인합니다. 일반적인 방법은 다음과 같습니다.
- 마스터에 연결하여 에이전트 시작: 이 방법은 에이전트 측에서 수동 시작이 필요합니다.
- SSH를 통해 에이전트 시작: SSH 자격 증명 및 호스트 설정을 통해 구성됩니다.
- 내장 노드 속성을 사용하여 에이전트 시작: 특정 시나리오용입니다.
JNLP 포트 가용성 확인: Jenkins 컨트롤러는 구성된 JNLP 포트(기본값 50000)에서 수신 대기해야 합니다. Manage Jenkins -> System -> Advanced -> File
-> TCP port for JNLP agents로 이동하여 설정되어 있고 액세스 가능한지 확인하십시오.

JNLP 에이전트 시작 시 "연결 거부됨"

이는 종종 Jenkins 컨트롤러의 JNLP 포트(기본값 50000)가 에이전트 머신에서 열려 있지 않거나 액세스할 수 없음을 의미합니다. 컨트롤러의 방화벽 규칙을 확인하고 포트가 올바르게 구성되었는지 확인하십시오.

팁: Jenkins 컨트롤러를 다시 시작하면 때때로 일시적인 JNLP 포트 문제가 해결될 수 있습니다.

SSH 에이전트 구성

SSH를 사용하여 에이전트에 연결할 때 여러 요인이 문제를 일으킬 수 있습니다.

잘못된 SSH 자격 증명: SSH 연결에 대해 Jenkins에 구성된 사용자 이름, 암호 또는 개인 키를 확인합니다. 개인 키가 올바르게 형식화되었는지(예: PEM 형식) 권한이 올바른지 확인합니다.
에이전트에서 SSH 서버 실행 중 아님: 에이전트 머신에서 SSH 데몬(sshd)이 실행 중인지 확인합니다.
bash # 에이전트 머신에서 sudo systemctl status sshd # 또는 sudo service ssh status
실행 중이 아니면 시작합니다.
bash sudo systemctl start sshd sudo systemctl enable sshd
SSH 포트 불일치: Jenkins에서 SSH에 대해 구성한 포트가 SSH 서버가 수신 대기 중인 포트(기본값 22)와 일치하는지 확인합니다.
에이전트 호스트 이름/IP 확인: Jenkins 컨트롤러가 에이전트의 호스트 이름 또는 IP 주소를 확인할 수 있어야 합니다.
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 포트 충돌

JNLP 포트(기본값 50000)가 Jenkins 컨트롤러의 다른 프로세스에서 이미 사용 중이면 에이전트가 연결에 실패합니다.

포트 사용량 확인: 컨트롤러 머신에서 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 파이프라인을 원활하게 실행할 수 있습니다.