GitLab VM 장애 복구: NBD 마운트와 백업 복원으로 서비스 재구축하기

Trouble Shooting

GitLab VM 장애 복구: NBD 마운트와 백업 복원으로 서비스 재구축하기

Somaz 2025. 12. 10. 06:58

728x90

Overview

GitLab VM이 갑작스럽게 rescue 모드로 돌입하면서 서비스가 중단되는 치명적인 장애가 발생했다. GRUB 복구도 불가능한 상황에서, 다행히 중요한 데이터들은 NFS에 저장되어 있어 완전한 데이터 손실은 피할 수 있었다.

이번 포스팅에서는 NBD(Network Block Device)를 활용해 손상된 VM의 qcow2 디스크를 마운트하고, 백업 데이터를 추출한 후 새로운 환경에서 GitLab을 복구하는 전체 과정을 다룬다. 또한 복구 과정에서 발생한 Prometheus 권한 문제와 GitLab 버전 다운그레이드 방법도 함께 소개한다.

문제 상황 분석

주요 증상

GitLab VM이 rescue 모드로 부팅됨
GRUB 복구 시도 실패
시스템 부팅 불가 상태

긍정적 요소

핵심 데이터가 NFS에 안전하게 보관됨
VM 디스크 파일(qcow2)에 접근 가능

복구 과정

1. NBD를 이용한 GitLab VM 디스크 마운트

손상된 VM에 직접 접근할 수 없는 상황에서 NBD(Network Block Device)를 활용해 qcow2 디스크 이미지를 마운트했다.

# NBD 모듈 로드
modprobe nbd max_part=8

# GitLab VM의 qcow2 디스크를 NBD 디바이스로 연결
qemu-nbd --connect=/dev/nbd0 /path/to/gitlab-vm.qcow2

2. 파티션 확인 및 마운트

# 연결된 디스크의 파티션 확인
fdisk -l /dev/nbd0

# GitLab 루트 파티션 마운트 (보통 /dev/nbd0p1)
mkdir -p /mnt/gitlab-root
mount /dev/nbd0p1 /mnt/gitlab-root

3. 백업 데이터 추출

마운트된 디스크에서 GitLab 관련 중요 데이터들을 체계적으로 추출했다.

# GitLab 설정 백업 (8.7M)
cp -r /mnt/gitlab-root/etc/gitlab /tmp/gitlab-config-backup

# GitLab 데이터 백업 (1.6G) - 주요 데이터베이스와 리포지토리
cp -r /mnt/gitlab-root/var/opt/gitlab /tmp/gitlab-data-backup

# 홈 디렉토리 백업 (88K)
cp -r /mnt/gitlab-root/home /tmp/home-backup

추출된 데이터 구성 예시

gitlab-config-backup (8.7M): `/etc/gitlab/` - GitLab 설정 파일들
gitlab-data-backup (1.6G): `/var/opt/gitlab/` - 데이터베이스, 리포지토리, 로그 등
home-backup (88K): `/home/` - 사용자 홈 디렉토리

4. 마운트 해제 및 정리

# 마운트 해제
umount /mnt/gitlab-root

# NBD 연결 해제
qemu-nbd --disconnect /dev/nbd0

5. GitLab 백업 복원

새로운 환경에서 추출한 백업을 활용해 GitLab을 복원했다.

sudo gitlab-backup restore BACKUP=1754284731_2025_08_04_18.1.1

6. Prometheus 권한 문제 해결

복구 과정에서 Prometheus 서비스가 다음과 같은 권한 오류로 실패했다.

caller=query_logger.go:114 level=error component=activeQueryTracker 
msg="Error opening query log file" 
file=/mnt/nfs/gitlab/prometheus/data/queries.active 
err="open /mnt/nfs/gitlab/prometheus/data/queries.active: permission denied"
panic: Unable to create mmap-ed active query log

이 문제는 NFS 마운트된 디렉토리의 소유권 문제로 발생했으며, 다음 명령으로 해결했다.

sudo chown -R gitlab-prometheus:gitlab-prometheus /mnt/nfs/gitlab/prometheus/

7. GitLab 다운그레이드

기존버전이 18.1.1 이였고, 최신버전이 18.2.1 이였는데 생각없이 최신버전으로 다운받았다가 백업이 동작하지 않아서 GitLab 버전을 다운그레이드해야 했다. 자동 백업을 건너뛰고 특정 버전으로 강제 다운그레이드를 수행했다.

# 자동 백업 스킵 설정
touch /etc/gitlab/skip-auto-backup

# 특정 버전으로 다운그레이드
sudo apt-get install -y gitlab-ce=18.1.1-ce.0 --allow-downgrades

교훈과 개선 사항

1. 모니터링 강화

Prometheus와 같은 모니터링 서비스의 상태를 더욱 면밀히 관찰
NFS 권한 문제에 대한 사전 점검 체계 구축

2. 백업 전략 개선

정기적인 전체 시스템 백업 외에 설정 파일 별도 백업
복구 테스트를 통한 백업 데이터 유효성 검증

3. 버전 관리 정책

GitLab 업그레이드 전 충분한 테스트 환경 검증
롤백 계획 수립 및 다운그레이드 절차 문서화

4. 인프라 아키텍처

단일 VM 의존도 감소를 위한 고가용성 구성 검토
컨테이너 기반 배포로의 전환 고려

마무리

이번 GitLab 장애는 예상치 못한 시스템 실패 상황에서 NBD를 활용한 디스크 마운트 기법의 유용성을 확인할 수 있는 사례였다. GRUB 복구가 불가능한 극한 상황에서도 qcow2 디스크에서 직접 데이터를 추출할 수 있다는 점은 가상화 환경의 큰 장점 중 하나다.

특히 NFS에 데이터를 분산 저장한 아키텍처 덕분에 완전한 데이터 손실을 피할 수 있었지만, 동시에 권한 관리의 복잡성도 경험했다. Prometheus 권한 문제처럼 세밀한 부분까지 고려한 운영 절차가 필요함을 다시 한번 깨달았다.

앞으로는 더욱 견고한 백업 전략과 모니터링 체계를 구축하고, 컨테이너 기반의 더 유연한 아키텍처로 전환을 검토해볼 계획이다. 장애는 피할 수 없지만, 철저한 준비와 체계적인 복구 절차로 서비스 중단 시간을 최소화할 수 있다는 교훈을 얻은 값진 경험이었다.

Reference

NFS 권한 문제 관련 자료

Prometheus NFS 권한 문제 관련 자료

GitLab 관련 공식 문서

NBD와 qcow2 관련 자료

728x90

저작자표시 비영리 변경금지 (새창열림)

'Trouble Shooting' 카테고리의 다른 글

Kubernetes Redis 클러스터 장애 처리 및 복구 가이드 (1)	2026.01.13
NVIDIA Driver/Library Version Mismatch 오류 해결하기 (0)	2025.09.17
Terraform 상태 관리 오류 해결 완전 가이드 (0)	2025.09.02
Kubernetes Pod 재시작 시 에러 해결 (0)	2025.08.20
DB Connection Error (ECONNRESET) 문제 해결 (2)	2025.08.06

현재글GitLab VM 장애 복구: NBD 마운트와 백업 복원으로 서비스 재구축하기

Somaz의 IT 공부 일지