Haru Utils

GITLAB AIRGAP

폐쇄망 GitLab 인플레이스 버전 업그레이드 (Rocky Linux el8·el9)

외부 인터넷이 차단된 폐쇄망 환경에서 U-Cloud VM 스냅샷과 설정 백업을 사전에 확보하고, Rocky Linux 8·9 아키텍처에 맞는 Omnibus RPM 패키지를 단계별 경유 정류장(Upgrade Stops)과 PostgreSQL 내장 DB 업그레이드, 배치 백그라운드 마이그레이션(BBM) 0건 검증을 거쳐 안전하게 인플레이스로 판올림합니다.
GitLab 인플레이스 업그레이드GitLab 폐쇄망 업그레이드GitLab upgrade pathgitlab-ctl pg-upgradebatched background migrationsRocky Linux GitLab RPMU-Cloud VM 스냅샷 롤백
지원 환경Rocky Linux 8 (x86_64, el8) 또는 Rocky Linux 9 (x86_64, el9)
예상 시간약 180분
난이도고급
검토일2026-08-28

BEFORE YOU START

시작 전에 준비하세요

01

Rocky Linux 정확한 메이저 버전(el8 vs el9) 및 현재 GitLab 패키지 버전(16.11.1) 사전 확인

02

사전 다운로드한 필수 경유 버전 RPM 패키지(16.11.10, 17.3.8, 17.5.4, 17.8.4, 17.11.7, 18.2.3, 18.5.2, 18.11.0, 19.2.8)와 SHA256 체크섬

03

서버 /var/opt/gitlab 여유 디스크 25GB 이상, root/sudo 권한, GitLab Admin 웹 계정, tmux 또는 screen

04

작업 직전 일관성 있는 복구를 보장하는 U-Cloud VM 스냅샷 생성 및 롤백 절차 승인

권장 대상 인터넷이 격리된 폐쇄망 서버에서 다운타임을 최소화하고 데이터 손실 없이 최신 취약점 패치 목표 버전까지 순차 인플레이스 업그레이드를 수행하려는 시스템 엔지니어·DevOps 운영자

FOLLOW THE RECIPE

8단계 구성·점검 레시피

1
확인시스템을 변경하지 않는 점검 단계

서버 환경·디스크 점검 및 작업 세션 보호

외부 인터넷이 격리된 폐쇄망 서버에서 OS 메이저 버전(el8 vs el9), GitLab 에디션, 파티션별 디스크 용량을 확인합니다. 특히 대용량 RPM(약 10GB+)과 PostgreSQL DB 복제 변환을 위해 /var/opt/gitlab 파티션에 최소 25GB 이상의 여유 공간이 필요하며, 작업 중 SSH 단절에 대비해 tmux/screen 세션 환경을 준비합니다.

OS 메이저 버전과 아키텍처 확인
cat /etc/redhat-release
uname -m
Rocky Linux release 8.x(el8)인지 9.x(el9)인지 반드시 확인하여 일치하는 RPM을 준비합니다.
파티션별 디스크 여유 공간 점검
df -hT / /var/opt/gitlab /tmp
/var/opt/gitlab 여유가 25GB 이상인지 확인합니다. /tmp가 12GB 미만이면 RPM 업로드 경로를 /var/opt/gitlab/upgrade_rpms로 지정해야 합니다.
현재 GitLab 패키지 및 전체 서비스 상태 확인
rpm -qa | grep gitlab
sudo gitlab-ctl status
현재 버전이 16.11.1-ce인지 확인하고 모든 프로세스가 run 상태인지 대조합니다.
SSH 세션 단절 방지용 터미널 멀티플렉서 실행
tmux new -s gitlab_upgrade || screen -S gitlab_upgrade
장시간 패키지 설치 및 DB 변환 중 네트워크 단절로 작업이 비정상 종료되는 것을 방지합니다.
  • Rocky Linux 메이저 버전이 el8인지 el9인지 정확히 식별했습니다.
  • /var/opt/gitlab 파티션의 여유 공간이 25GB 이상 확보되었습니다.
  • 현재 실행 중인 모든 GitLab 컴포넌트(gitaly, puma, postgresql, redis, sidekiq 등)가 run 상태입니다.
  • SSH 세션 단절에 대비해 tmux 또는 screen 세션 안에서 작업을 시작했습니다.
