Jenkins AWS 에서 구축하기 (2) - Agent 구축 및 연결

0. Agent 내부 구성

Jenkins Agent에 Docker를 설치하면, 파이프라인에서 동일한 Docker 이미지로 빌드와 테스트를 실행할 수 있어 환경 차이로 인한 문제를 줄일 수 있다. Agent 한 대가 Docker 호스트 역할을 하면 Java·Node·Python 등 여러 런타임을 각각의 컨테이너로 돌릴 수 있어, 에이전트마다 다른 툴을 깔 필요 없이 한 Agent로 여러 환경을 제공할 수 있으므로, Docker까지 함께 설치하는 것을 구상했다.

1. AWS 인스턴스 생성

Agent 또한 스펙은 chatGPT의 도움을 받았다.

애플리케이션 및 OS 이미지(Amazon Machine Image)

• Amazon Linux 선택
• AMI : Amazon Linux 2023 kernel-6.1 AMI
• 아키텍처 : 64비트

EC2에서 가장 AWS 친화적인 리눅스 버전으로, Controller와 동일하다.

인스턴스 유형

• t3.large

Jenkins Agent는 단순 SSH 머신이 아니라, 실제 빌드를 수행해야 하는 CI 워커 노드이다. 그리고 OOM(Out Of Memory) 장애를 피하기 위해 메모리를 8GB를 해야 안정적이다.

키 페어

접속할 때 이용할 키 페어로, 하나 생성했다.

네트워크 설정

별도로 설정한 것은 없다.

스토리지 구성

빌드 데이터도 가지고 있으려면 다소 넉넉한 용량이 필요하다.

2. 인스턴스에 접속 및 기본 설정

가지고 있는 키 페어나, 1번에서 키 페어를 생성했다면 자동 다운로드 된 *.pem 파일을 가지고 로그인을 시도한다.

우선 해당 파일을 권한 설정을 해준다.

chmod 400 my-key.pem

이후 접속을 시도한다.

ssh -i my-key.pem {user_account}@{public_ip}

3. Jenkins Agent 설치

agent 내부에서 작업한다.

Java 설치

sudo dnf install java-17-amazon-corretto -y

설치하고 java -version 까지 하면 잘 나오는 것을 볼 수 있다.

Docker 설치

# Docker 설치
sudo dnf install docker -y

# Docker 서비스 시작
sudo systemctl enable docker
sudo systemctl start docker

# ec2-user를 docker 그룹에 추가
sudo usermod -aG docker ec2-user

# 로그아웃
exit

그룹에 추가하고 로그아웃하는 이유는, sudo 명령어 없이 수행하면 다음과 같은 오류가 뜬다.

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.44/containers/json": dial unix /var/run/docker.sock: connect: permission denied

그러므로, 그룹에 추가하고 로그아웃 후에 다시 로그인해주면 된다.

3. Controller에서 Agent 노드 생성

Inbound Agent 포트 열기

설정(메인 페이지 상단 좌측 톱니바퀴 아이콘)에 들어가서 Security 로 들어가서, 아래 이미지처럼 Agent 섹션에서 TCP port for inbound agents 포트를 Fixed 로 해서 50000를 지정했다.

노드 생성

설정에 들어가서 System Configuration 섹션에서 Nodes 를 클릭해서, 다음 화면에서 [New Node] 를 클릭한다.

노드의 이름을 입력하고 Create 버튼을 누르면, 아래와 같이 입력 폼이 더 나타난다. 아래와 같이 설정했고, 각 설정 별로 궁금해서 찾아본 것들을 아래 적어두었다.

• Remote root directory
  • 기본 유저(위에서 사용한 유저)를 사용한다면 아래 이미지대로 /home/{user_name}/jenkins 으로 입력해준다.
• Usage
  • 젠킨스가 빌드를 어떻게 수행할지 결정하는 것이다.
  • Use this node as much as possible
    • 기본 설정으로, Jenkins가 해당 노드를 자유롭게 사용하며, 해당 노드를 사용해서 실행할 수 있는 빌드가 있다면 Jenkins에서는 언제든 이 노드를 사용한다.
  • Only build jobs with label expressions matching this node
    • 특정 노드에서만 실행되도록 라벨 표현식으로 프로젝트를 제한하고, 그 표현식이 노드 이름 또는 라벨과 일치할 때만 Jenkins가 해당 작업을 이 노드에서 실행한다.
• Launch method
  • Launch agent by connecting it to the controller
    • Inbound Agent인 JNLP 방식으로 Agent가 Controller로 직접 연결을 시도한다. 방화벽이 엄격한 환경에서 유리하고, Cloud / K8s 환경에서 표준 방식으로 이용된다.
  • Launch agents via SSH
    • Controller가 SSH로 에이전트 호스트에 접속해, 그 위에서 에이전트 프로세스를 기동한다. 에이전트는 Controller → 에이전트 방향으로만 연결이 필요하므로, 에이전트가 방화벽 안쪽에 있어도 Controller만 SSH(22번 포트) 접근이 가능하면 된다. 사내/온프레미스처럼 네트워크를 제어할 수 있는 환경에서 많이 쓰이고, 에이전트 머신에 에이전트를 직접 설치·실행하지 않고 SSH만으로 관리할 때 유리하다.
