콘텐츠로 이동

GitLab 데이터 경로 준비 및 Bind Mount

  • GitLab 설치 전에 수행해야 하는 데이터 경로 준비 작업을 정의함.
  • GitLab 데이터를 OS 영역과 분리하고, 데이터 종류별로 독립 관리하기 위한 표준 구성임.

1. 개요

GitLab은 기본적으로 다음 경로를 사용함.

  • Data: /var/opt/gitlab
  • Log: /var/log/gitlab
  • Config: /etc/gitlab

운영 환경에서는 다음과 같이 별도 경로로 분리하는 것을 권장함.

/gitlab
 ├── data       # /var/opt/gitlab
 ├── logs       # /var/log/gitlab
 ├── packages   # /var/opt/gitlab/gitlab-rails/shared/packages
 ├── artifacts  # /var/opt/gitlab/gitlab-rails/shared/artifacts
 ├── uploads    # /var/opt/gitlab/gitlab-rails/uploads
 ├── lfs        # /var/opt/gitlab/gitlab-rails/shared/lfs-objects
 └── backups    # /var/opt/gitlab/backups, backup_path
  • data: Git repository 및 GitLab 주요 데이터
  • logs: 서비스 로그
  • packages: Package Registry 저장소
  • artifacts: CI/CD job artifacts 저장소
  • uploads: issue, MR, wiki 등 사용자 업로드 저장소
  • lfs: Git LFS 저장소
  • backups: 백업 파일

2. 수행 시점

본 작업은 GitLab 설치 전에 수행하는 것을 기준으로 함.

설치 이후 경로를 변경할 경우 다음과 같은 문제가 발생할 수 있음.

  • 기존 데이터 이동 필요
  • 서비스 중단 발생
  • 설정 복잡도 증가
  • 경로별 마운트 정합성 검증 필요

3. 설치 디스크 또는 파티션 결정 및 디렉터리 준비

GitLab 설치 전에 /gitlab 을 어느 디스크 또는 파티션에 둘지 먼저 결정해야 함. 이 결정에 따라 이후 모든 경로와 마운트 구성이 달라짐.

디스크 또는 파티션 현황 확인:

sudo lsblk

선택 기준:

구성 방식 설명 권장 대상
OS 디스크 또는 파티션 내 LVM 별도 디스크 없이 OS 내부에 구성 소규모 / 테스트
별도 디스크 또는 파티션 분리 /gitlab 전용 디스크 또는 파티션을 마운트 후 구성 운영 환경 권장

별도 디스크 또는 파티션 사용 시 (해당하는 경우만 수행)

⚠️ 해당 디스크 또는 파티션 마운트가 bind mount보다 반드시 먼저 적용되어야 함. 순서가 잘못되면 부팅 시 bind mount가 빈 경로에 걸려 GitLab 데이터가 유실 또는 데이터가 잘못된 위치에 기록되어 기존 데이터가 가려질 수 있음.

# ⚠️ 아래 DISK_OR_PARTITION 변수를 본인 환경에 맞게 먼저 수정 (lsblk 결과 참고)
# 예: /dev/sda, /dev/sdb, /dev/nvme1n1 등 환경마다 다름
DISK_OR_PARTITION=/dev/sda

# 필요시! 신규 디스크 또는 파티션 포맷 (최초 1회, 기존 데이터 삭제됨 주의)
# sudo mkfs.xfs ${DISK_OR_PARTITION}

# 마운트
sudo mkdir -p /gitlab
sudo mount ${DISK_OR_PARTITION} /gitlab

# UUID 확인 (fstab 등록용)
sudo blkid ${DISK_OR_PARTITION}

디렉터리 생성 (모든 환경 공통)

  • 아래 내용은 설치 전 기본 경로 보호 설정임
  • /gitlab 상위 경로는 root:root 755 기준으로 유지함
  • /gitlab/backups 는 gitlab_rails['backup_path'] 로 사용되므로 git:git 700 권한을 명시적으로 적용함
  • GitLab 백업 프로세스가 /gitlab/backups 에 백업 파일을 생성할 수 있어야 함
sudo mkdir -p /gitlab/{data,logs,packages,artifacts,uploads,lfs,backups}
sudo chown -R root:root /gitlab
sudo chmod -R 755 /gitlab

# GitLab backup_path 전용 권한
sudo chown git:git /gitlab/backups
sudo chmod 700 /gitlab/backups

4. mount 대상 생성

  • GitLab 설치 전 bind mount를 적용하기 위해 source 디렉터리와 하위 mount 대상 구조를 사전 생성함
  • /var/opt/gitlab 하위 경로는 이후 /gitlab/data 가 mount 되므로 실제 대상 구조는 /gitlab/data 아래에 준비해야 함