결과 읽기

OS 배포판 버전과 파티션 공간이 확인되면 폐쇄망 반입용 RPM 목록이 확정됩니다. /var/opt/gitlab 디스크 공간이 25GB 미만인 경우 볼륨 증설 후 진행해야 합니다.

다음 판단

기존 버전 잔여 백그라운드 마이그레이션 완료 여부를 점검하고 여유 파티션에 RPM을 반입합니다.

2
확인시스템을 변경하지 않는 점검 단계

잔여 마이그레이션 0건 확인 및 여유 파티션 RPM 무결성 검증

현재 16.11.1 버전에서 백그라운드 마이그레이션(BBM)이 모두 완료되었는지 확인합니다. 또한 외부 인터넷 PC에서 17.5.4를 포함한 모든 필수 경유 RPM을 다운로드한 후, 용량이 넉넉한 /var/opt/gitlab/upgrade_rpms 디렉터리로 SFTP 반입하여 체크섬을 검증합니다.

현재 버전(16.11.1) 백그라운드 마이그레이션 0건 확인
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean: All migrations finished'
미완료 작업이 없어야 업그레이드를 시작할 수 있습니다. active/pending이 있으면 완료될 때까지 대기합니다.
외부 인터넷 PC용 경유 버전 일괄 다운로드 스크립트 (17.5.4 포함)
# 외부 인터넷 망에서 실행하여 el8 또는 el9 패키지 일괄 다운로드
TARGET_OS="el8"
RPM_VERSIONS=("16.11.10-ce.0" "17.3.8-ce.0" "17.5.4-ce.0" "17.8.4-ce.0" "17.11.7-ce.0" "18.2.3-ce.0" "18.5.2-ce.0" "18.11.0-ce.0" "19.2.8-ce.0")
mkdir -p ./gitlab_rpms && cd ./gitlab_rpms
for VER in "${RPM_VERSIONS[@]}"; do
  PKG="gitlab-ce-${VER}.${TARGET_OS}.x86_64.rpm"
  echo "Downloading ${PKG}..."
  curl -LO "https://packages.gitlab.com/gitlab/gitlab-ce/packages/el/${TARGET_OS##el}/${PKG}/download.rpm"
  mv download.rpm "${PKG}"
done
ls -lh *.rpm
sha256sum *.rpm > SHA256SUMS.txt
17.3.x에서 17.8.x 진입 전 필수 제약이 발생하지 않도록 17.5.4 정류장을 명시적으로 포함하여 다운로드합니다.
여유 파티션 디렉터리 생성 및 업로드된 RPM 검증
sudo mkdir -p /var/opt/gitlab/upgrade_rpms
ls -lh /var/opt/gitlab/upgrade_rpms/gitlab-ce-*.rpm
sha256sum /var/opt/gitlab/upgrade_rpms/gitlab-ce-*.rpm
/tmp 대신 디스크 용량이 충분한 /var/opt/gitlab/upgrade_rpms에 반입하고 각 파일 크기(1GB 이상)와 체크섬을 검증합니다.
GitLab 환경 상세 진단 점검
sudo gitlab-rake gitlab:env:info
점검 전 기준 사양, Ruby, PostgreSQL 버전 정보를 기록합니다.
  • 현재 16.11.1에서 pending, failed, active 상태의 백그라운드 마이그레이션이 0건임을 확인했습니다.
  • 17.5.4를 포함한 모든 경유 버전 RPM(총 9개)이 /var/opt/gitlab/upgrade_rpms에 업로드되었습니다.
  • 반입된 RPM 파일들의 크기(개당 1.1GB~1.3GB) 및 SHA256 체크섬이 정상 대조되었습니다.
결과 읽기

BBM이 진행 중인 상태에서 패키지를 덮어쓰면 DB 롤백 외에는 복구가 불가능해집니다.

다음 판단

패키지 변경 직전 필수 선행 단계로 설정 파일 수동 백업과 U-Cloud VM 스냅샷을 생성합니다.

