젠킨스 에이전트

젠킨스 에이전트 (Agent) 사용하기

젠킨스 아키텍처는 원래부터 분산 빌드 환경을 염두에 두고 설계됐어요. 덕분에 빌드 프로젝트마다 서로 다른 환경을 쓰고, 여러 에이전트가 작업을 병렬로 나눠 감당하면서 워크로드를 분산할 수 있죠. 여기서 일의 주체는 크게 둘로 나뉘어요 — 전체를 관리하는 **컨트롤러(controller)**와 실제 작업을 수행하는 에이전트(agent). 에이전트가 왜 필요하고, 어떻게 관리하는지 살펴볼게요.

출처: Using Jenkins agents - Jenkins Handbook

컨트롤러와 에이전트

컨트롤러(controller)는 젠킨스 설치의 최초 노드이자, 에이전트를 관리하고 그 작업을 조율하는 주체예요. 잡을 에이전트에 스케줄링하고 에이전트 상태를 모니터링하죠. 에이전트는 컨트롤러를 대신해 실행자를 사용해 작업을 수행하는 '워커'예요.

에이전트는 로컬 컴퓨터일 수도 있고 클라우드 컴퓨터일 수도 있어요. 다만 공통 조건이 하나 있어요 — Java 설치와 컨트롤러와의 네트워크 연결. 에이전트는 작은(약 170KB 단일 jar) Java 클라이언트 프로세스로 컨트롤러에 연결하며, '불안정할 수 있다'고 가정하고 설계돼요. 즉 에이전트 하나가 죽어도 전체 시스템이 흔들리지 않게 만드는 구조라는 뜻이에요.

node('linux && high-memory') {
    // 이 블록은 linux 라벨이면서 high-memory인 에이전트에서 실행돼요
}

라벨로 에이전트 묶기

에이전트가 많아지면 '어떤 잡을 어느 에이전트에 보낼지'를 정해야 해요. 이때 쓰는 게 **라벨(label)**이에요. 라벨은 특정 기준으로 노드(에이전트)를 묶고, 잡을 특정 에이전트에 할당하는 데 도와줘요. 예를 들어 운영체제나 하드웨어 능력에 따라 라벨을 붙일 수 있어요.

linux, windows, docker, high-memory

라벨은 에이전트 구성 설정에서 지정할 수 있어요. 파이프라인에서는 node('linux')처럼 특정 라벨을 골라 작업을 보내고, 잡 설정에서도 라벨 표현식으로 실행 대상을 제한할 수 있어요.

작업을 에이전트에 배정하는 방법

잡이 어떤 에이전트에서 실행될지는 에이전트 설정의 사용(Usage) 항목으로 제어해요. 기본적으로 두 가지 방식이 있어요.

  • Use this node as much as possible — 가능하면 이 노드에 잡을 할당.
  • Only build jobs with label expressions matching this node — 라벨이 일치하는 잡만 이 노드에서 실행.

여기에 더해 빌드를 위한 실행자(executor) 수를 얼마나 둘지도 에이전트별로 설정해요. 실행자 수를 0으로 두면 그 노드에서는 작업을 실행하지 않고 관리 전용으로 쓸 수 있어요.

Docker로 에이전트 구성하기

에이전트를 Docker 컨테이너로 띄우는 것도 흔한 방식이에요. 컨테이너 이미지를 SSH로 연결하는 docker-ssh-agent 이미지를 쓰면, 에이전트를 컨테이너로 실행하고 젠킨스에 등록해 사용할 수 있어요. 이렇게 하면 필요한 도구가 들어 있는 이미지로 에이전트를 즉석에서 만들어 빌드 환경을 표준화할 수 있죠.

# Linux에서 docker-ssh-agent 이미지로 에이전트 컨테이너 실행
docker run -d --name agent1 \
  -e JENKINS_AGENT_SSH_PUBKEY="$(cat ~/.ssh/id_rsa.pub)" \
  jenkins/ssh-agent:latest-jdk17

실행 중인 컨테이너는 docker ps로 확인할 수 있어요. 컨테이너의 IP를 젠킨스 에이전트 설정의 Host로 지정해 연결하면 됩니다.

더 알아보기