# 상위 mount 대상 (모든 환경 공통)
sudo mkdir -p /var/opt/gitlab
sudo mkdir -p /var/log/gitlab

# /var/opt/gitlab mount 이후 사용할 하위 경로를 source 쪽에 미리 생성
sudo mkdir -p /gitlab/data/backups
sudo mkdir -p /gitlab/data/gitlab-rails/shared/packages
sudo mkdir -p /gitlab/data/gitlab-rails/shared/artifacts
sudo mkdir -p /gitlab/data/gitlab-rails/uploads
sudo mkdir -p /gitlab/data/gitlab-rails/shared/lfs-objects

5. bind mount 적용

  • bind mount는 상위 경로 → 하위 경로 순으로 적용함
sudo mount --bind /gitlab/data /var/opt/gitlab
sudo mount --bind /gitlab/logs /var/log/gitlab
sudo mount --bind /gitlab/packages /var/opt/gitlab/gitlab-rails/shared/packages
sudo mount --bind /gitlab/artifacts /var/opt/gitlab/gitlab-rails/shared/artifacts
sudo mount --bind /gitlab/uploads /var/opt/gitlab/gitlab-rails/uploads
sudo mount --bind /gitlab/lfs /var/opt/gitlab/gitlab-rails/shared/lfs-objects
sudo mount --bind /gitlab/backups /var/opt/gitlab/backups

6. 영구 적용 (/etc/fstab)

  • nofail 옵션 사용 시 mount 실패 상태에서도 부팅이 진행되므로, 부팅 후 mount 상태를 반드시 확인해야 함
  • systemd는 fstab을 병렬로 처리할 수 있으므로 x-systemd.requires 로 의존성을 명시해야 함
sudo vi /etc/fstab

OS 디스크 또는 파티션 내 LVM 사용 시:

/gitlab/data        /var/opt/gitlab                                 none   bind,nofail                                   0 0
/gitlab/logs        /var/log/gitlab                                 none   bind,nofail                                   0 0

/gitlab/packages    /var/opt/gitlab/gitlab-rails/shared/packages    none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0
/gitlab/artifacts   /var/opt/gitlab/gitlab-rails/shared/artifacts   none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0
/gitlab/uploads     /var/opt/gitlab/gitlab-rails/uploads            none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0
/gitlab/lfs         /var/opt/gitlab/gitlab-rails/shared/lfs-objects none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0
/gitlab/backups     /var/opt/gitlab/backups                         none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0

별도 디스크 또는 파티션 사용 시 (UUID는 blkid 결과로 대체):

# 반드시 bind mount보다 위에 위치해야 함
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   /gitlab   xfs   defaults,noatime   0 0

/gitlab/data        /var/opt/gitlab                                 none   bind,nofail,x-systemd.requires=/gitlab,x-systemd.after=/gitlab        0 0
/gitlab/logs        /var/log/gitlab                                 none   bind,nofail,x-systemd.requires=/gitlab,x-systemd.after=/gitlab        0 0

/gitlab/packages    /var/opt/gitlab/gitlab-rails/shared/packages    none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0
/gitlab/artifacts   /var/opt/gitlab/gitlab-rails/shared/artifacts   none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0
/gitlab/uploads     /var/opt/gitlab/gitlab-rails/uploads            none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0
/gitlab/lfs         /var/opt/gitlab/gitlab-rails/shared/lfs-objects none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0
/gitlab/backups     /var/opt/gitlab/backups                         none   bind,nofail,x-systemd.requires=/gitlab/data,x-systemd.after=/gitlab/data   0 0

sudo systemctl daemon-reload
sudo mount -a

7. mount 확인

# mount 상태 확인
mount | grep gitlab
findmnt /var/opt/gitlab
findmnt /var/log/gitlab
findmnt /var/opt/gitlab/gitlab-rails/shared/packages
findmnt /var/opt/gitlab/gitlab-rails/shared/artifacts
findmnt /var/opt/gitlab/gitlab-rails/uploads
findmnt /var/opt/gitlab/gitlab-rails/shared/lfs-objects
findmnt /var/opt/gitlab/backups
findmnt | grep gitlab

# 디렉터리 구조 확인
sudo ls -ld /gitlab /var/opt/gitlab /var/log/gitlab
cat /etc/fstab | grep gitlab

8. 동작 테스트

# data 영역 테스트
sudo touch /var/opt/gitlab/testfile
sudo ls /gitlab/data
sudo rm /gitlab/data/testfile

# logs 영역 테스트
sudo touch /var/log/gitlab/testfile
sudo ls /gitlab/logs
sudo rm /gitlab/logs/testfile

