SonarQube 업그레이드 가이드

이 문서는 SonarQube 업그레이드 가이드를 공유하기 위해 작성되었다. 

1. 개요

본 문서는 SonarQube Server의 업그레이드 절차 및 권장 지침을 안내합니다.

SonarQube는 정기 릴리즈와 LTA(Long-Term Active) 릴리즈를 운영하며, 업그레이드 시 공식 Upgrade Path를 반드시 준수해야 합니다. 경로상에 LTA 버전이 존재하는 경우 해당 LTA를 순차적으로 경유해야 데이터베이스 마이그레이션 오류를 방지할 수 있습니다.

2. 릴리즈 정책 및 업그레이드 경로

2.1 버전 체계

• 형식: YYYY.Release.Patch (예: 2025.1, 2025.4 LTA, 2026.1 LTA)

• LTA (Long-Term Active): 연 1회 출시되는 장기 지원 버전

2.2 업그레이드 기본 원칙

1. Direct Upgrade 가능: 중간에 LTA 버전이 포함되지 않은 릴리즈 간 업그레이드 (예: 2025.2 → 2025.3)

2. Intermediate LTA 필수 경유: 대상 버전 사이에 LTA가 존재하는 경우 해당 LTA를 반드시 거쳐서 진행 (예: 8.9 LTA → 9.9 LTA → 2025.1 LTA)

3. 최신 패치 버전 사용: LTA 단계 경유 및 최종 업그레이드 시 각 버전의 최신 Patch(x.x.Patch)를 적용하는 것을 강력히 권장

2.3 주요 버전별 업그레이드 경로 매트릭스

3. 사전 점검 항목 (Prerequisites)

4. 환경별 업그레이드 절차

4.1 Docker 환경 업그레이드 (권장)

# 1. 기존 컨테이너 중지 및 제거 (데이터는 볼륨에 보존됨)
docker stop sonarqube
docker rm sonarqube

# 2. 신규 버전 이미지 다운로드
docker pull sonarqube:<target_version>

# 3. 신규 컨테이너 실행 (기존 볼륨 sonarqube_data, extensions, logs 반드시 유지)
docker run -d \
  --name sonarqube \
  -p 9000:9000 \
  -e SONAR_JDBC_URL="jdbc:postgresql://<db_host>:5432/sonar" \
  -e SONAR_JDBC_USERNAME="sonar" \
  -e SONAR_JDBC_PASSWORD="<db_password>" \
  -v sonarqube_data:/opt/sonarqube/data \
  -v sonarqube_extensions:/opt/sonarqube/extensions \
  -v sonarqube_logs:/opt/sonarqube/logs \
  sonarqube:<target_version>

4.2 ZIP 설치 환경 업그레이드

안내: SonarSource는 ZIP 설치 방식을 향후 지원 종료(Deprecated)할 예정이므로, 중장기적으로 Docker 또는 Kubernetes 환경으로의 전환을 권장합니다.

1. 신규 패키지 준비: 신규 버전을 $NEW_SONARQUBE_HOME에 압축 해제합니다.

2. 플러그인 반영: 호환 검증된 플러그인만 신규 디렉터리에 설치합니다. (기존 extensions/plugins 디렉터리 통째 복사 금지)

3. 설정 반영: 신규 conf/sonar.properties를 기준으로 기존 파일에서 필요한 설정값만 선별 이관합니다. (기존 설정 파일 덮어쓰기 금지)

4. JDBC 드라이버 복사: Oracle DB 사용 시 extensions/jdbc-driver/oracle로 드라이버를 복사합니다.

5. 서버 교체 및 기동:

   # 기존 서버 중지
   $OLD_SONARQUBE_HOME/bin/<platform>/sonar.sh stop
   
   # 신규 서버 시작
   $NEW_SONARQUBE_HOME/bin/<platform>/sonar.sh start

   
   

4.3 Database Migration 수행 (공통 필수)

신규 컨테이너 또는 프로세스 기동 직후 웹 UI에서 DB 스키마 마이그레이션을 실행합니다.