3
변경패키지·설정·서비스 상태가 달라지는 단계

핵심 암호화 키 및 설정 파일 타임스탬프 수동 백업

패키지나 데이터베이스를 변경하기 전에 반드시 /etc/gitlab/gitlab-secrets.json과 gitlab.rb를 권한(0600)을 유지한 채 별도 디렉터리에 백업합니다. secrets.json이 손상되면 데이터베이스가 남아있어도 CI/CD 변수, 웹훅 토큰, 2FA 시크릿이 영구 복구 불가능해집니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.
설정 및 비밀 암호화 키 타임스탬프 백업 디렉터리 생성 및 보존
sudo mkdir -p /root/gitlab_config_backup_$(date +%Y%m%d)
sudo cp -p /etc/gitlab/gitlab.rb /root/gitlab_config_backup_$(date +%Y%m%d)/
sudo cp -p /etc/gitlab/gitlab-secrets.json /root/gitlab_config_backup_$(date +%Y%m%d)/
sudo ls -la /root/gitlab_config_backup_$(date +%Y%m%d)/
소유권과 파일 권한(0600)을 그대로 보존(cp -p)하며 타임스탬프 디렉터리에 격리 백업합니다.
GitLab 구성 파일 검토
sudoedit /etc/gitlab/gitlab.rb
폐쇄망 기본 설정 및 향후 Jenkins 웹훅 로컬 연동에 대비한 설정을 사전 점검합니다.
설정 예시 · /etc/gitlab/gitlab.rb
GitLab 폐쇄망 권장 기본 설정 (백업 보존 및 Webhook 타임아웃)
# /etc/gitlab/gitlab.rb 설정 파일 예시 (수정 전 반드시 cp 백업)
external_url 'https://gitlab.example.local'

# 폐쇄망 및 Jenkins 연동 시 내부 웹훅 아웃바운드 준비
gitlab_rails['webhook_timeout'] = 15

# 백업 보존 기간 (초 단위: 604800 = 7일)
gitlab_rails['backup_keep_time'] = 604800

# 패키지 업그레이드 시 자동 DB 마이그레이션 활성화
  • /etc/gitlab/gitlab-secrets.json 파일이 루트 전용 안전 디렉터리에 타임스탬프 백업되었습니다.
  • /etc/gitlab/gitlab.rb 설정 파일 백업본이 생성되었습니다.
  • 백업 파일의 접근 권한이 0600으로 안전하게 보호되고 있습니다.
결과 읽기

설정 파일 백업 없이 업그레이드를 진행하면 마이그레이션 실패 시 secrets 복원이 불가능해집니다.

다음 판단

데이터 정합성을 위해 서비스를 일시 중지하고 U-Cloud VM 스냅샷을 생성합니다.

4
변경패키지·설정·서비스 상태가 달라지는 단계

데이터 정합성 정지 후 U-Cloud VM 스냅샷 촬영 및 재기동

패키지를 덮어씌우기 직전, 장애 시 100% 롤백을 보장하기 위해 U-Cloud VM 스냅샷을 생성합니다. 디스크 일관성과 데이터베이스 버퍼 플러시를 위해 GitLab 서비스를 잠시 내린 상태에서 스냅샷을 촬영하고, 완료 즉시 서비스를 다시 기동합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.
GitLab 서비스 정상 중지 (DB 버퍼 플러시)
sudo gitlab-ctl stop
sudo gitlab-ctl status
모든 서비스가 down 상태가 되었는지 확인합니다.
U-Cloud 콘솔에서 VM 스냅샷 생성 및 완료 확인
echo '[인프라 담당자] U-Cloud 콘솔에서 VM 전체 스냅샷 생성을 완료할 때까지 대기합니다. 스냅샷 태그: gitlab-pre-upgrade-16.11.1'
스냅샷 생성이 100% 완료된 것을 확인한 후 다음 단계로 진행합니다.
GitLab 서비스 재기동 및 상태 확인
sudo gitlab-ctl start
sudo gitlab-ctl status
모든 프로세스가 run 상태로 복귀했는지 확인합니다.
스냅샷 직후 헬스체크 확인
sudo gitlab-rake gitlab:check SANITIZE=true
서비스 재기동 후 데이터베이스 연결과 시스템 상태가 정상인지 점검합니다.
  • gitlab-ctl stop 후 인프라 U-Cloud VM 스냅샷이 정상 완료되었습니다.
  • gitlab-ctl start 후 주요 컴포넌트가 정상 run 상태로 복귀했습니다.
  • 긴급 상황 시 VM 콘솔에서 해당 스냅샷으로 10분 내 롤백 가능한 상태임을 확인했습니다.
