Jenkins 연결 문제 진단: 네트워크 및 에이전트 문제
포트, 방화벽, 인바운드 에이전트, SSH, Java 및 로그를 확인하여 Jenkins 컨트롤러와 에이전트 간 연결 문제를 해결합니다.
Jenkins 연결 문제 진단: 네트워크 및 에이전트 문제
Jenkins는 중앙 컨트롤러와 실행 환경(에이전트 또는 노드) 간의 강력한 통신에 크게 의존합니다. 이 연결이 실패하면 빌드가 중단되고, 파이프라인이 멈추며, 지속적 통합이 중단됩니다. 이러한 문제를 진단하려면 체계적인 접근 방식이 필요하며, 일반적으로 먼저 네트워크 토폴로지에 초점을 맞춘 다음 에이전트 구성 및 프로토콜 오류를 확인해야 합니다.
이 포괄적인 가이드는 가장 일반적인 Jenkins 연결 문제(해결하기 어려운 방화벽 문제, 잘못 구성된 JNLP 포트, 에이전트 시작 실패 등)를 해결하기 위한 단계별 지침을 제공하여 안정적인 운영과 신뢰할 수 있는 CI/CD 파이프라인을 신속하게 복원하는 데 도움을 줍니다.
1. Jenkins 컨트롤러-에이전트 통신 이해
문제 해결을 시작하기 전에 Jenkins 컨트롤러가 에이전트와 통신하는 방식을 이해하는 것이 중요합니다. Jenkins는 각각 고유한 진단 요구 사항이 있는 두 가지 기본 방법을 제공합니다.
1.1 Java 네트워크 실행 프로토콜 (JNLP)
JNLP 모델에서는 Jenkins 에이전트가 컨트롤러에 대한 연결을 시작합니다. 이는 권장되는 가장 일반적인 접근 방식입니다. 에이전트는 컨트롤러의 특정 포트(현재는 일반적으로 인바운드 에이전트 TCP 포트라고 함)에 연결합니다.
- 방향: 에이전트가 컨트롤러에 연결합니다.
- 필수 포트: 컨트롤러의 인바운드 에이전트 TCP 포트(기본값은 종종 50000 또는 동적으로 할당됨).
1.2 보안 셸 (SSH)
SSH 모델에서는 Jenkins 컨트롤러가 에이전트에 대한 연결을 시작합니다. 이를 위해서는 에이전트 머신에서 SSH 서버가 실행 중이어야 합니다.
- 방향: 컨트롤러가 에이전트에 연결합니다.
- 필수 포트: 에이전트의 SSH 포트(일반적으로 22).
- 요구 사항: SSH 자격 증명(키 또는 비밀번호)이 Jenkins에 올바르게 구성되어 있어야 합니다.
2. 초기 네트워크 및 방화벽 진단
네트워크 문제, 특히 방화벽 제한은 연결 문제의 가장 빈번한 원인입니다. 에이전트가 갑자기 오프라인이 되거나 새 에이전트가 연결에 실패하면 여기서부터 시작하세요.
2.1 필수 포트가 열려 있는지 확인
통신 모델에 따라 필요한 포트에서 트래픽이 흐를 수 있는지 확인해야 합니다.
| 연결 유형 | 소스 | 대상 | 필수 포트 | 상태 확인 |
|---|---|---|---|---|
| 웹 인터페이스 | 사용자/에이전트 | 컨트롤러 | 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
팁: "연결 거부" 오류는 네트워크 경로는 열려 있지만 서비스(Jenkins)가 해당 포트에서 수신 대기 중이지 않거나 컨트롤러의 로컬 방화벽이 차단하고 있음을 나타냅니다. 연결 시간이 초과되면 머신 사이의 방화벽이 원인일 가능성이 높습니다.
2.3 고정 JNLP 포트 설정
JNLP를 사용하는 경우 모호성을 피하고 방화벽 규칙을 단순화하기 위해 고정 포트를 구성하는 것이 가장 좋습니다. Jenkins는 고정 포트를 설정하지 않으면 임의의 인바운드 에이전트 포트를 사용할 수 있으며, 이는 보안 설정을 복잡하게 만듭니다.
- Jenkins 관리 > 보안(또는 이전 Jenkins 버전의 전역 보안 구성)으로 이동합니다.
- 에이전트에서 인바운드 에이전트용 TCP 포트 옵션을 찾습니다.
- 고정을 선택하고 포트(예: 50000)를 지정합니다.
- 컨트롤러 머신의 호스트 운영 체제 방화벽(예:
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가 역방향 프록시 뒤에 있는 경우 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 인증 방법 확인
- 키: Jenkins 자격 증명 관리자에 저장된 개인 키에 해당하는 공개 키가 에이전트 사용자의
~/.ssh/authorized_keys파일에 올바르게 추가되었는지 확인하세요. - 비밀번호: 비밀번호를 사용하는 경우 에이전트의 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또는JDK 경로변수가 에이전트 머신의 유효한 Java 설치 디렉터리를 가리키는지 확인하세요.
5.2 작업 공간 및 사용자 권한
Jenkins가 에이전트를 실행하는 데 사용하는 사용자 계정(SSH 로그인 또는 시스템 서비스를 통해)은 정의된 원격 루트 디렉터리(작업 공간)에 대한 읽기 및 쓰기 권한이 있어야 합니다.
- 조치: 원격 루트 디렉터리(예:
/home/jenkins/workspace)의 소유권과 권한을 확인하세요.
5.3 시간 동기화
흔하지는 않지만 컨트롤러와 에이전트 머신 간의 심각한 시간 차이는 SSL/TLS 핸드셰이크 오류를 유발하여 연결 끊김이나 거부를 초래할 수 있습니다. 두 머신이 네트워크 시간 프로토콜(NTP)을 통해 동기화되어 있는지 확인하세요.
요점 및 체크리스트
Jenkins 연결 문제 해결은 네트워크 경계에서부터 안쪽으로 진행되는 제거 과정입니다. 방화벽을 체계적으로 확인하고, telnet과 같은 도구를 사용하여 포트 연결 가능성을 확인하고, 통신 프로토콜(JNLP 또는 SSH)이 올바르게 인증되고 구성되었는지 확인함으로써 연결 문제를 신속하게 찾아내고 해결할 수 있습니다.
문제 해결 체크리스트:
- 네트워크 방화벽: 필수 포트(JNLP의 경우 50000+, SSH의 경우 22)에서 트래픽이 양방향으로 허용됩니까?
- 로컬 방화벽: 컨트롤러/에이전트에서 실행 중인 OS 방화벽(Windows/Linux)이 포트를 차단하고 있습니까?
- 프로토콜 테스트: 연결 머신에서 대상의 관련 포트로
telnet이 성공합니까? - Java: 에이전트에 호환되는 Java 버전이 설치되어 있고 경로가 올바릅니까?
- 인증: SSH 키/비밀번호가 유효합니까, 아니면 JNLP 비밀 토큰이 최신 상태입니까?
모든 연결 시도가 실패하면 서비스 저널 또는 /var/log/jenkins/jenkins.log에서 확인할 수 있는 Jenkins 컨트롤러 로그에서 리모팅 및 Java 스택 추적을 확인하세요.