InfoGrab DocsInfoGrab Docs

업그레이드 전 확인 사항

요약

GitLab 인스턴스를 업그레이드하기 전에 다음을 수행해야 합니다. 업그레이드를 계획할 때 다음을 수행합니다. 업그레이드 전 정보를 모두 수집했다면 사전 단계 수행으로 넘어갈 수 있습니다. 업그레이드 중에는 문제가 발생할 수 있으므로 롤백 계획을 마련하는 것이 중요합니다.

GitLab 인스턴스를 업그레이드하기 전에 다음을 수행해야 합니다.

  1. 업그레이드 전 정보를 수집해 업그레이드를 준비합니다.
  2. GitLab 자체를 업그레이드하기 전에 사전 단계를 수행합니다.

업그레이드 전 정보 수집#

업그레이드를 계획할 때 다음을 수행합니다.

  1. GitLab 릴리스 및 유지 관리 정책을 검토합니다.
  2. 호환성을 보장하기 위해 GitLab 여러 버전에 대한 GitLab 업그레이드 노트를 참고합니다.
  3. 관련이 있다면 대상 GitLab 버전과의 OS 호환성을 확인합니다.
  4. Geo를 사용 중이라면 다음을 수행합니다.
  5. 필요한 업그레이드 정지 지점을 포함해 인스턴스에 적합한 업그레이드 경로를 결정합니다. 업그레이드 정지 지점이 있으면 여러 차례 업그레이드를 수행해야 할 수 있습니다.
  6. 업그레이드 상태 점검을 실행해 잠재적 문제를 조기에 찾아 해결합니다.
  7. 다음을 문서화한 업그레이드 계획을 작성합니다.
    • 인스턴스를 업그레이드하는 단계. 가능하고 필요하다면 무중단 업그레이드를 포함합니다.
    • 업그레이드가 순조롭게 진행되지 않을 경우의 단계. 필요 시 GitLab 롤백 방법을 포함합니다.
  8. 업그레이드 계획을 운영 환경의 복제본에서 테스트합니다. 이렇게 하면 예기치 않은 중단의 위험을 줄일 수 있고 잠재적으로 장시간 실행되는 마이그레이션의 소요 시간을 측정하는 데 도움이 됩니다.

업그레이드 전 정보를 모두 수집했다면 사전 단계 수행으로 넘어갈 수 있습니다.

롤백 계획 및 백업 작성#

업그레이드 중에는 문제가 발생할 수 있으므로 롤백 계획을 마련하는 것이 중요합니다. 적절한 롤백 계획은 GitLab 인스턴스를 마지막으로 정상 작동하던 상태로 되돌리는 명확한 경로를 제공하며 다음으로 구성됩니다.

  • 인스턴스를 백업하는 절차.
  • 인스턴스를 복원하는 절차.

필요해지기 전에 롤백 계획을 테스트해야 합니다. 롤백에 필요한 단계에 대한 개요는 이전 GitLab 버전으로 롤백하기를 참고합니다.

GitLab 백업 만들기#

업그레이드에 문제가 발생했을 때 GitLab을 롤백할 수 있도록 다음 중 하나를 수행합니다.

  • GitLab 백업을 만듭니다. 설치 방법에 따른 안내를 따라야 하며 시크릿 및 설정 파일을 반드시 백업해야 합니다.
  • 인스턴스의 스냅샷을 만듭니다. 인스턴스가 멀티 노드 설치라면 모든 노드의 스냅샷을 만들어야 합니다. 이 과정은 GitLab Support의 지원 범위에 포함되지 않습니다.

GitLab 롤백#

운영 환경을 모사한 테스트 환경이 있다면 예상대로 모두 정상 작동하는지 확인하기 위해 복원을 테스트합니다.

GitLab 백업을 복원하려면 다음을 수행합니다.

  1. 복원 사전 요구 사항을 참고합니다. 가장 중요한 점은 백업된 GitLab 인스턴스와 새 GitLab 인스턴스의 버전이 동일해야 한다는 것입니다.
  2. 설치 방법에 따른 안내를 따라 GitLab을 복원합니다.
  3. 시크릿 및 설정 파일도 함께 복원되었는지 확인합니다.

스냅샷에서 복원하는 경우, 그 방법은 이미 알고 있어야 합니다. 이 과정은 GitLab Support의 지원 범위에 포함되지 않습니다.

사전 단계 수행#