결과 읽기

서비스가 구동 중인 상태에서 스냅샷을 찍으면 파일시스템 저널 불일치가 생길 수 있으므로 stop 상태에서 찍는 것이 가장 안전합니다.

다음 판단

완벽한 롤백 안전망이 확보되었으므로 이제 단계별 경유 RPM 순차 설치와 BBM 대기 루틴을 진행합니다.

5
변경패키지·설정·서비스 상태가 달라지는 단계

Upgrade Stops 경유 RPM 설치 및 BBM 0건 대기 루틴

절대로 여러 패키지를 한 번에 설치해서는 안 됩니다! 매 정류장마다 [① RPM 1개 설치 ➔ ② 서비스 run 상태 확인 ➔ ③ BBM 0건 대기] 3단계를 세트로 완료한 뒤 다음 버전으로 넘어갑니다. 특히 16.11.10 직후 PostgreSQL 14 승격과 18.11.0 후 PostgreSQL 16 버전 요구사항을 반드시 확인합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.
[정류장 1] 16.11.10 패키지 설치 및 BBM 대기
sudo rpm -Uvh /var/opt/gitlab/upgrade_rpms/gitlab-ce-16.11.10-ce.0.<OS_RELEASE>.x86_64.rpm
sudo gitlab-ctl status
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean: Ready for next stop'
출력이 없을 때까지 대기합니다. <OS_RELEASE>는 el8 또는 el9로 치환하여 실행합니다.
[핵심 기술 절차] 현재 PostgreSQL 버전 점검 및 14 수동 승격
sudo gitlab-psql -c "SELECT version();"
# 현재 DB가 13.x인 경우에만 14로 업그레이드 수행 (충분한 디스크 공간 확인 필수)
sudo gitlab-ctl pg-upgrade -V 14
sudo gitlab-psql -c "SELECT version();"
sudo gitlab-ctl status postgresql
GitLab 17부터는 PG 13이 미지원되므로 필수입니다. 이미 14인 경우 실행할 필요가 없습니다.
[정류장 2] 17.3.8 설치 및 BBM 대기
sudo rpm -Uvh /var/opt/gitlab/upgrade_rpms/gitlab-ce-17.3.8-ce.0.<OS_RELEASE>.x86_64.rpm
sudo gitlab-ctl status
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean: Ready for next stop'
17.x 초기 정류장 설치 후 BBM 종료를 반드시 대기합니다.
[정류장 3] 17.5.4 및 17.8.4 설치 및 BBM 대기 (하나씩 순차 실행!)
# 1단계: 17.5.4 설치 후 BBM 대기
sudo rpm -Uvh /var/opt/gitlab/upgrade_rpms/gitlab-ce-17.5.4-ce.0.<OS_RELEASE>.x86_64.rpm
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean: Ready for 17.8'
# 2단계: 17.8.4 설치 후 BBM 대기
sudo rpm -Uvh /var/opt/gitlab/upgrade_rpms/gitlab-ce-17.8.4-ce.0.<OS_RELEASE>.x86_64.rpm
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean: Ready for 17.11'
17.5.4와 17.8.4를 절대 한 번에 붙여넣지 말고 각각 설치 후 BBM 0건을 확인합니다.
[정류장 4] 17.11.7 (17.x 최종 정류장) 설치 및 BBM 대기
sudo rpm -Uvh /var/opt/gitlab/upgrade_rpms/gitlab-ce-17.11.7-ce.0.<OS_RELEASE>.x86_64.rpm
sudo gitlab-ctl status
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean: Ready for 18.x'
17.x 종착지 설치 후 모든 백그라운드 작업이 0건인지 교차 검증합니다.
[정류장 5] 18.2.3, 18.5.2, 18.11.0 순차 설치 (1회당 1개씩 BBM 확인 후 진행)
# 18.2.3 설치 ➔ 상태 점검 ➔ BBM 대기
sudo rpm -Uvh /var/opt/gitlab/upgrade_rpms/gitlab-ce-18.2.3-ce.0.<OS_RELEASE>.x86_64.rpm
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean'
# 18.5.2 설치 ➔ 상태 점검 ➔ BBM 대기
sudo rpm -Uvh /var/opt/gitlab/upgrade_rpms/gitlab-ce-18.5.2-ce.0.<OS_RELEASE>.x86_64.rpm
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean'
# 18.11.0 설치 ➔ 상태 점검 ➔ BBM 대기
sudo rpm -Uvh /var/opt/gitlab/upgrade_rpms/gitlab-ce-18.11.0-ce.0.<OS_RELEASE>.x86_64.rpm
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean'
18.x 시리즈를 하나씩 설치할 때마다 BBM이 0건이 될 때까지 기다립니다.
[19.x 진입 전 점검] PostgreSQL 버전 확인 및 필요시 16 업그레이드
sudo gitlab-psql -c "SELECT version();"
# 19.x 패키지가 PostgreSQL 16을 요구하는 경우 아래 명령어로 업그레이드
sudo gitlab-ctl pg-upgrade -V 16 || echo "PostgreSQL version verified"
19.x 최소 요구 DB 버전을 확인하고 필요한 경우에만 추가 pg-upgrade를 수행합니다.
[최종 목표] 19.2.8 패키지 설치 및 최종 reconfigure
sudo rpm -Uvh /var/opt/gitlab/upgrade_rpms/gitlab-ce-19.2.8-ce.0.<OS_RELEASE>.x86_64.rpm
sudo gitlab-ctl reconfigure
sudo gitlab-rake gitlab:background_migrations:status | grep -E 'pending|failed|active' || echo 'Clean: All migrations finished'
최종 목표 버전 패키지를 설치하고 전체 컴포넌트 설정을 재구성합니다.
  • 16.11.10 설치 후 PostgreSQL 13인 경우 pg-upgrade가 성공하여 14로 전환되었습니다.
  • 17.3.8 ➔ 17.5.4 ➔ 17.8.4 ➔ 17.11.7 ➔ 18.2.3 ➔ 18.5.2 ➔ 18.11.0 정류장을 하나씩 개별 설치했습니다.
  • 각 RPM 설치마다 sudo gitlab-ctl status와 BBM 0건 대기를 완료한 후 다음 정류장을 진행했습니다.
