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

Jenkins 에이전트(노드라고도 함)는 대부분의 빌드 작업이 실제로 실행되는 곳입니다. 에이전트가 오프라인이 되면 증상은 명확합니다. 작업이 대기열에 쌓이고, 레이블을 충족할 수 없으며, 팀은 시작되지 않을 빌드를 다시 실행하기 시작합니다. 유용한 작업은 어떤 계층이 손상되었는지 파악하는 것입니다: 네트워크 연결성, SSH, 인바운드 리모팅, Java, 자격 증명, 디스크 또는 컨트롤러 자체.

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

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

에이전트가 오프라인이 되는 데는 여러 요인이 있을 수 있습니다. 특정 증상을 식별하는 것이 잠재적 원인을 좁히는 핵심입니다:

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

네트워크 및 방화벽 문제

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

네트워크 연결성 확인

Jenkins 특정 구성으로 들어가기 전에 기본 네트워크 연결을 확인하십시오:

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

방화벽 구성

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

Jenkins 컨트롤러 방화벽: 컨트롤러가 에이전트 포트에 대한 연결을 시작할 수 있는지 확인하십시오.
에이전트 시스템 방화벽: 에이전트 시스템의 방화벽(예: ufw, firewalld, Windows 방화벽)이 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 에이전트 구성

JNLP(Java Network Launch Protocol) 에이전트는 전용 포트를 사용하여 Jenkins 컨트롤러와 통신합니다. 기본 구성에는 에이전트의 실행 방법과 컨트롤러의 사용 가능한 포트가 포함됩니다.

Jenkins UI에서 에이전트가 오프라인 상태인 경우

Jenkins UI에 에이전트가 오프라인으로 표시되면 컨트롤러가 연결을 설정하거나 유지할 수 없음을 의미합니다.

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

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

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

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

SSH 에이전트 구성

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

