[TroubleShooting] Jenkins 장애 대응

Date

2025/11/18

작성일: 2025.11.18

장애 유형: EBS I/O 성능 고갈로 인한 Jenkins Hang 상태

1. 개요

본 문서는 2025.11.17 23:50 ~ 00:10 발생한 Jenkins 중단 장애에 대해 장애 발생 이후 수행된 조치와 성능 개선 결과를 기록한 보고서이다.

장애의 근본 원인은 Jenkins EC2 인스턴스가 사용하는 EBS(gp2)의

BurstBalance 고갈 → I/O Stall → OS Hang

이었으며, 이에 따라 Jenkins UI, SSH, Docker 모두 응답하지 못하는 상태가 발생했다.

이 문서는 장애 분석 요약 → 수행한 조치 → 성능 비교 순서로 구성한다.

2. 장애 원인 요약

Root Cause

•

Jenkins EC2의 Docker Root(/var/lib/docker) 가 EC2의 주 EBS 볼륨(gp2) 에 위치

•

Docker build & image layer 작업 중 ReadOps/WriteOps 폭증

•

gp2 특성상 BurstCredit 고갈 → BurstBalance 0%

•

VolumeTotalReadTime/WriteTime 최대 119초, QueueLength 급증

→ 디스크 응답이 오지 않아 OS 레벨에서 block

•

결과적으로:

◦

Jenkins UI: 504 Gateway Timeout

◦

SSH: 접속 불가

◦

Docker: build 중단

◦

EC2 Status Check: 정상 (하드웨어/네트워크 문제는 아님)

주 원인: 스토리지 I/O 병목(EBS 성능 부족)

BurstBalance

VolumeTotalReadTime

VolumeQueueLength

3. 기존 볼륨 구성 vs 변경 후 볼륨 구성

기존 구조는 OS(EBS 20GB) 위에 Docker가 공존하여 Docker build 작업이 전체 파일 시스템에 병목 현상을 가져오는 구조였다. 이를 다음과 같이 개선하였다.

Before

•

Root EBS (gp2, 20GB)

◦

OS

◦

/var/lib/docker (Docker 이미지/레이어) → 장애 지점

•

Jenkins Data EBS (gp2, 20GB)

◦

/var/jenkins_home (Job 설정, 플러그인, 빌드 히스토리 등 Jenkins state)

◦

Jenkins 데이터 보존용 볼륨

After

•

Root EBS (gp2, 20GB)

•

Jenkins Data EBS (gp3, 50GB)

◦

/var/jenkins_home (변경 없음)

•

새 Docker 전용 EBS (gp3, 50GB, 6000 IOPS, Throughput 125MB/s)

◦

/var/lib/docker 전용

4. 장애 대응 및 조치 내역

장애 발생 직후 Jenkins의 I/O 병목을 해결하기 위해 다음과 같은 조치를 수행하였다.

4.1 Docker 전용 EBS(gp3) 추가 및 Attach

1) Terraform: Docker 전용 EBS 생성

resource "aws_ebs_volume" "docker" {
  count             = length(local.docker_existing_ids) > 0 ? 0 : 1
  availability_zone = var.az

  size       = var.docker_ebs_size  # 50
  type       = var.docker_ebs_type  # gp3
  iops       = var.docker_ebs_iops  # 6000
  throughput = var.docker_ebs_throughput  # 125

  tags = {
    Name = "${var.prefix}-docker-data"
  }

  lifecycle {
    prevent_destroy = true
  }
}
HCL
복사

2) Terraform: EC2에 Docker 볼륨 attach

resource "aws_volume_attachment" "docker" {
  device_name  = "/dev/sdg"
  volume_id    = local.docker_volume_id
  instance_id  = aws_instance.this.id
  force_detach = true

  lifecycle {
    ignore_changes = [volume_id]
  }
}
HCL
복사

4.2 Userdata를 통한 /var/lib/docker 마이그레이션

부팅 시 자동으로

Docker 전용 EBS를 EXT4로 포맷

/var/lib/docker에 마운트

/etc/fstab에 등록

Docker 서비스 재시작

1) Userdata (부분 발췌)

DOCKER_VOL_ID="${docker_volume_id}"
DOCKER_MNT="/var/lib/docker"
DOCKER_DEVICE=""

for i in $(seq 1 120); do
  if DOCKER_DEVICE=$(find_nvme_device "$DOCKER_VOL_ID"); then
    break
  fi
  echo "Retry $i/120: Docker volume not found..."
  sleep 2
done

# 1) 포맷
if ! blkid "$DOCKER_DEVICE" >/dev/null 2>&1; then
  mkfs.ext4 "$DOCKER_DEVICE"
fi