결과 읽기

BBM이 진행 중인 상태에서 상위 버전 패키지를 설치하면 스키마 충돌이 발생해 복구가 불가능해집니다.

다음 판단

데이터베이스 변환 및 백그라운드 마이그레이션의 최종 완료 여부를 종합 검증합니다.

6
확인시스템을 변경하지 않는 점검 단계

최종 헬스체크 및 백그라운드 마이그레이션 완전 완료 검증

목표 버전(19.2.8) 도달 후 모든 백그라운드 데이터 변환이 0건으로 끝났는지 확인하고, 시스템 전체 헬스체크와 프로세스 uptime을 검증합니다.

배치 백그라운드 마이그레이션(BBM) 최종 0건 확인
sudo gitlab-rake gitlab:background_migrations:status
출력되는 항목 중 queued, active, failed 카운트가 모두 0이어야 합니다. 웹 UI Admin Area > Monitoring > Background Migrations에서도 0건 대조.
전체 GitLab 환경 정보 및 최종 버전 확인
sudo gitlab-rake gitlab:env:info
GitLab 버전이 19.2.8인지, PostgreSQL 및 Ruby 버전이 정상인지 확인합니다.
GitLab 통합 진단 및 권한 검사
sudo gitlab-rake gitlab:check SANITIZE=true
저장소 권한, Gitaly 연결, Redis 큐 등 모든 진단 항목이 OK인지 점검합니다.
각 컴포넌트 서비스 프로세스 구동 확인
sudo gitlab-ctl status
puma, sidekiq, gitaly, postgresql, redis, gitlab-workhorse 등 모든 서비스가 run 상태이고 uptime이 유지되는지 점검합니다.
  • BBM의 Pending, Active, Failed 작업 수가 0건임을 확인했습니다. (Admin Area > Monitoring > Background Migrations 대조)
  • gitlab:env:info에서 목표 버전 19.2.8과 내장 컴포넌트 버전이 정상 출력됩니다.
  • gitlab:check SANITIZE=true 진단에서 심각한 오류가 발견되지 않았습니다.