업그레이드를 수행하기 직전에 다음을 수행합니다.

  1. 업그레이드 상태 점검을 다시 실행합니다.
  2. 사용 중인 선택적 기능에 대한 업그레이드를 수행합니다.

업그레이드 상태 점검 실행#

업그레이드 직전과 직후에 GitLab의 주요 구성 요소가 정상 작동하는지 확인하기 위해 업그레이드 상태 점검을 실행합니다.

  1. 일반 설정을 확인합니다.

    sudo gitlab-rake gitlab:check

  2. 모든 백그라운드 데이터베이스 마이그레이션의 상태를 확인합니다. 각 업그레이드 전에 모든 마이그레이션이 완료되어야 합니다. 백그라운드 마이그레이션이 완료될 시간을 확보하려면 메이저·마이너 릴리스 사이의 업그레이드 간격을 넓혀야 합니다.

  3. 암호화된 데이터베이스 값을 복호화할 수 있는지 확인합니다.

    sudo gitlab-rake gitlab:doctor:secrets

  4. GitLab UI에서 다음을 확인합니다.

    • 사용자가 로그인할 수 있습니다.
    • 프로젝트 목록이 표시됩니다.
    • 프로젝트 이슈와 머지 리퀘스트에 접근할 수 있습니다.
    • 사용자가 GitLab에서 리포지터리를 클론할 수 있습니다.
    • 사용자가 GitLab에 커밋을 푸시할 수 있습니다.

  5. GitLab CI/CD에 대해 다음을 확인합니다.

    • 러너가 job을 가져옵니다.
    • 레지스트리에서 Docker 이미지를 푸시하고 풀할 수 있습니다.

  6. Geo를 사용 중이라면 기본 사이트와 각 보조 사이트에서 관련 점검을 실행합니다.

    sudo gitlab-rake gitlab:geo:check

  7. Elasticsearch를 사용 중이라면 검색이 정상적으로 되는지 확인합니다.

  8. 선택 사항. 패키지 가용성을 테스트하고 설치 시간을 줄이려면 공식 리포지터리에서 패키지를 미리 다운로드합니다.

문제가 발생하면 지원을 요청합니다.

선택적 기능에 대한 업그레이드#

GitLab 인스턴스 설정에 따라 GitLab을 업그레이드하기 전에 다음과 같은 추가 단계가 필요할 수 있습니다.

  1. 외부 Gitaly 서버를 사용 중이라면 GitLab 자체를 업그레이드하기 전에 Gitaly 서버를 새 버전으로 업그레이드합니다. 이렇게 하면 애플리케이션 서버의 gRPC 클라이언트가 이전 Gitaly 버전이 지원하지 않는 RPC를 보내는 상황을 방지할 수 있습니다.

  2. GitLab에 연결된 Kubernetes 클러스터가 있다면 새 GitLab 버전에 맞춰 Kubernetes 용 GitLab 에이전트를 업그레이드합니다.

  3. 고급 검색(Elasticsearch)을 사용 중이라면 대기 중인 마이그레이션을 확인해 고급 검색 마이그레이션이 완료되었는지 확인합니다. gitlab:check Rake 작업도 대기 중인 고급 검색 마이그레이션이 있는지 보고합니다. 이 검사는 업그레이드를 중단시키지 않으므로 출력을 읽고 결과에 따라 조치해야 합니다.

    GitLab을 업그레이드한 뒤 새 버전이 호환성을 깨는 경우 Elasticsearch를 업그레이드해야 할 수 있습니다. Elasticsearch 업데이트는 GitLab Support의 지원 범위에 포함되지 않습니다.

CI/CD 파이프라인 및 job 일시 중지#

대부분의 GitLab 인스턴스 유형에서는 업그레이드 중 CI/CD 파이프라인과 job을 일시 중지해야 합니다.

GitLab Runner가 job을 처리하는 동안 GitLab 인스턴스를 업그레이드하면 트레이스 업데이트가 실패합니다. GitLab 이 다시 온라인 상태가 되면 트레이스 업데이트는 자동으로 복구되어야 합니다. 트레이스 업데이트가 자동으로 복구되지 않으면 오류에 따라 GitLab Runner가 재시도하거나 job 처리를 종료합니다.

GitLab Runner는 job 아티팩트 업로드를 세 번 시도하며, 그 이후에는 job 이 실패합니다.