# 2) docker 중지
systemctl stop docker || true

# 3) 마운트 및 fstab 등록
mkdir -p "$DOCKER_MNT"
if ! mount | grep -q "$DOCKER_MNT"; then
	mount "$DOCKER_DEVICE" "$DOCKER_MNT"
	echo "$DOCKER_DEVICE $DOCKER_MNT ext4 defaults,nofail 0 2" >> /etc/fstab
fi

# 4) docker 재시작
systemctl start docker
Shell
복사

이로써 Docker I/O는 전부 Docker EBS(gp3)로만 가고, Root 디스크 및 Jenkins Data 디스크에는 거의 영향이 가지 않게 된다.

4.3 Jenkins Data 볼륨 유지

•

기존의 Jenkins Data 볼륨(/mnt/jenkins_data → 컨테이너 내부 /var/jenkins_home)은

장애 이전부터 존재하던 볼륨이며, 이번 작업에서도 포맷/삭제/변경 없이 그대로 유지하였다.

•

Userdata에서는 Jenkins Volume도 마찬가지로 NVMe 매핑 후 /mnt/jenkins_data에 마운트만 수행한다.

따라서 Jenkins Job 설정, 플러그인, 빌드 히스토리 등은 그대로 유지되고, 이번 조치로 인해 Jenkins 데이터 손실은 발생하지 않았다.

5. 성능 및 안정성 개선 결과

5.1 EBS 지표

지표	장애 당시 (gp2 + Docker 공유)	조치 후 (Docker 전용 gp3)	개선
VolumeTotalReadTime	최대 119초	평균 5~9ms 수준	약 13,000배 개선
VolumeTotalWriteTime	수십 초	몇 ms 수준	정상 범위
VolumeQueueLength	10~30	0 ~ 0.2	대기열 해소
BurstBalance	0%	gp3는 크레딧 개념 없음	구조적 해결
ReadOps/WriteOps	급격한 스파이크 + 긴 Tail	짧은 스파이크 후 바로 0	I/O 정체 해소

VolumeReadBytes / WriteBytes

VolumeReadOps / WriteOps

VolumeTotalReadTime / WriteTime

VolumeQueueLength

5.2 Jenkins Pipeline 성능 개선

항목	변경 전	변경 후
Docker Build & Push 단계	장애 발생으로 측정 불가	약 1분 2초
전체 Pipeline 실행 시간	장애 발생으로 측정 불가	1분 35초 내외 안정적으로 완료
Jenkins UI 반응	빌드 중 매우 느림 / 타임아웃	빌드 중에도 UI 즉시 응답

Before

After

6. 결론

•

Jenkins 장애의 원인은 EC2 인스턴스나 Jenkins Data Volume이 아니라, 
Docker가 공유 Root EBS(gp2)에 몰린 구조였다.

•

이미 존재하던 Jenkins Data 전용 볼륨은 그대로 유지하면서,

•

Docker 전용 gp3 EBS를 추가하고 /var/lib/docker를 분리함으로써,

◦

I/O 병목이 완전히 제거되었고

◦

Jenkins Pipeline의 안정성과 성능이 모두 크게 향상되었다.

이번 조치는

“빌드 트래픽은 Docker 볼륨으로, Jenkins 상태는 Data 볼륨으로, OS는 Root 볼륨으로”

라는 명확한 역할 분리를 통해, 스토리지 레벨에서 Jenkins CI의 안정성을 높인 작업으로 평가할 수 있다.

[TroubleShooting] Jenkins 장애 대응

작성일: 2025.11.18

관련 서비스: Jenkins CI / Docker Build Pipeline

장애 유형: EBS I/O 성능 고갈로 인한 Jenkins Hang 상태

관련 장애 보고서: [TroubleShooting] Jenkins 장애 분석

1. 개요

2. 장애 원인 요약

Root Cause

주 원인: 스토리지 I/O 병목(EBS 성능 부족)

3. 기존 볼륨 구성 vs 변경 후 볼륨 구성

Before

After

4. 장애 대응 및 조치 내역

4.1 Docker 전용 EBS(gp3) 추가 및 Attach

1) Terraform: Docker 전용 EBS 생성

2) Terraform: EC2에 Docker 볼륨 attach

4.2 Userdata를 통한 /var/lib/docker 마이그레이션

1) Userdata (부분 발췌)

4.3 Jenkins Data 볼륨 유지

5. 성능 및 안정성 개선 결과

5.1 EBS 지표

VolumeReadBytes / WriteBytes

VolumeReadOps / WriteOps

VolumeTotalReadTime / WriteTime

VolumeQueueLength

5.2 Jenkins Pipeline 성능 개선

Before

After

6. 결론