[Jenkins] Agent 구성하기

이준영·2026년 1월 8일

Agent를 만들게 된 이유

예전에 구현한 기능인데, 계속 다른걸 공부해서 올리다 보니 늦었다.

Jenkins 관리 텝에 들어가다 보면 여러가지 경고 문구를 볼 수 있는데, 여기서

"Building on the built-in node can be a security issue. You should set up distributed builds. See the documentation." 라는 문구의 경고 창을 볼 수 있다.

해당 경고는 보안과 안정성 측면에서 'Best Practice(모범 사례)'를 권장하고 있기 때문이다.

간단히 말해, "Jenkins 메인 서버(Controller)에서 직접 빌드를 돌리지 말고, 별도의 작업용 서버(Agent)를 연결해서 사용하라"는 뜻이다.

내장 구조가 위험한 이유

Jenkins의 Built-in Node는 Jenkins의 설정, 플러그인 정보, 기밀 데이터를 모두 가지고 있는 심장부이다.

보안 위험: 빌드 스크립트에 악의적인 코드나 실수가 포함되어 있다면, Jenkins 설정 파일을 직접 수정하거나 삭제할 수 있다. 즉, 빌드 하나가 Jenkins 서버 전체를 망가뜨릴 수 있다.
성능 저하: 여러 빌드가 동시에 메인 서버에서 실행되면 CPU와 메모리 점유율이 올라가 Jenkins 대시보드 자체가 느려지거나 응답 불능 상태가 될 수 있다.
격리 실패: 빌드 도중 생성된 임시 파일이나 환경 변수가 Jenkins 시스템 자체에 영향을 줄 수 있다.

분산 빌드 구조

가장 권장되는 방식은 Controller-Agent 구조
Jenkins Controller (Main): 설정 관리, 빌드 스케줄링, UI 제공 (빌드는 수행하지 않음).
Jenkins Agent (Node): 실제 빌드 명령을 수행하는 별도의 서버 또는 컨테이너.

Agent 구성하기

내장 노드의 실행기 수를 0으로 설정

내장 노드의 실행기 수를 0으로 설정

사진으로 간단 설명!
이제 Save.

새로운 Agent 추가

새로운 Agent 추가

이름은 build_agent로 했다.

Agent 옵션

이 옵션중 Remote root directory가 가장 중요하다
난 C\JenkinsTest로 설정했다. 다만 이렇게 설정하려면 실제 경로에 같은 폴더가 있어야 한다.

경로

이제 Agent 옵션 중 밑에 옵션을 설정해야한다.

Usage

Use this node as much as possible : 최대한 이 노드 사용
Only build jobs with label expressions matching this node : 이 노드와 일치하는 레이블 표현식이 있는 빌드만 실행
난 Use this node as much as possible을 사용했다.

Launch method

방식	주도권	권장 환경	비고
Inbound (1번)	에이전트가 먼저 접근	Windows, 내부망 노드	컨트롤러의 IP/도메인을 알아야 함
Command (2번)	컨트롤러가 직접 명령 실행	Docker, 클라우드	고급 사용자용 스크립팅 필요
SSH (3번)	컨트롤러가 먼저 접근	Linux (가장 추천)	SSH 플러그인 설치 필요

나는 Windows를 사용중이기 때문에 1번을 사용했다.

Availability

Keep this agent online as much as possible : 항상 온라인 상태 유지
Bring this agent online according to a schedule : 스케줄에 따라 온라인으로 전환
Bring this agent online when in demand, and take offline when idle : 필요할 때만 연결하고 한가할 때 연결 해제
Keep this agent online as much as possible를 사용.
이제 옵션을 다 설정했으면 저장.

Jenkins 홈

Jenkins 홈으로 돌아오면 그냥 죽어있는 Agent를 볼 수 있다.
살아있는지 눌러보자.

Agent

딱 보니, 나에 상황에 맞는 OS에 따라 해당 명령어 들을 입력하면 될 거 같다.
일단 cmd를 켰다.

Cmd

C:\JenkinsTest로 이동하고 복사한 코드를 넣어줬다.
만약 agent.jar이 다운되지 않는다면 [내 ip 주소] -> localhost로 바꿔보면 된다.
맨 밑줄에 "정보: Connected"가 뜬다면 성공

Jenkins 홈

이제 사용할 수 있는 agent가 완성되었다.
하지만 이 방법에는 치명적인 단점이 있는데, agent를 활성화 시킬 때 마다 저 뒤질라게 긴 명령어를 cmd에서 실행시켜야 한다.

상시 활성화

그래서 Windows Service로 등록하는 방법이 있다.

WinSW GitHub 배포 페이지에 접속
WinSW-x64.exe 파일을 다운로드

사진

WinSW GitHub 배포 페이지에 접속
WinSW-x64.exe 파일을 다운로드

사진

다운로드한 파일을 에이전트 폴더인 C:\JenkinsTest로 옮기기
파일 이름을 관리하기 쉽게 JenkinsTest-agent.exe로 변경

사진

텍스트 파일 생성 후, 이름을 JenkinsTest-agent.xml로 변경.
해당 파일을 열어서 다음 코드를 작성해준다.

<service>
  <id>jenkins-agent2</id>
  <name>Jenkins Agent2</name>
  <description>This service runs a Jenkins agent for distributed builds.</description>
  <executable>java</executable>
  <arguments>-jar agent.jar -url http://localhost:8080/ -secret 8f881e9159708deca9e7bc45b37033b721acdc74d942b668be41534bf8b69f05 -name "build_agent" -webSocket -workDir "C:\JenkinsTest"</arguments>
  <log mode="roll"></log>
</service>