이전 버전 업그레이드

Tier: Free, Premium, Ultimate Offering: Self-Managed

이 페이지에서 이전 버전의 업그레이드 안내가 제공됩니다.

GitLab 차트의 최신 버전을 업그레이드하려면 업그레이드 가이드를 참조하세요.

5.9 버전으로 업그레이드

Sidekiq pod가 준비 상태가 되지 않음

5.9.x로 업그레이드하면 Sidekiq pod가 준비 상태가 되지 않을 수 있습니다. pod는 시작되고 정상적으로 작동하는 것으로 보이지만 3807번(기본 메트릭 엔드포인트 포트)에서 듣지 않습니다. 따라서 Sidekiq pod는 준비된 것으로 간주되지 않습니다.

이는 관리자 영역에서 해결할 수 있습니다:

  1. 왼쪽 사이드바에서 맨 아래에서 관리자 영역을 선택합니다.
  2. 설정 > 메트릭 및 프로파일링을 선택합니다.
  3. 메트릭 - Prometheus를 확장합니다.
  4. Health 및 성능 메트릭 엔드포인트 활성화가 활성화되어 있는지 확인합니다.
  5. 영향을 받는 pod를 다시 시작합니다.

이 시나리오에 대한 추가 토론이 잠긴 이슈에서 진행 중입니다.

5.5 버전으로 업그레이드

5.5.0에서 task-runner 차트가 toolbox로 이름이 변경되고 제거되었습니다. 따라서 구성에서 task-runner를 언급하는 모든 내용은 toolbox로 이름을 바꿔야 합니다. 5.5 버전 이상에서는 toolbox 차트를 사용하고, 5.4 버전 이하에서는 task-runner 차트를 사용하세요.

객체 리포지터리 비밀 에러 누락

5.5 버전 이상으로 업그레이드하면 아래와 유사한 오류가 발생할 수 있습니다: 

Error: UPGRADE FAILED: execution error at (gitlab/charts/gitlab/charts/toolbox/templates/deployment.yaml:227:23): A valid backups.objectStorage.config.secret is needed!

오류에 언급된 비밀이 이미 존재하고 정확하다면, 이 오류는 새로운 toolbox가 아닌 여전히 task-runner를 참조하는 객체 리포지터리 구성 값이 있기 때문일 것입니다. 구성에서 task-runner를 toolbox로 이름을 바꾸면 이 문제를 해결할 수 있습니다.

오류 메시지 설명에 대한 개방된 이슈가 있습니다.

5.0 버전으로 업그레이드

caution
차트의 4.x 버전에서 최신 5.0 릴리스로 업그레이드하는 경우, 업그레이드가 작동하려면 먼저 최신 4.12.x 패치 릴리스로 업데이트해야 합니다. 5.0 릴리스 노트에서 지원되는 업그레이드 경로에 대해 설명합니다.

5.0.0 릴리스에는 업그레이드를 수행하기 위해 매뉴얼 단계가 필요합니다. 번들 PostgreSQL을 사용하는 경우, 이 업그레이드를 수행하는 가장 좋은 방법은 이전 데이터베이스를 백업하고 새 데이터베이스 인스턴스로 복원하는 것입니다.

caution
업그레이드를 진행하기 전에 백업을 만드는 것을 잊지 마십시오. 이 단계를 문서에 기술된대로 수행하지 않을 경우 데이터베이스의 손실이 발생할 수 있습니다. 별도의 백업이 있는지 확인하세요.

외부 PostgreSQL 데이터베이스를 사용하는 경우, 먼저 데이터베이스를 12 버전 이상으로 업그레이드해야 합니다. 그런 다음 표준 업그레이드 단계를 따르세요.

번들된 PostgreSQL 데이터베이스를 사용하는 경우, 번들된 데이터베이스 업그레이드 단계를 따르세요.

5.0 릴리스 업그레이드 과정의 문제 해결

  • 업그레이드 중 실패가 발생하면, 자세한 내용을 확인하기 위해 gitlab-upgrade-check pod의 설명을 확인하는 것이 유용할 수 있습니다: 

    kubectl get pods -lrelease=RELEASE,app=gitlab
kubectl describe pod <gitlab-upgrade-check-pod-full-name>

4.0 버전으로 업그레이드

