DevOps 지식 허브
DevOps 지식 허브

Jenkins 연결 문제 진단: 네트워크 및 에이전트 이슈

핵심 연결 문제 해결 단계를 숙달하여 Jenkins 환경을 복구하십시오. 이 가이드는 마스터-에이전트 통신과 관련된 문제 진단 및 해결에 중점을 두며, 방화벽 구성, JNLP 포트 설정, SSH 인증 실패와 같은 중요한 네트워크 측면을 다룹니다. `telnet`과 같은 도구를 사용하여 접근성을 확인하는 방법과 일반적인 환경적 함정을 이해하는 방법을 배우고, 이를 통해 Jenkins 에이전트가 온라인 상태를 유지하고 CI/CD 파이프라인이 원활하게 실행되도록 보장합니다.

40 조회수

Jenkins 연결 문제 진단: 네트워크 및 에이전트 문제

Jenkins는 중앙 컨트롤러(마스터)와 실행 환경(에이전트 또는 노드) 간의 강력한 통신에 크게 의존합니다. 이 연결이 실패하면 빌드가 지연되고, 파이프라인이 중단되며, 지속적 통합이 멈춥니다. 이러한 문제를 진단하려면 체계적인 접근 방식이 필요하며, 종종 먼저 네트워크 토폴로지에 초점을 맞춘 다음 에이전트 구성 및 프로토콜 오류를 살펴봅니다.

이 포괄적인 가이드는 까다로운 방화벽 문제, 잘못 구성된 JNLP 포트, 에이전트 시작 실패를 포함한 가장 일반적인 Jenkins 연결 문제를 해결하기 위한 단계별 지침을 제공하여 안정적인 운영 및 신뢰할 수 있는 CI/CD 파이프라인을 신속하게 복원하도록 돕습니다.

1. Jenkins 마스터-에이전트 통신 이해

문제 해결 전에 Jenkins 마스터(컨트롤러)가 에이전트와 통신하는 방법을 이해하는 것이 중요합니다. Jenkins는 두 가지 주요 방법을 제공하며, 각 방법에는 고유한 진단 요구 사항이 있습니다.

1.1 Java Network Launch Protocol (JNLP)

JNLP 모델에서는 Jenkins 에이전트가 마스터로의 연결을 시작합니다. 이것이 권장되는 가장 일반적인 접근 방식입니다. 에이전트는 마스터의 특정 포트(JNLP 에이전트 포트)에 연결합니다.

  • 방향: 에이전트가 마스터에 연결.
  • 필요한 포트: 마스터의 JNLP 포트(기본값은 종종 50000이거나 동적으로 할당됨).

1.2 Secure Shell (SSH)

SSH 모델에서는 Jenkins 마스터가 에이전트로의 연결을 시작합니다. 이를 위해서는 에이전트 머신에서 SSH 서버가 실행 중이어야 합니다.

  • 방향: 마스터가 에이전트에 연결.
  • 필요한 포트: 에이전트의 SSH 포트(일반적으로 22).
  • 요구 사항: Jenkins에서 SSH 자격 증명이 올바르게 구성되어야 합니다(키 또는 비밀번호).

2. 초기 네트워크 및 방화벽 진단

네트워크 문제, 특히 방화벽 제한은 연결 문제의 가장 빈번한 단일 원인입니다. 에이전트가 갑자기 오프라인이 되거나 새 에이전트가 연결되지 않으면 여기서 시작하십시오.

2.1 필수 포트 열림 확인

통신 모델에 따라 필요한 포트에서 트래픽이 흐를 수 있는지 확인해야 합니다.

연결 유형 소스 대상 필요한 포트 상태 확인
웹 인터페이스 사용자/에이전트 마스터 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. Manage Jenkins > Manage Nodes and Clouds > Configure Global Security로 이동합니다.
  2. Agents 섹션에서 TCP port for inbound agents 옵션을 찾습니다.
  3. Fixed를 선택하고 포트(예: 50000)를 지정합니다.
  4. 이 포트가 마스터 머신의 호스트 운영 체제 방화벽(예: iptables, firewalld 또는 Windows 방화벽)에 열려 있는지 확인합니다.

3. JNLP 에이전트 문제 해결

네트워크 확인이 통과되면 문제는 일반적으로 인증, 구성 또는 환경 불일치와 관련이 있습니다.

3.1 마스터의 에이전트 로그 확인

JNLP 에이전트를 시작하려고 할 때 Jenkins 자체에서 제공하는 로그를 확인하십시오. 특정 에이전트 구성 페이지로 이동하여 Log 섹션을 봅니다. 이 섹션에는 가장 명확한 오류 메시지가 제공되는 경우가 많습니다.

  • 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을 반영하는지 확인하십시오.
  • Secret Token 확인: 노드가 재구성되면 토큰이 만료되거나 변경될 수 있습니다. 최신 .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 자격 증명 관리자에 저장된 개인 키에 해당하는 공개 키가 에이전트 사용자의 ~/.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 스택 추적을 확인하십시오.