이 문서는 reverse proxy로 구성되어 agent TCP 포트 연결이 어려운 환경에서 agent 를 구성하는 방법을 정리한다.

개요

HTTP(s) 포트 (80 또는 443) 포트를 통해 Jenkins master 서버에 접속은 가능하지만, agent는 별도의 TCP (default 5000 포터) 포트 접속은 안되는 경우가 발생한다.

해결 방법

Jenkins 는 webSocket를 이용해 agent와 통신하는 설정을 지원한다.

Step 1) Master 서버 webSocket 활성화

  1. Manage Jenkins > Nodes
  2. 추가하려는 agent의 Configuration 으로 이동
  3. Launch method 항목으로 이동
  4. Use WebSocket 체크
  5. 설정 저장

만약 Launch method 가 보이지 않는다면,

  1. Manage Jenkins > Script Console
  2. 스크립트 입력 (agentName 에 agent 이름으로 변경)
    import hudson.model.Node
import hudson.slaves.JNLPLauncher

// Enter the exact name of your Windows agent here
def agentName = "YOUR_AGENT_NODE_NAME" 

def node = Jenkins.get().getNode(agentName)

if (node != null) {
    def newLauncher = new JNLPLauncher("", "", null)
    newLauncher.setWebSocket(true)
    
    node.setLauncher(newLauncher)
    node.save()
    
    println "SUCCESS: Agent '${agentName}' has been successfully forced into WebSocket mode!"
} else {
    println "ERROR: Could not find an agent named '${agentName}'. Please check the spelling."
}


  3. 스크립트 실행
  4. Launch method 항목에 Use WebSocket 체크 활성 상태 확인

Step 2) Reverse Proxy 서버 설정

Nginx를 예시로 설명한다.

  1. 설정 수정
    server {
    listen 80; # or 443 ssl
    server_name your-jenkins-domain.com;

    location / {
        proxy_pass http://<internal_jenkins_master_private_ip>:8080;
        
        # === CRUCIAL WEBSOCKET HEADERS ===
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # === TIMEOUT FIXES FOR AGENTS ===
        # Stops Nginx from dropping the agent handshake connection every 60 seconds
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s; 
        
        # Standard proxy headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
  2. 설정 반영
    sudo nginx -s reload

Step 3) Agent 에 webSocket 옵션 지정

Agent 가 TCP 대신 webSocket 을 사용하도록 옵션을 지정한다.

@echo off
cd /d C:\Jenkins

"C:\Program Files\Java\jdk-21\bin\java.exe" -jar agent.jar -jnlpUrl https://curvc.com<YOUR_NODE_NAME>/jenkins-agent.jnlp -secret <YOUR_SECRET_KEY> -workDir "C:\Jenkins" -webSocket -noCertificateCheck

pause


  • 레이블 없음