4.0.0 릴리스에는 업그레이드를 수행하기 위해 매뉴얼 단계가 필요합니다. 번들 PostgreSQL을 사용하는 경우, 이 업그레이드를 수행하는 가장 좋은 방법은 이전 데이터베이스를 백업하고 새 데이터베이스 인스턴스로 복원하는 것입니다.

caution
업그레이드를 진행하기 전에 백업을 만드는 것을 잊지 마십시오. 이 단계를 문서에 기술된대로 수행하지 않을 경우 데이터베이스의 손실이 발생할 수 있습니다. 별도의 백업이 있는지 확인하세요.

외부 PostgreSQL 데이터베이스를 사용하는 경우, 먼저 데이터베이스를 11 버전 이상으로 업그레이드해야 합니다. 그런 다음 표준 업그레이드 단계를 따르세요.

번들된 PostgreSQL 데이터베이스를 사용하는 경우, 번들된 데이터베이스 업그레이드 단계를 따르세요.

4.0 릴리스 업그레이드 과정의 문제 해결

  • 업그레이드 중 실패가 발생하면, 자세한 내용을 확인하기 위해 gitlab-upgrade-check pod의 설명을 확인하는 것이 유용할 수 있습니다: 

    kubectl get pods -lrelease=RELEASE,app=gitlab
kubectl describe pod <gitlab-upgrade-check-pod-full-name>

4.8: Praefect 업그레이드 중 리포지터리 데이터 손실 문제

Praefect 차트는 아직 제품 사용에 적합하다고 간주되지 않습니다.

Praefect 차트의 4.8 버전에서는 복수의 가상 리포지터리를 지정할 수 있게 되어 StatefulSet 이름을 변경해야 하는 필요성이 생기면서 기존 Praefect 관리 Gitaly StatefulSet 이름(및 연결된 PersistentVolumeClaims)이 변경됩니다. 이로 인해 리포지터리 데이터가 손실된 것처럼 보일 수 있습니다.

업그레이드 전에 다음을 확인하세요:

  • 모든 리포지터리가 Gitaly 클러스터 전체에서 동기화되어 있고 GitLab이 업그레이드 동안 사용되지 않는지 확인합니다. 리포지터리가 동기화되어 있는지 확인하려면 Praefect 파드 중 하나에서 다음 명령을 실행합니다: 

    /usr/local/bin/praefect -config /etc/gitaly/config.toml dataloss

  • 완전하고 테스트된 백업이 있는지 확인합니다.

리포지터리 데이터를 복원하려면 지속적 볼륨 관리 문서를 참조하여 이전 PersistentVolumeClaims을 이전 PersistentVolumes에 다시 연결하는 지침을 제공합니다.

이 과정의 주요 단계 중 하나는 이전 지속적 볼륨의 persistentVolumeReclaimPolicy를 보존으로 설정하는 것입니다. 이 단계를 놓치면 실제 데이터 손실이 발생할 수 있습니다.

문서를 검토한 후, 관련된 이슈의 코멘트에서 이 프로시저에 대한 요약이 스크립트로 제공됩니다.

이전 PersistentVolumes를 다시 연결한 후, 모든 리포지터리가 Praefect에 의해 읽기 전용으로 설정될 가능성이 높습니다. Praefect 컨테이너에서 다음을 실행하여 확인합니다: 

praefect -config /etc/gitaly/config.toml dataloss

이전 PersistentVolumes를 통해 모든 Git 리포지터리가 동기화되어 있다면, Praefect에서 Gitaly 클러스터를 수정하기 위해 각 리포지터리에 대한 accept-dataloss 프로시저를 사용하세요.

이 접근 방법이 Praefect를 수정하는 최선의 방법인지 확인하기 위한 이슈가 열려 있습니다.

3.0 버전으로 업그레이드

3.0.0 릴리스에는 업그레이드를 수행하기 위해 매뉴얼 단계가 필요합니다.

caution
업그레이드를 진행하기 전에 백업을 만드는 것을 잊지 마십시오. 이 단계를 문서에 기술된대로 수행하지 않을 경우 데이터베이스의 손실이 발생할 수 있습니다. 별도의 백업이 있는지 확인하세요.

번들 PostgreSQL을 사용하고 있다면, 이전 데이터베이스를 백업하고 새 데이터베이스 인스턴스로 복원하는 것이 최선의 방법입니다. 일부 단계를 자동화했지만 매뉴얼으로 단계를 수행할 수도 있습니다.

기존 데이터베이스 준비