# packages 영역 테스트
sudo touch /var/opt/gitlab/gitlab-rails/shared/packages/testfile
sudo ls /gitlab/packages
sudo rm /gitlab/packages/testfile

# artifacts 영역 테스트
sudo touch /var/opt/gitlab/gitlab-rails/shared/artifacts/testfile
sudo ls /gitlab/artifacts
sudo rm /gitlab/artifacts/testfile

# uploads 영역 테스트
sudo touch /var/opt/gitlab/gitlab-rails/uploads/testfile
sudo ls /gitlab/uploads
sudo rm /gitlab/uploads/testfile

# lfs 영역 테스트
sudo touch /var/opt/gitlab/gitlab-rails/shared/lfs-objects/testfile
sudo ls /gitlab/lfs
sudo rm /gitlab/lfs/testfile

# backups 영역 테스트
sudo touch /var/opt/gitlab/backups/testfile
sudo ls /gitlab/backups
sudo rm /gitlab/backups/testfile

9. SELinux 주의사항

현재 프로젝트 기준처럼 /gitlab/data, /gitlab/logs, /gitlab/packages, /gitlab/artifacts, /gitlab/uploads, /gitlab/lfs, /gitlab/backups 를 각 GitLab 기본 경로에 bind mount 하여 사용하는 구조에서는, SELinux Enforcing 환경이라도 추가 context 설정 없이 동작하는 경우가 많아 설정이 항상 필요한 것은 아님. GitLab 공식 패키지 기준 기본 경로를 그대로 유지하는 bind mount 구조에서는 별도 설정 없이 동작하는 것이 일반적임.

단, 다음 상황에서는 SELinux 문제 발생 가능:

  • 커스텀 경로 직접 사용 시
  • context가 변경된 경우
  • 서비스 접근 실패(AVC 발생)

이 경우에만 아래를 확인함.

sudo sestatus
sudo ausearch -m avc -ts recent

필요 시 참고:

sudo restorecon -Rv /gitlab
sudo ls -Zd /gitlab

10. 주의사항 (중요)

  • /gitlab 디렉터리는 반드시 충분한 디스크 또는 파티션 용량을 확보할 것
  • bind mount는 GitLab 설치 전에 적용해야 함
  • mount 누락 시 GitLab 데이터가 /var/opt/gitlab에 직접 저장됨 (복구 어려움)
  • /etc/fstab 설정 오류 시 부팅 실패 가능 → 반드시 mount -a 검증 수행
  • 상위 경로 mount 후 하위 경로를 순서대로 mount 해야 함

11. 서버 이전 및 데이터 이동 전략

본 구조는 GitLab 데이터 영역을 분리하여 다음과 같은 다양한 이전 시나리오를 지원함.

⚠️ 반드시 GitLab 서비스 중지 후 수행

sudo gitlab-ctl stop

11.1 전체 GitLab 이전

rsync -avz /gitlab/ new-server:/gitlab/
rsync -avz /etc/gitlab/ new-server:/etc/gitlab/

11.2 repository(data)만 이전

rsync -avz /gitlab/data/ new-server:/gitlab/data/

11.3 로그(logs)만 이전

rsync -avz /gitlab/logs/ new-server:/gitlab/logs/

11.4 Package Registry(packages)만 이전

rsync -avz /gitlab/packages/ new-server:/gitlab/packages/

11.5 artifacts만 이전

rsync -avz /gitlab/artifacts/ new-server:/gitlab/artifacts/

11.6 uploads만 이전

rsync -avz /gitlab/uploads/ new-server:/gitlab/uploads/

11.7 lfs만 이전

rsync -avz /gitlab/lfs/ new-server:/gitlab/lfs/

11.8 backups만 이전

rsync -avz /gitlab/backups/ new-server:/gitlab/backups/

11.9 운영 기준

  • 각 디렉터리는 독립적으로 이동 가능해야 함
  • mount 구조를 유지하면 부분 이전이 가능함
  • 이전 시 GitLab 서비스 중지 상태에서 수행
  • 데이터 이동 후 mount 및 경로 정합성 반드시 검증
  • --delete 옵션 사용 시 대상 서버의 기존 데이터가 삭제되므로 사용 전 반드시 확인
  • 서버 간 UID/GID 불일치 주의: 새 서버에서 GitLab을 먼저 설치하여 git 유저를 생성한 후 rsync 수행하거나, rsync 완료 후 sudo gitlab-ctl reconfigure 를 실행하여 권한을 재설정할 것

12. 요약

  • bind mount를 통해 기본 경로와 연결함
  • 해당 작업은 반드시 설치 전에 수행해야 함
  • 이 구조로 두면 이후 서버 이전 및 저장소 분리가 쉬워짐.