CI/CD 파이프라인과 job을 일시 중지하려면 다음을 수행합니다.

  1. 러너를 일시 중지합니다.

  2. /etc/gitlab/gitlab.rb 파일에 다음을 추가해 새 job 시작을 차단합니다.

    nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n}\n"

  3. GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  4. 모든 job 이 끝날 때까지 기다립니다.

GitLab 업그레이드를 완료했다면 다음을 수행합니다.

  1. 러너의 일시 중지를 해제합니다.
  2. 이전 /etc/gitlab/gitlab.rb 변경 사항을 되돌려 새 job 시작 차단을 해제합니다.

Support와 함께 작업하기#

업그레이드 계획을 검토하기 위해 Support와 함께 작업 중이라면 아래 질문에 대한 답변과 함께 계획을 문서화해 공유합니다.

  • GitLab은 어떻게 설치되어 있습니까?
  • 노드의 운영 체제는 무엇입니까? 이후 업데이트가 제공되는지 확인하려면 지원되는 플랫폼을 확인합니다.
  • 단일 노드 구성입니까, 멀티 노드 구성입니까? 멀티 노드라면 각 노드에 대한 아키텍처 세부 정보를 문서화해 공유합니다. 어떤 외부 구성 요소를 사용합니까? 예를 들어 Gitaly, PostgreSQL, Redis 등입니다.
  • Geo를 사용 중입니까? 그렇다면 각 보조 사이트에 대한 아키텍처 세부 정보를 문서화해 공유합니다.
  • 구성에서 특이하거나 중요할 수 있는 다른 점이 있습니까?
  • 현재 사용 중인 GitLab 버전에서 알려진 이슈를 겪고 있습니까?

지원 요청#

업그레이드 중 문제가 발생하면 다음을 수행합니다.

  1. 오류를 복사하고 나중에 분석할 로그를 수집합니다. 데이터를 수집하는 데는 다음 도구를 사용합니다.
    • Linux 패키지 또는 Docker로 GitLab을 설치했다면 gitlabsos.
    • Helm Charts로 GitLab을 설치했다면 kubesos.
  2. 마지막으로 정상 작동하던 버전으로 롤백합니다.

지원을 받으려면 다음을 수행합니다.

업그레이드 전 확인 사항

GitLab v19.5
Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed
원문 보기

요약

GitLab 인스턴스를 업그레이드하기 전에 다음을 수행해야 합니다. 업그레이드를 계획할 때 다음을 수행합니다. 업그레이드 전 정보를 모두 수집했다면 사전 단계 수행으로 넘어갈 수 있습니다. 업그레이드 중에는 문제가 발생할 수 있으므로 롤백 계획을 마련하는 것이 중요합니다.

GitLab 인스턴스를 업그레이드하기 전에 다음을 수행해야 합니다.

  1. 업그레이드 전 정보를 수집해 업그레이드를 준비합니다.
  2. GitLab 자체를 업그레이드하기 전에 사전 단계를 수행합니다.

업그레이드 전 정보 수집#

업그레이드를 계획할 때 다음을 수행합니다.

  1. GitLab 릴리스 및 유지 관리 정책을 검토합니다.
  2. 호환성을 보장하기 위해 GitLab 여러 버전에 대한 GitLab 업그레이드 노트를 참고합니다.
  3. 관련이 있다면 대상 GitLab 버전과의 OS 호환성을 확인합니다.
  4. Geo를 사용 중이라면 다음을 수행합니다.
  5. 필요한 업그레이드 정지 지점을 포함해 인스턴스에 적합한 업그레이드 경로를 결정합니다. 업그레이드 정지 지점이 있으면 여러 차례 업그레이드를 수행해야 할 수 있습니다.
  6. 업그레이드 상태 점검을 실행해 잠재적 문제를 조기에 찾아 해결합니다.
  7. 다음을 문서화한 업그레이드 계획을 작성합니다.
    • 인스턴스를 업그레이드하는 단계. 가능하고 필요하다면 무중단 업그레이드를 포함합니다.
    • 업그레이드가 순조롭게 진행되지 않을 경우의 단계. 필요 시 GitLab 롤백 방법을 포함합니다.
  8. 업그레이드 계획을 운영 환경의 복제본에서 테스트합니다. 이렇게 하면 예기치 않은 중단의 위험을 줄일 수 있고 잠재적으로 장시간 실행되는 마이그레이션의 소요 시간을 측정하는 데 도움이 됩니다.