다음 사항을 주목하십시오:

  • 번들된 PostgreSQL 차트(postgresql.install이 false인 경우)를 사용하지 않는다면, 이 단계를 수행할 필요가 없습니다.
  • 동일한 네임스페이스에 여러 차트가 설치된 경우, Helm 릴리스 이름을 데이터베이스 업그레이드 스크립트에 전달해야 할 수 있습니다. 나중에 제공되는 예제 명령어에서 bash -s STAGE를 bash -s -- -r RELEASE STAGE로 바꿔주십시오.
  • kubectl 컨텍스트의 기본이 아닌 다른 네임스페이스에 차트를 설치한 경우, 데이터베이스 업그레이드 스크립트에 네임스페이스를 전달해야 합니다. 나중에 제공되는 예제 명령어에서 bash -s STAGE를 bash -s -- -n NAMESPACE STAGE로 바꿔주십시오. 이 옵션은 -r RELEASE와 함께 사용할 수 있습니다. 현재 컨텍스트의 기본 네임스페이스를 설정하려면 kubectl config set-context --current --namespace=NAMESPACE를 실행하거나, kubectx의 kubens를 사용하십시오.

pre 단계에서는 Toolbox에 있는 백업 유틸리티 스크립트를 사용하여 데이터베이스의 백업을 생성한 후, 구성된 s3 버킷(MinIO 기본)에 저장합니다: 

# GITLAB_RELEASE는 'v'로 시작하는 설치하는 차트의 버전이어야 합니다: v3.0.0
curl -s "https://gitlab.com/gitlab-org/charts/gitlab/-/raw/${GITLAB_RELEASE}/scripts/database-upgrade" | bash -s pre

클러스터 데이터베이스 비밀 준비

번들된 PostgreSQL 차트를 사용하지 않는 경우(postgresql.install이 false라면):

  • global.psql.password.key를 제공한 경우, 이 단계를 수행할 필요가 없습니다.
  • global.psql.password.secret를 제공한 경우, 추가로 global.psql.password.key를 기존 키의 이름으로 설정하여 이 단계를 우회할 수 있습니다.

응용 프로그램 데이터베이스 키의 시크릿 키가 postgres-password에서 postgresql-password로 변경됩니다. 데이터베이스 비밀번호 시크릿을 업데이트하려면 아래 두 단계 중 하나를 사용하십시오:

  1. 자동으로 생성된 PostgreSQL 암호를 사용하려면, 업그레이드가 새 암호를 생성하도록 이전 시크릿을 삭제하십시오. RELEASE-NAME은 helm list에서 GitLab 릴리스 이름이어야 합니다: 

    # 예전 데이터베이스를 복원해야 할 수도 있으므로 예전 시크릿의 로컬 복사본을 만듭니다
kubectl get secret RELEASE-NAME-postgresql-password -o yaml > postgresql-password.backup.yaml
# 새 시크릿을 생성하기 위해 시크릿을 삭제합니다
kubectl delete secret RELEASE-NAME-postgresql-password

  2. 동일한 비밀번호를 사용하려면 시크릿을 편집하여 키를 postgres-password에서 postgresql-password로 변경하십시오. 추가로, 슈퍼유저 계정에 대한 시크릿이 필요합니다. 해당 사용자를 위한 키 postgresql-postgres-password을 추가하십시오: 

    # 슈퍼유저 암호를 Base64로 인코딩합니다
echo SUPERUSER_PASSWORD | base64
kubectl edit secret RELEASE-NAME-postgresql-password
# EDITOR 창에서 적절한 변경을 수행합니다

기존 서비스 삭제

3.0 버전은 NGINX Ingress의 불변 필드를 업데이트하므로, 업그레이드하기 전에 모든 서비스를 먼저 삭제해야 합니다. 자세한 내용은 Immutable Field Error, spec.clusterIP의 수정 지침에서 확인할 수 있습니다.

  1. 영향을 받는 모든 서비스를 제거하십시오. RELEASE_NAME은 helm list에서 GitLab 릴리스 이름이어야 합니다: 

    kubectl delete services -lrelease=RELEASE_NAME
caution
이로 인해 해당 차트에서 LoadBalancer의 동적 값이 변경되며, 사용 중이라면 NGINX Ingress의 외부IP에 대한 글로벌 Ingress 설정 설명서에서 자세한 내용을 확인하십시오. DNS 레코드를 업데이트해야 할 수도 있습니다!

GitLab 업그레이드