결과 읽기

마이그레이션 큐가 0이 아닌 상태에서 재부팅하면 백그라운드 작업이 데드락에 빠질 수 있으므로 웹 UI에서도 완료 여부를 반드시 교차 검증합니다.

다음 판단

Jenkins 연동, 웹훅 아웃바운드 허용, 토큰 만료 정책 등 보안 설정을 정비합니다.

7
확인시스템을 변경하지 않는 점검 단계

Jenkins 웹훅 아웃바운드 허용, 파이프라인 검증 및 RPM 정리

GitLab 최신 버전의 SSRF 방어 정책으로 차단되는 Jenkins 사설 IP 웹훅을 허용하고, 실제 Git Clone 및 Webhook Push 이벤트를 테스트합니다. 모든 검수가 완료된 후 임시 RPM 파일을 안전하게 정리하여 디스크 공간을 확보합니다.

Admin UI 웹훅 로컬 네트워크 허용 가이드 점검
echo '[Admin Web UI 점검] GitLab Admin Area > Settings > Network > Outbound requests 진입'
echo '1. Allow requests to the local network from web hooks and services 체크 활성화'
echo '2. Jenkins 서버 사설 IP(예: 10.x.x.x 또는 192.168.x.x)를 Local IP 허용 목록에 등록'
사설 IP 대역의 Jenkins로 향하는 Webhook이 400/500 에러로 차단되지 않도록 허용합니다.
Jenkins 연동 테스트 빌드 및 Webhook 수동 테스트
echo '1. Jenkins 작업 화면에서 Build Now를 1회 실행하여 GitLab 저장소 Git Clone(인증) 정상 동작 여부 확인'
echo '2. GitLab 프로젝트 > Settings > Webhooks에서 Jenkins Webhook의 Test > Push events 클릭 후 HTTP 200 응답 확인'
Jenkins의 Git Clone 및 GitLab의 Webhook 트리거가 모두 정상 통신하는지 검증합니다.
GitLab Runner 등록 상태 점검
echo 'GitLab Admin Area > CI/CD > Runners 메뉴 확인'
echo '기존 등록된 전용 Runner가 온전한 상태인지, 연결 끊김 없이 Online 상태인지 확인'
버전 업그레이드 후 호환성 이슈가 없는지 확인합니다.
검수 완료 후 임시 설치 RPM 파일 정리 (디스크 확보)
ls -lh /var/opt/gitlab/upgrade_rpms/
rm -f /var/opt/gitlab/upgrade_rpms/gitlab-ce-*.rpm
df -hT /var/opt/gitlab
모든 검수가 완료된 후 대용량 임시 RPM 파일을 안전하게 삭제하여 디스크 용량을 확보합니다.
  • Admin Area > Settings > Network에서 사설망 Jenkins 웹훅 아웃바운드 요청이 허용되었습니다.
  • Jenkins에서 Git Clone 및 Push Webhook 테스트(HTTP 200)가 정상 통과했습니다.
  • 기존 등록된 GitLab Runner들이 정상 Online 상태를 유지하고 있습니다.
  • 모든 검수 완료 후 임시 RPM 파일이 정리되어 디스크 공간이 확보되었습니다.
결과 읽기

사설망 웹훅 차단 해제 시 임의의 외부 IP를 전체 개방하지 말고 필요한 Jenkins 서버 IP 또는 서브넷만 화이트리스트로 제한합니다.

다음 판단

만약 작업 중 심각한 DB 장애나 복구 불능 오류가 발생했을 때를 대비한 긴급 롤백 절차를 숙지합니다.