업그레이드 전 정보를 모두 수집했다면 사전 단계 수행으로 넘어갈 수 있습니다.

롤백 계획 및 백업 작성#

업그레이드 중에는 문제가 발생할 수 있으므로 롤백 계획을 마련하는 것이 중요합니다. 적절한 롤백 계획은 GitLab 인스턴스를 마지막으로 정상 작동하던 상태로 되돌리는 명확한 경로를 제공하며 다음으로 구성됩니다.

  • 인스턴스를 백업하는 절차.
  • 인스턴스를 복원하는 절차.

필요해지기 전에 롤백 계획을 테스트해야 합니다. 롤백에 필요한 단계에 대한 개요는 이전 GitLab 버전으로 롤백하기를 참고합니다.

GitLab 백업 만들기#

업그레이드에 문제가 발생했을 때 GitLab을 롤백할 수 있도록 다음 중 하나를 수행합니다.

  • GitLab 백업을 만듭니다. 설치 방법에 따른 안내를 따라야 하며 시크릿 및 설정 파일을 반드시 백업해야 합니다.
  • 인스턴스의 스냅샷을 만듭니다. 인스턴스가 멀티 노드 설치라면 모든 노드의 스냅샷을 만들어야 합니다. 이 과정은 GitLab Support의 지원 범위에 포함되지 않습니다.

GitLab 롤백#

운영 환경을 모사한 테스트 환경이 있다면 예상대로 모두 정상 작동하는지 확인하기 위해 복원을 테스트합니다.

GitLab 백업을 복원하려면 다음을 수행합니다.

  1. 복원 사전 요구 사항을 참고합니다. 가장 중요한 점은 백업된 GitLab 인스턴스와 새 GitLab 인스턴스의 버전이 동일해야 한다는 것입니다.
  2. 설치 방법에 따른 안내를 따라 GitLab을 복원합니다.
  3. 시크릿 및 설정 파일도 함께 복원되었는지 확인합니다.

스냅샷에서 복원하는 경우, 그 방법은 이미 알고 있어야 합니다. 이 과정은 GitLab Support의 지원 범위에 포함되지 않습니다.

사전 단계 수행#

업그레이드를 수행하기 직전에 다음을 수행합니다.

  1. 업그레이드 상태 점검을 다시 실행합니다.
  2. 사용 중인 선택적 기능에 대한 업그레이드를 수행합니다.

업그레이드 상태 점검 실행#

업그레이드 직전과 직후에 GitLab의 주요 구성 요소가 정상 작동하는지 확인하기 위해 업그레이드 상태 점검을 실행합니다.

  1. 일반 설정을 확인합니다.

    sudo gitlab-rake gitlab:check

  2. 모든 백그라운드 데이터베이스 마이그레이션의 상태를 확인합니다. 각 업그레이드 전에 모든 마이그레이션이 완료되어야 합니다. 백그라운드 마이그레이션이 완료될 시간을 확보하려면 메이저·마이너 릴리스 사이의 업그레이드 간격을 넓혀야 합니다.

  3. 암호화된 데이터베이스 값을 복호화할 수 있는지 확인합니다.

    sudo gitlab-rake gitlab:doctor:secrets

  4. GitLab UI에서 다음을 확인합니다.

    • 사용자가 로그인할 수 있습니다.
    • 프로젝트 목록이 표시됩니다.
    • 프로젝트 이슈와 머지 리퀘스트에 접근할 수 있습니다.
    • 사용자가 GitLab에서 리포지터리를 클론할 수 있습니다.
    • 사용자가 GitLab에 커밋을 푸시할 수 있습니다.

  5. GitLab CI/CD에 대해 다음을 확인합니다.

    • 러너가 job을 가져옵니다.
    • 레지스트리에서 Docker 이미지를 푸시하고 풀할 수 있습니다.

  6. Geo를 사용 중이라면 기본 사이트와 각 보조 사이트에서 관련 점검을 실행합니다.

    sudo gitlab-rake gitlab:geo:check

  7. Elasticsearch를 사용 중이라면 검색이 정상적으로 되는지 확인합니다.

  8. 선택 사항. 패키지 가용성을 테스트하고 설치 시간을 줄이려면 공식 리포지터리에서 패키지를 미리 다운로드합니다.

문제가 발생하면 지원을 요청합니다.

선택적 기능에 대한 업그레이드#