• 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
    • 빌드 등 작업이 있을 때만 에이전트를 올리고, 일정 시간 유휴면 오프라인으로 내린다. 리소스 절약이 중요할 때(예: Cloud/유료 에이전트)에 적합하다.

이후, Save 버튼을 누르고, Nodes 목록 화면에서 방금 전 생성된 노드를 클릭한다.

agent.jar 다운로드 및 실행 (Agent에서 작업)

위에서 생성한 노드를 클릭해서 들어가면 아래와 같은 화면이 나온다.

IP와 시크릿키는 모두 가렸으나 환경에 따라 실행해야 되는 명령어가 나온다.

시크릿 키는 반드시 저장하자.

작업 디렉토리 생성

mkdir ~/jenkins
cd ~/jenkins

agent.jar 다운로드

~/jenkins 에서 수행해야 한다.

curl -sO http://{controller-ip}:8080/jnlpJars/agent.jar

agent 실행

java -jar agent.jar -url http://{controller-ip}:8080/ -secret {secret} -name "{node-name}" -webSocket -workDir "/home/{user-name}/jenkins"

Feb 22, 2026 12:51:15 PM org.jenkinsci.remoting.engine.WorkDirManager initializeWorkDir
INFO: Using /home/ec2-user/jenkins/remoting as a remoting work directory
Feb 22, 2026 12:51:15 PM org.jenkinsci.remoting.engine.WorkDirManager setupLogging
INFO: Both error and output logs will be printed to /home/ec2-user/jenkins/remoting
Feb 22, 2026 12:51:15 PM hudson.remoting.Launcher createEngine
INFO: Setting up agent: aws-agent-01
Feb 22, 2026 12:51:15 PM hudson.remoting.Engine startEngine
INFO: Using Remoting version: 3352.v17a_fb_4b_2773f
Feb 22, 2026 12:51:15 PM org.jenkinsci.remoting.engine.WorkDirManager initializeWorkDir
INFO: Using /home/ec2-user/jenkins/remoting as a remoting work directory
Feb 22, 2026 12:51:15 PM hudson.remoting.Launcher$CuiListener status
INFO: WebSocket connection open
Feb 22, 2026 12:51:15 PM hudson.remoting.Launcher$CuiListener status
INFO: Connected

정상 Connected 확인

컨트롤러의 Nodes 에 들어가서 보면 이제 명령어가 아닌 Agent is connected. 를 확인할 수 있다.

서비스로 등록

서비스로 등록하지 않으면, EC2 재부팅 시 Agent 연결이 끊기므로, 서비스로 등록하는 작업이 필요하다.

agent 에서 /etc/systemd/system 경로에 jenkins-agent.service 파일을 생성해서 아래와 같이 작성한다. {} 처리 되어 있는 부분은 자신의 정보를 넣어야 한다.

[Unit]
Description=Jenkins Agent
After=network.target

[Service]
User=ec2-user
WorkingDirectory=/home/{user-name}/jenkins
ExecStart=/usr/bin/java -jar /home/{user-name}/jenkins/agent.jar \
  -jnlpUrl http://{controller-ip}:8080/computer/{node-name}/slave-agent.jnlp \
  -secret {secret} \
  -workDir "/home/{user-name}/jenkins"
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable jenkins-agent
sudo systemctl start jenkins-agent

Agent 에서 Job 실행 확인

아주 간단하게 Job을 만들고 실행해서, Agent 에서 잘 동작하는지 확인해보았다.

메인 화면 좌측에서 [새로운 Item] 버튼을 누르면 아래와 같은 화면이 나오고, 이름을 입력하고 item type을 ‘Pipeline’을 선택했다. 그 다음엔 OK 버튼을 눌렀다.

Definition 섹션에서 Script 영역을 확인할 수 있다. 오른쪽에 try sample pipeline… 옵션을 클릭하여, Hello World 를 클릭하면 다음과 같이 스크립트가 자동으로 들어간다. 이후 Save 버튼을 눌러 생성한다.

목록에서 오른쪽 초록색 재생 아이콘을 누르면 왼쪽에 빌드가 진행 중인 것을 볼 수 있다. 또한 해당 Job Name을 클릭해서 들어가면 빌드 기록들을 볼 수 있다.

Running on {agent-name} 을 볼 수 있다.

마무리 하며

Controller와 Agent 모두 EC2 인스턴스로 올리고 설치하고 연결까지 끝내고, 테스트까지 끝마쳤다. 다음은 실제로 빌드하며 마무리 할 예정이다.