8
주의권한·연결·중단 영향을 확인할 단계

장애 시 다운그레이드 금지 및 U-Cloud VM 스냅샷 전체 복원

업그레이드 도중 DB 마이그레이션 실패 등 치명적인 장애가 발생한 경우 절대로 하위 버전 RPM 강제 설치(다운그레이드)를 시도해서는 안 됩니다. 부분 적용된 스키마 변경으로 DB가 영구 손상됩니다. 즉시 작업을 중단하고 Step 4에서 생성한 U-Cloud VM 스냅샷으로 서버 전체를 복원하여 작업 시작 전 상태로 즉시 원복합니다.

GitLab 프로세스 긴급 중지
sudo gitlab-ctl stop
sudo killall -9 puma sidekiq || true
비정상 상태의 프로세스를 안전하게 종료합니다.
U-Cloud 콘솔에서 VM 스냅샷 복원(Restore) 실행
echo '[긴급 롤백] U-Cloud 인프라 콘솔에서 4단계에 생성한 스냅샷 gitlab-pre-upgrade-16.11.1을 선택하고 VM 복원을 실행합니다.'
스냅샷 복원이 진행되면 VM이 재부팅되면서 업그레이드 이전의 16.11.1 디스크 및 DB 상태로 복구됩니다.
복원 후 부팅 및 서비스 상태 점검
sudo gitlab-ctl status
sudo gitlab-rake gitlab:env:info
원래 버전 16.11.1과 데이터베이스가 정상적으로 복구되었는지 확인합니다.
설정 및 암호화 키 확인 (필요 시 수동 복구)
sudo ls -la /root/gitlab_config_backup_*/
sudo gitlab-rake gitlab:check SANITIZE=true
필요한 경우 백업해 둔 /root/gitlab_config_backup_*/ 디렉터리의 secrets.json과 gitlab.rb 파일을 /etc/gitlab/에 복원하고 권한을 0600으로 맞춥니다.
  • 오류 발생 시 무리한 다운그레이드 명령어를 실행하지 않고 스냅샷 복원을 결정했습니다.
  • U-Cloud VM 스냅샷 복원을 통해 16.11.1 시점으로 디스크와 DB 전체가 원복되었습니다.
  • 복구 후 gitlab-ctl status에서 모든 컴포넌트가 정상 기동되었고 기존 데이터와 코드가 보존되었습니다.
결과 읽기

스냅샷 복원 후에는 업그레이드 시도 중 작성된 신규 커밋이나 설정 변경이 되돌려지므로 작업 전 공지된 점검 창 내에서만 수행해야 합니다.

다음 판단

원인 분석 후 누락된 정류장 및 PostgreSQL 버전을 보완하여 재작업 일정을 수립합니다.

SECURITY CHECK

운영 전 마지막 보안 점검

  • 업그레이드 패키지를 덮어쓰기 전 /etc/gitlab/gitlab-secrets.json과 gitlab.rb를 권한(0600) 보존 수동 백업했다.
  • 패키지 변경 전 gitlab-ctl stop 후 일관성 있는 U-Cloud VM 스냅샷을 생성하여 롤백 안전망을 확보했다.
  • 장시간 작업 중 네트워크 단절에 대비하여 tmux 또는 screen 세션 내에서 작업을 실행했다.
  • 16.11.10 설치 후 PostgreSQL 버전을 확인하고 13.x인 경우 gitlab-ctl pg-upgrade -V 14로 승격했다.
  • 매 경유 정류장 RPM마다 설치 후 gitlab:background_migrations:status 0건을 확인하고 다음 버전으로 진행했다.
  • Admin Area Outbound Requests에서 사설망 Jenkins 서버 IP로의 Webhook 아웃바운드 호출을 허용했다.
  • 오류 발생 시 무리한 패키지 강제 다운그레이드를 하지 않고 U-Cloud VM 스냅샷 복원 원칙을 준수한다.

COMMON ERRORS

자주 막히는 지점

경유 RPM 설치 중 BBM 미완료 상태에서 다음 버전 덮어쓰기 시도