GitLab 인스턴스 설정에 따라 GitLab을 업그레이드하기 전에 다음과 같은 추가 단계가 필요할 수 있습니다.

  1. 외부 Gitaly 서버를 사용 중이라면 GitLab 자체를 업그레이드하기 전에 Gitaly 서버를 새 버전으로 업그레이드합니다. 이렇게 하면 애플리케이션 서버의 gRPC 클라이언트가 이전 Gitaly 버전이 지원하지 않는 RPC를 보내는 상황을 방지할 수 있습니다.

  2. GitLab에 연결된 Kubernetes 클러스터가 있다면 새 GitLab 버전에 맞춰 Kubernetes 용 GitLab 에이전트를 업그레이드합니다.

  3. 고급 검색(Elasticsearch)을 사용 중이라면 대기 중인 마이그레이션을 확인해 고급 검색 마이그레이션이 완료되었는지 확인합니다. gitlab:check Rake 작업도 대기 중인 고급 검색 마이그레이션이 있는지 보고합니다. 이 검사는 업그레이드를 중단시키지 않으므로 출력을 읽고 결과에 따라 조치해야 합니다.

    GitLab을 업그레이드한 뒤 새 버전이 호환성을 깨는 경우 Elasticsearch를 업그레이드해야 할 수 있습니다. Elasticsearch 업데이트는 GitLab Support의 지원 범위에 포함되지 않습니다.

CI/CD 파이프라인 및 job 일시 중지#

대부분의 GitLab 인스턴스 유형에서는 업그레이드 중 CI/CD 파이프라인과 job을 일시 중지해야 합니다.

GitLab Runner가 job을 처리하는 동안 GitLab 인스턴스를 업그레이드하면 트레이스 업데이트가 실패합니다. GitLab 이 다시 온라인 상태가 되면 트레이스 업데이트는 자동으로 복구되어야 합니다. 트레이스 업데이트가 자동으로 복구되지 않으면 오류에 따라 GitLab Runner가 재시도하거나 job 처리를 종료합니다.

GitLab Runner는 job 아티팩트 업로드를 세 번 시도하며, 그 이후에는 job 이 실패합니다.

CI/CD 파이프라인과 job을 일시 중지하려면 다음을 수행합니다.

  1. 러너를 일시 중지합니다.

  2. /etc/gitlab/gitlab.rb 파일에 다음을 추가해 새 job 시작을 차단합니다.

    nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n}\n"

  3. GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  4. 모든 job 이 끝날 때까지 기다립니다.

GitLab 업그레이드를 완료했다면 다음을 수행합니다.

  1. 러너의 일시 중지를 해제합니다.
  2. 이전 /etc/gitlab/gitlab.rb 변경 사항을 되돌려 새 job 시작 차단을 해제합니다.

Support와 함께 작업하기#

업그레이드 계획을 검토하기 위해 Support와 함께 작업 중이라면 아래 질문에 대한 답변과 함께 계획을 문서화해 공유합니다.

  • GitLab은 어떻게 설치되어 있습니까?
  • 노드의 운영 체제는 무엇입니까? 이후 업데이트가 제공되는지 확인하려면 지원되는 플랫폼을 확인합니다.
  • 단일 노드 구성입니까, 멀티 노드 구성입니까? 멀티 노드라면 각 노드에 대한 아키텍처 세부 정보를 문서화해 공유합니다. 어떤 외부 구성 요소를 사용합니까? 예를 들어 Gitaly, PostgreSQL, Redis 등입니다.
  • Geo를 사용 중입니까? 그렇다면 각 보조 사이트에 대한 아키텍처 세부 정보를 문서화해 공유합니다.
  • 구성에서 특이하거나 중요할 수 있는 다른 점이 있습니까?
  • 현재 사용 중인 GitLab 버전에서 알려진 이슈를 겪고 있습니까?

지원 요청#

업그레이드 중 문제가 발생하면 다음을 수행합니다.

  1. 오류를 복사하고 나중에 분석할 로그를 수집합니다. 데이터를 수집하는 데는 다음 도구를 사용합니다.
    • Linux 패키지 또는 Docker로 GitLab을 설치했다면 gitlabsos.
    • Helm Charts로 GitLab을 설치했다면 kubesos.
  2. 마지막으로 정상 작동하던 버전으로 롤백합니다.

지원을 받으려면 다음을 수행합니다.