표준 절차에 따라 GitLab을 업그레이드하되, 다음 사항을 추가로 고려하십시오:

번들된 PostgreSQL을 사용하는 경우, 업그레이드 명령에 다음 플래그를 사용하여 마이그레이션을 비활성화하십시오:

  1. --set gitlab.migrations.enabled=false

번들된 PostgreSQL의 데이터베이스 마이그레이션은 나중에 수행될 것입니다.

데이터베이스 복원

다음 사항을 주목하십시오:

  • 번들된 PostgreSQL 차트를 사용하지 않는다면, 이 단계를 수행할 필요가 없습니다.
  • 스크립트 실행을 위해 Bash 4.0 이상을 사용해야 성공적으로 실행됩니다.

  1. Toolbox pod의 업그레이드가 완료될 때까지 기다립니다. RELEASE_NAME은 helm list에서 GitLab 릴리스 이름이어야 합니다: 

    kubectl rollout status -w deployment/RELEASE_NAME-toolbox

  2. Toolbox pod이 성공적으로 배포된 후에 post 단계를 실행합니다:

    이 단계에서는 다음을 수행합니다:

    1. webservice, sidekiq, 및 gitlab-exporter 배포의 레플리카를 0으로 설정합니다. 이는 백업이 복원되는 동안 다른 응용 프로그램이 데이터베이스를 변경하는 것을 방지합니다.
    2. pre 단계에서 생성된 백업에서 데이터베이스를 복원합니다.
    3. 새 버전을 위해 데이터베이스 마이그레이션을 실행합니다.
    4. 처음 단계에서부터 배포를 재개합니다. 
    # GITLAB_RELEASE는 'v'로 시작하는 설치하는 차트의 버전이어야 합니다: v3.0.0
curl -s "https://gitlab.com/gitlab-org/charts/gitlab/-/raw/${GITLAB_RELEASE}/scripts/database-upgrade" | bash -s post

3.0 릴리즈 업그레이드 프로세스 문제 해결

  • 2.15.x의 버그로 인해 Helm 2.14.3 또는 >= 2.16.1을 사용 중임을 확인하십시오.

  • 업그레이드 중 실패 메시지가 표시된 경우, 자세한 내용을 확인하기 위해 gitlab-upgrade-check pod의 설명을 확인하는 것이 유용할 수 있습니다: 

    kubectl get pods -lrelease=RELEASE,app=gitlab
kubectl describe pod <gitlab-upgrade-check-pod-full-name>

  • helm upgrade 실행 시 아래와 같은 오류가 발생할 수 있습니다: 

    Error: kind ConfigMap with the name "gitlab-gitlab-shell-sshd" already exists in the cluster and wasn't defined in the previous release.
Before upgrading, please either delete the resource from the cluster or remove it from the chart
Error: UPGRADE FAILED: kind ConfigMap with the name "gitlab-gitlab-shell-sshd" already exists in the cluster and wasn't defined in the previous release.
Before upgrading, please either delete the resource from the cluster or remove it from the chart

    이 오류 메시지에는 gitlab-redis-health, gitlab-redis-headless 등 다른 configmap에 대한 언급이 포함될 수 있습니다. 이를 해결하기 위해 3.0 릴리즈 업그레이드 단계에 명시된 대로 서비스가 삭제되었는지 확인하십시오. 그 후에, 오류 메시지에 표시된 configmap을 kubectl delete configmap <configmap-name>으로 삭제하십시오.

번들된 PostgreSQL 차트 업그레이드

번들된 PostgreSQL을 버전 12로 업그레이드

본 차트의 5.0.0 릴리스의 일환으로, 번들된 PostgreSQL 버전이 11.9.0에서 12.7.0으로 업그레이드되었습니다. 이는 완전한 대체가 아닙니다. 데이터베이스를 업그레이드하려면 매뉴얼 단계를 수행해야 합니다. 이러한 단계는 5.0 업그레이드 단계에 문서화되어 있습니다.

번들된 PostgreSQL을 11 버전으로 업그레이드하기

이 차트의 4.0.0 릴리스의 일환으로, 저희는 번들된 PostgreSQL 차트를 7.7.0에서 8.9.4로 업그레이드했습니다. 이는 즉시 대체할 수 있는 것이 아닙니다. 데이터베이스를 업그레이드하려면 매뉴얼으로 작업해야 합니다. 업그레이드 단계는 4.0 버전 업그레이드 단계에 문서화되어 있습니다.