1. 웹 브라우저에서 http://<server_url>:9000/setup 접속

2. 안내 마법사에 따라 Upgrade 버튼 클릭 및 마이그레이션 완료 확인
   

5. 업그레이드 후 사후 검증

1. 시스템 정상 상태 확인 (System Status)

   • System: UP

   • Compute Engine: GREEN

   • Search Engine (Elasticsearch): GREEN

2. 플러그인 구동 점검: Portfolio, Branch Analysis, Custom Plugin 등이 정상 활성화되었는지 확인

3. Scanner 및 CI/CD 연동 테스트: Jenkins, GitLab CI, GitHub Actions 등에서 Maven/Gradle/CLI 빌드 분석 실행

4. 프로젝트 분석 데이터 검증: 신규 분석 정상 수행 여부, Quality Gate 통과 및 Issue 수치 일치 여부 확인

6. CURVC 표준 운영 권장 절차

운영 환경의 안정적인 서비스 전환을 위해 아래 단계별 배포 및 검증 순서를 권장합니다.

[표준 실행 흐름]
1. [TEST] 사전 검증
   - 대상 버전 업그레이드 및 DB Migration 테스트
   - 플러그인 호환성 및 주요 프로젝트 샘플 분석 검증
   ↓
2. [PROD] 데이터 백업 (필수)
   - 작업 직전 운영 Database 전체 백업 수행 (롤백용)
   ↓
3. [PROD] 운영 업그레이드
   - 신규 버전 적용 및 DB Migration(/setup) 실행
   ↓
4. [PROD] 서비스 정상 확인
   - System Status(UP / GREEN) 확인 및 주요 프로젝트 스캔 점검

7. 긴급 롤백 절차 (DB Dump 복구)

업그레이드 또는 DB Migration 중 오류가 발생하여 원복해야 하는 경우, 기존 컨테이너로 되돌리고 사전 백업한 DB Dump 파일을 복원합니다.

Step 1. 신규 SonarQube 중지

DB 복원 중 데이터가 변경되지 않도록 실행 중인 SonarQube 컨테이너를 중지합니다.

docker stop sonarqube
docker rm sonarqube

Step 2. PostgreSQL 데이터베이스 초기화 및 복원

마이그레이션 도중 생성/변경된 테이블과의 충돌을 방지하기 위해 기존 스키마를 정리(Drop & Recreate)한 후 Dump를 밀어 넣습니다.

# 1. DB 컨테이너 접속 후 데이터베이스 재생성 (PostgreSQL 기준)
docker exec -it <db_container_name> psql -U sonar -c "DROP DATABASE sonar;"
docker exec -it <db_container_name> psql -U sonar -c "CREATE DATABASE sonar OWNER sonar;"

# 2. 백업 파일(.sql 형식) 복원
cat sonar_backup.sql | docker exec -i <db_container_name> psql -U sonar -d sonar

# (참고) 커스텀/압축 포맷(.dump / .tar) 백업본인 경우
# docker exec -i <db_container_name> pg_restore -U sonar -d sonar --clean < sonar_backup.dump

Step 3. 이전 버전 SonarQube 컨테이너 재기동

기존에 사용하던 이전 버전 태그로 컨테이너를 다시 실행합니다.

docker run -d \
  --name sonarqube \
  -p 9000:9000 \
  -e SONAR_JDBC_URL="jdbc:postgresql://<db_host>:5432/sonar" \
  -e SONAR_JDBC_USERNAME="sonar" \
  -e SONAR_JDBC_PASSWORD="<db_password>" \
  -v sonarqube_data:/opt/sonarqube/data \
  -v sonarqube_extensions:/opt/sonarqube/extensions \
  -v sonarqube_logs:/opt/sonarqube/logs \
  sonarqube:<previous_version>

Step 4. 원복 상태 점검

1. http://<server_url>:9000 접속 확인

2. Administration → System 메뉴에서 이전 버전 번호 및 상태(UP / GREEN) 정상 여부 확인

참고

•  Upgrading the server | SonarQube Docs (sonarsource.com)