[Jenkins] 실무 최악의 Jenkins 장애 대처 Best 3

길고 길었던 [Jenkins 실무 완벽 가이드] 40부작 대장정의 마지막 장에 오신 것을 환영합니다! 그동안 우리는 도커(Docker) 띄우기부터 파이프라인 문법, 보안, 분산 아키텍처까지 젠킨스의 모든 찬란한 기능들을 완벽히 마스터했습니다. 여러분은 이제 회사에서 "CI/CD 마스터"라는 칭호를 얻었을 것입니다. 하지만 인프라 엔지니어의 진짜 실력은 평화로울 때가 아니라, 모두가 퇴근한 금요일 밤 11시에 시스템이 완전히 먹통이 되었을 때 어떻게 응급 복구를 해내느냐에서 판가름 납니다. 수년간 수백 대의 젠킨스 서버를 운영하며 필자가 피눈물을 흘리며 겪었던 가장 끔찍하고 빈번한 젠킨스 장애 3가지와, 그 장애를 3분 만에 진압하는 '응급 처치(Troubleshooting) 노하우'를 다뤄보겠습니다.

💣 장애 1순위: "No space left on device" (디스크 풀)

증상: 젠킨스 UI 접속 시 HTTP 500 에러 창만 덩그러니 뜨거나, 모든 파이프라인이 시작하자마자 java.io.IOException: No space left on device 에러를 뿜으며 즉사합니다.

원인: 32단계에서 배운 Discard Old Builds를 설정하지 않아 낡은 아티팩트가 가득 차거나, 도커 기반 빌드를 너무 많이 돌려서 호스트 리눅스 서버에 <단말기 없는 찌꺼기 도커 이미지(Dangling Images)>가 수십 기가바이트(GB) 쌓였기 때문입니다.

응급 복구(Troubleshooting): 절대 당황하지 말고 SSH로 서버에 접속합니다. 다음 두 줄의 터미널 명령어를 날리면 5분 안에 디스크 50%가 즉각 확보되고 젠킨스가 숨을 쉬기 시작합니다.

# 1. 젠킨스 Workspace에 남겨진 30일 이상 된 오래된 임시 파일들을 강제로 모조리 찾아 삭제합니다.
find /var/jenkins_home/workspace/ -type f -mtime +30 -exec rm -f {} \;

# 2. 도커가 쓰레기통에 남겨둔 이름 없는(Dangling) 이미지와 캐시를 싹 비웁니다.
docker system prune -a --volumes -f

💥 장애 2순위: java.lang.OutOfMemoryError (OOM 데스매치)

증상: 젠킨스가 미친 듯이 느려지다가 브라우저 무한 로딩이 걸립니다. 로그를 까보면 OutOfMemoryError: Java heap space라는 섬뜩한 문구가 찍혀있고 젠킨스 프로세스 자체가 리눅스 OS에 의해 강제 킬(Kill) 당해 있습니다.

원인: 젠킨스는 기본적으로 자바(Java) 애플리케이션입니다. 1만 줄이 넘어가는 엄청난 빌드 로그 텍스트를 파이프라인 UI에 뿌려주려고 힙(Heap) 메모리에 전부 밀어 넣거나, 수백 개의 git fetch가 동시에 발생하면 메모리가 폭주합니다.

응급 복구(Troubleshooting): 젠킨스 컨테이너를 띄우는 docker-compose.yml 또는 구동 스크립트에 자바 가비지 컬렉터(GC) 튜닝과 메모리 상한선(Xmx) 환경변수를 넉넉히 때려 박고 재시작해야 합니다.

// docker-compose.yml 예시
environment:
  # 기본 메모리가 모자랍니다. Heap 메모리를 4GB(4096m)로 뻥튀기하고, 
  # 일시 정지(Stop-the-world) 시간이 짧은 G1GC 가비지 컬렉터를 강제로 주입합니다.
  - JAVA_OPTS=-Xmx4096m -Xms2048m -XX:+UseG1GC -XX:+ExplicitGCInvokesConcurrent

☠️ 장애 3순위: 플러그인 의존성 지옥 (Update Hell)

증상: [플러그인 관리] 메뉴에 뜬 빨간색 "업데이트 가능" 버튼들이 거슬려서 무심코 [모두 업데이트]를 누르고 젠킨스를 재시작했습니다. 그런데 젠킨스가 켜지다 말고 Failed to load plugin: workflow-api 같은 에러를 수십 개 뱉으며 영원히 부팅되지 않습니다.

원인: A 플러그인을 최신 버전으로 올렸는데, 이 녀석이 B 플러그인의 구버전과 호환되지 않아 서로 충돌하며 코어 엔진을 박살 낸 것입니다. 실무 젠킨스 운영의 가장 끔찍한 금기어는 "묻지마 플러그인 업데이트"입니다.

응급 복구(Troubleshooting): UI에 접속이 안 되니 터미널로 뚫고 들어가서 수동으로 찌그러진 플러그인을 뽑아내야 합니다.

# 1. 젠킨스의 플러그인이 모여있는 폴더로 진입
cd /var/jenkins_home/plugins/

# 2. 에러 로그에서 말썽을 일으킨 플러그인(예: workflow-api)의 .jpi (또는 .hpi) 파일을 찾아 강제 백업/삭제
mv workflow-api.jpi workflow-api.jpi.bak
mv workflow-api.jpi.disabled workflow-api.jpi.bak.disabled

# 3. 젠킨스 컨테이너 강제 재시작
docker restart jenkins

이렇게 수동으로 문제의 플러그인을 비활성화(제거)하면 간신히 젠킨스 UI가 되살아납니다. 이후 호환되는 안정화(Stable) 버전의 플러그인을 찾아 수동으로 .hpi 파일을 업로드하여 설치해야 합니다.

🏆 에필로그: 진정한 CI/CD 장인으로의 길

축하합니다! 디스크 풀을 정리하고, OOM을 잡고, 플러그인 지옥에서 살아 돌아온 당신은 이제 어떠한 장애에도 굴하지 않는 강철의 멘탈을 가진 진정한 데브옵스/CI-CD 엔지니어입니다.