증상
rpm -Uvh 실행 중 또는 reconfigure 중 'StandardError: Expected batched background migration to be finished' 오류가 발생합니다.
가능한 원인
이전 버전의 백그라운드 DB 마이그레이션이 완전히 끝나지 않은 상태에서 다음 버전 RPM을 설치했습니다.
확인 순서
sudo gitlab-rake gitlab:background_migrations:status로 미완료 작업을 확인하고, Admin Area > Monitoring > Background Migrations에서 실패 작업을 'Retry'하거나 완료될 때까지 대기합니다.
트러블슈팅으로 이어보기

PostgreSQL 버전 미충족으로 17.x 패키지 설치 실패

증상
GitLab 17.x RPM 설치 또는 reconfigure 중 'PostgreSQL 13 is no longer supported' 오류와 함께 중단됩니다.
가능한 원인
GitLab 17부터는 PostgreSQL 13 지원이 중단되었으며, 16.11.10에서 17.x로 넘어가기 전 pg-upgrade를 실행하지 않았습니다.
확인 순서
16.11.10 상태에서 'sudo gitlab-ctl pg-upgrade -V 14'를 실행하여 내장 DB를 PostgreSQL 14로 먼저 승격한 후 17.x RPM을 설치합니다.
트러블슈팅으로 이어보기

/var/opt/gitlab 또는 /tmp 디스크 용량 부족으로 RPM 설치 중단

증상
rpm -Uvh 실행 중 'No space left on device' 또는 pg-upgrade 중 디스크 고갈 에러가 발생합니다.
가능한 원인
여러 경유 버전 RPM(개당 1GB+)과 pg-upgrade DB 복제 변환 파일로 인해 디스크 여유 공간이 고갈되었습니다.
확인 순서
RPM 업로드 경로를 여유가 넉넉한 파티션(/var/opt/gitlab/upgrade_rpms)으로 옮기고, 이미 설치 완료된 이전 버전 RPM을 삭제하거나 볼륨을 증설한 뒤 재실행합니다.
트러블슈팅으로 이어보기

업그레이드 후 Jenkins Webhook 호출 시 400/500 또는 Blocked 발생

증상
GitLab에서 Jenkins로 Push 이벤트 발생 시 'Requests to localhost/private network are not allowed' 오류가 발생합니다.
가능한 원인
GitLab 최신 버전의 SSRF 방어 보안 정책으로 사설망(Private IP)에 대한 웹훅 아웃바운드 호출이 기본 차단됩니다.
확인 순서
Admin Area > Settings > Network > Outbound requests에서 'Allow requests to the local network from web hooks and services'를 체크하고 Jenkins IP를 허용 목록에 등록합니다.
트러블슈팅으로 이어보기

PRIMARY REFERENCES

공식 문서

설치 저장소와 지원 버전은 바뀔 수 있습니다. 검토일 이후에는 링크된 공식 문서와 현재 서버의 패키지 후보 버전을 함께 확인하세요.

TROUBLESHOOT NEXT

설치 후 문제라면 여기서 이어가세요

트러블슈팅 · SYSTEMD서비스가 시작되지 않거나 failed일 때진단 순서 보기 →트러블슈팅 · STORAGE FIRST AIDLinux 서버 디스크가 가득 찼을 때진단 순서 보기 →트러블슈팅 · PORT CHECK특정 포트를 누가 사용 중인지 찾을 때진단 순서 보기 →트러블슈팅 · MEMORY메모리 부족과 OOM 종료를 확인할 때진단 순서 보기 →

NEXT RECIPE

함께 볼 구성 레시피

CI RUNNERGitLab Runner 설치와 안전한 등록8단계로 보기 →RHEL-COMPATIBLE SERVERRocky Linux 9 서버 설치와 초기 구성8단계로 보기 →데이터베이스 · 설치·설정 레시피PostgreSQL 설치와 제한된 원격 연결8단계로 보기 →

도구 빠른 검색

최근 사용한 도구를 다시 열거나, 이름과 기능으로 검색하세요.

검색어와 도구의 입력·결과는 저장하지 않습니다.

↑↓ 이동 · Enter 열기 · Esc 닫기