잘못된 SSH 자격 증명: Jenkins에서 SSH 연결에 대해 구성된 사용자 이름, 암호 또는 개인 키를 확인하십시오. 개인 키가 올바르게 형식화되었는지(예: PEM 형식) 확인하고 올바른 권한이 있는지 확인하십시오.
에이전트에서 SSH 서버가 실행되고 있지 않음: 에이전트 시스템에서 SSH 데몬(sshd)이 실행 중인지 확인하십시오.
```
# 에이전트 시스템에서
sudo systemctl status sshd
# 또는
sudo service ssh status
```
실행 중이 아닌 경우 시작하십시오:
```
sudo systemctl start sshd
sudo systemctl enable sshd
```
SSH 포트 불일치: Jenkins에서 구성된 포트가 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 홈 디렉터리 및 해당 하위 디렉터리의 소유권과 권한을 확인하십시오.
```
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를 사용하여 어떤 프로세스가 포트를 사용 중인지 확인하십시오.
```
sudo netstat -tulnp | grep 50000
# 또는
sudo ss -tulnp | grep 50000
```
다른 프로세스가 사용 중인 경우 Jenkins 또는 다른 애플리케이션을 다시 구성하여 다른 포트를 사용해야 합니다.

고급 문제 해결 및 로그

표준 점검으로 문제가 드러나지 않으면 더 깊은 조사가 필요합니다.

Jenkins 컨트롤러 로그

에이전트 연결과 관련된 오류에 대해 Jenkins 컨트롤러 로그를 검토하십시오. 이러한 로그는 특정 오류 메시지를 제공할 수 있습니다.

위치: 일반적으로 $JENKINS_HOME/jenkins.log에 있거나 Jenkins 관리 -> 시스템 로그를 통해 액세스할 수 있습니다.
찾을 내용: 에이전트의 호스트 이름, IP 주소, 연결 시도, JSch 예외 또는 연결 거부됨 오류를 언급하는 메시지.

에이전트 로그

에이전트가 실행 중이지만 오프라인을 보고하는 경우 로그에서 오류를 확인하십시오.

JNLP 에이전트: 에이전트 프로세스 자체가 콘솔 또는 지정된 로그 파일에 로그를 출력할 수 있습니다.
SSH 에이전트: 로그는 에이전트 시스템의 $JENKINS_HOME/agent.log에 있거나 SSH 수준에서 연결이 실패하는 경우 sshd와 관련될 수 있습니다.

디버그 로깅 활성화

매우 지속적인 문제의 경우 관련 Jenkins 구성 요소에 대한 디버그 로깅을 일시적으로 활성화하면 더 세분화된 정보를 제공할 수 있습니다.

JNLP/에이전트 통신: Java 시스템 속성을 조정하거나 Jenkins의 로깅 구성(Jenkins 관리 -> 시스템 로그 -> 로그 레코더)을 사용하여 hudson.slaves 또는 관련 패키지의 자세한 정도를 높여야 할 수 있습니다.

반복 중단을 방지하는 실용적인 습관

Jenkins 에이전트 연결 문제를 해결하려면 기본 네트워크 확인부터 시작하여 Jenkins 특정 구성으로 진행하는 체계적인 접근 방식이 필요합니다.

네트워크 확인: 항상 ping 및 telnet/nc로 시작하여 기본 네트워크 연결 및 포트 액세스를 확인하십시오.
방화벽 확인: 컨트롤러와 에이전트 모두의 방화벽과 모든 네트워크 방화벽이 필요한 포트의 트래픽을 허용하는지 확인하십시오.
자격 증명 확인: SSH 키, 사용자 이름 및 암호를 다시 확인하십시오.
에이전트 서비스 확인: SSH 에이전트의 경우 sshd가 실행 중이고 액세스 가능한지 확인하십시오.
Jenkins 로그 모니터링: 컨트롤러 로그는 연결 실패를 이해하기 위한 기본 소스입니다.
특정 IP 사용: 가능한 경우 방화벽과 Jenkins를 광범위한 범위나 0.0.0.0 대신 특정 IP 주소를 사용하도록 구성하십시오.

이러한 단계를 따르면 대부분의 일반적인 Jenkins 에이전트 연결 문제를 효과적으로 진단하고 해결하여 CI/CD 파이프라인이 원활하게 실행되도록 할 수 있습니다.

추측 없이 오프라인 메시지 읽기

"오프라인"이라는 단어는 그 자체로 문제를 해결하기에는 너무 광범위합니다. Jenkins 설정을 변경하기 전에 에이전트 페이지를 열고 Jenkins가 제공하는 정확한 이유를 읽으십시오. "연결 거부됨", "권한 거부됨", "호스트 키 확인 실패", "JNLP 에이전트 거부됨" 및 "채널이 닫혔습니다" 사이에는 큰 차이가 있습니다. 모두 오프라인 노드로 끝나지만 다른 계층을 가리킵니다.

저는 일반적으로 증상을 평이한 언어로 기록합니다: "컨트롤러가 TCP 포트 22에 도달할 수 없음", "SSH 로그인은 작동하지만 Java를 시작할 수 없음", "인바운드 에이전트가 시작되지만 컨트롤러로 다시 호출할 수 없음" 또는 "에이전트가 연결된 후 빌드 중에 끊어짐". 그 한 문장이 조사에 집중하게 합니다.

에이전트가 한 번도 연결된 적이 없다면 구성, DNS, 방화벽, 자격 증명 또는 실행 명령을 의심하십시오. 오늘 연결에 실패하기 전까지 몇 달 동안 연결되어 있었다면 최근 변경 사항(교체된 SSH 키, Jenkins 업그레이드, 플러그인 업데이트, 새로운 방화벽 규칙, 만료된 인증서, 에이전트 이미지 재구축 또는 클라우드 네트워킹 변경)을 확인하십시오. 타임라인은 종종 오류 텍스트보다 더 유용합니다.

SSH 에이전트: 로그인 문제와 실행 문제 분리

SSH 기반 에이전트의 경우 Jenkins가 사용하는 것과 동일한 경로를 테스트하십시오. 컨트롤러 호스트에서 Jenkins 구성 사용자로 연결하십시오:

ssh -vvv jenkins-agent-user@agent-hostname

자세한 출력은 인증 전, 인증 중 또는 로그인 후에 실패가 발생하는지 알려줍니다. SSH가 서버에 도달하지 못하면 Jenkins가 이를 해결할 수 없습니다. 라우팅, 보안 그룹, 네트워크 ACL, 호스트 방화벽 및 SSH 데몬을 확인하십시오. SSH가 서버에 도달했지만 키를 거부하는 경우 Jenkins의 자격 증명, 사용자의 authorized_keys, 파일 권한 및 계정이 잠겨 있는지 확인하십시오.

수동 SSH 로그인은 작동하지만 Jenkins가 계속 실패하는 경우 원격 루트 디렉터리와 Java 시작을 살펴보십시오. Jenkins는 리모팅 파일을 위한 쓰기 가능한 디렉터리가 필요하며 에이전트 사용자에게 해당 디렉터리에 파일을 생성할 수 있는 권한이 필요합니다. 일반적인 실수는 원격 루트를 root가 소유하거나 다른 프로세스에 의해 정리된 경로로 지정하는 것입니다.

에이전트에서 다음 확인을 실행하십시오:

whoami
pwd
java -version
test -w /path/to/jenkins-agent && echo writable
df -h /path/to/jenkins-agent

Java 버전은 최신 Jenkins 컨트롤러가 에이전트에서 호환되는 Java 버전을 필요로 하기 때문에 중요합니다. 정확한 요구 사항은 Jenkins 릴리스에 따라 다르므로 이전 에이전트 이미지가 여전히 유효하다고 가정하지 말고 사용 중인 버전에 대한 Jenkins 설명서를 확인하십시오.

인바운드 에이전트: 콜백 경로가 일반적인 함정

인바운드 에이전트는 컨트롤러가 에이전트에 대한 SSH를 시작할 수 없을 때(예: NAT 뒤에 있거나 제한된 네트워크에 있는 에이전트) 자주 사용됩니다. 에이전트 프로세스는 Jenkins 외부에서 시작되어 컨트롤러에 다시 연결됩니다. 즉, 네트워크 경로가 반대입니다: 에이전트가 Jenkins URL을 확인하고 도달해야 합니다.

에이전트 호스트에서 구성된 대로 정확히 Jenkins URL을 테스트하십시오:

curl -I https://jenkins.example.com/

Jenkins가 역방향 프록시 뒤에 있는 경우 Jenkins 관리 > 시스템의 공개 URL이 올바른지 확인하십시오. 잘못된 Jenkins URL은 생성된 에이전트 명령이 에이전트가 확인할 수 없는 내부 호스트 이름을 가리키게 할 수 있습니다. 인바운드 에이전트에 대해 WebSocket 모드가 활성화된 경우 프록시가 WebSocket 업그레이드 헤더를 지원하는지 확인하십시오. 대신 TCP 인바운드 에이전트 포트를 사용하는 경우 고정 포트가 구성되어 있고 에이전트 네트워크에서 연결할 수 있는지 확인하십시오.

TLS 문제는 Jenkins 문제처럼 보일 수 있습니다. 에이전트가 최소 컨테이너 이미지에서 실행되는 경우 내부 CA 인증서가 없을 수 있습니다. curl은 일반적으로 이를 빠르게 노출합니다. 인증서 확인을 비활성화하는 대신 CA 인증서를 에이전트 이미지에 설치하십시오.

빌드 중 연결이 끊어지는 에이전트

성공적으로 연결된 후 빌드 중에 끊어지는 에이전트는 일반적으로 기본 연결 문제가 아닙니다. 리소스 압박과 프로세스 수명 주기를 살펴보십시오.

운영 체제가 에이전트 프로세스를 종료했는지 확인하십시오:

dmesg -T | grep -i -E 'killed process|out of memory'
journalctl -u jenkins-agent --since '2 hours ago'

또한 디스크 공간을 확인하십시오. Jenkins 리모팅, 체크아웃, 테스트 보고서 및 보관된 아티팩트는 모두 공간이 필요합니다. 가득 찬 작업 영역 볼륨은 리모팅 프로세스가 임시 파일이나 로그를 쓸 수 없기 때문에 에이전트를 신뢰할 수 없게 보이게 할 수 있습니다.

연결 끊김이 대량 콘솔 출력, 아티팩트 보관 또는 테스트 보고서 게시 중에 발생하는 경우 네트워크 안정성과 컨트롤러 부하를 살펴보십시오. 에이전트 채널은 실시간 연결입니다. 컨트롤러의 긴 가비지 수집 일시 중지, 과부하된 프록시, 유휴 연결 시간 초과 및 패킷 손실로 인해 연결이 끊어질 수 있습니다. 로드 밸런서나 회사 프록시를 통과하는 에이전트의 경우 유휴 시간 초과 설정과 연결 유지 동작을 확인하십시오.

DNS 및 호스트 키 문제

DNS 변경은 놓치기 쉽습니다. Jenkins는 build-agent-01에 연결하는 반면 수동 테스트는 IP 주소를 사용할 수 있습니다. 컨트롤러에서 호스트 이름을 테스트하십시오:

getent hosts build-agent-01
nc -vz build-agent-01 22

호스트 이름이 잘못된 주소로 확인되면 DNS 또는 에이전트 구성을 수정하십시오. 명확한 소유권 프로세스가 없으면 장기적인 /etc/hosts 패치를 피하십시오. 보이지 않는 인프라가 되기 때문입니다.

SSH 에이전트의 경우 호스트 키 확인은 Jenkins가 예기치 않은 시스템에 연결하는 것을 방지합니다. 에이전트가 재구축된 경우 호스트 키가 변경되었을 수 있습니다. 확인을 맹목적으로 비활성화하지 마십시오. 재구축을 확인하고 컨트롤러 사용자의 known_hosts에서 이전 키를 제거하고 구성된 Jenkins 전략을 통해 새 키를 수락하십시오.

프로덕션 에이전트를 위한 복구 체크리스트

여러 에이전트가 동시에 오프라인이 되는 경우 공통 원인을 찾기 전에 하나씩 수정하지 마십시오. 다음을 질문하십시오:

Jenkins 컨트롤러가 다시 시작되었거나 업그레이드되었습니까?
공유 자격 증명이 교체되었습니까?
기본 에이전트 이미지가 변경되었습니까?
방화벽, 프록시, VPN 또는 DNS 변경이 배포되었습니까?
실패한 모든 에이전트가 동일한 서브넷, 클라우드 계정, Kubernetes 네임스페이스 또는 가용성 영역에 있습니까?

에이전트 하나만 실패하면 해당 호스트를 검사하십시오. 전체 그룹이 함께 실패하면 공통 종속성을 검사하십시오. 이렇게 하면 대규모 Jenkins 팜에서 많은 시간을 절약할 수 있습니다.