GitLab 차트 업그레이드

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

GitLab 설치를 업그레이드하기 전에 원하는 버전으로 업그레이드하고자 하는 해당 릴리스에 대한 changelog를 확인하고 새로운 GitLab 차트 버전과 관련된 릴리스 노트를 찾아보아야 합니다.

업그레이드는 지원되는 업그레이드 경로를 따라야 합니다. GitLab 차트 버전은 GitLab 버전과 동일한 번호 매기는 방식을 따르지 않으므로, 이들 간의 버전 매핑을 확인하시기 바랍니다.

참고: Zero-downtime 업그레이드는 GitLab 차트에서 사용할 수 없습니다. 이 기능을 지원하기 위한 작업은 GitLab Operator epic에서 추적할 수 있습니다.

또한 먼저 백업을 하는 것을 권장합니다. 또한 현재의 값들 중 일부가 더 이상 지원되지 않을 수 있으므로 helm upgrade --set key=value 구문이나 values.yaml 대신 --reuse-values 대신 모든 값을 제공해야 합니다.

이전의 --set 인수를 청소하려면, helm get values <릴리스 이름>을 사용할 수 있습니다. 이를 파일로 지정하면 (helm get values <릴리스 이름> > gitlab.yaml), 이 파일을 -f로 안전하게 전달할 수 있습니다. 따라서 helm upgrade gitlab gitlab/gitlab -f gitlab.yaml으로 제공할 수 있습니다. 이는 --reuse-values의 동작을 안전하게 대체합니다.

단계

참고: 만약 차트의 7.0 버전으로 업그레이드하려면 7.0 버전에 대한 수동 업그레이드 단계를 따르십시오. 만약 차트의 5.0 버전으로 업그레이드하려면 5.0 버전에 대한 수동 업그레이드 단계를 따르십시오. 만약 차트의 4.0 버전으로 업그레이드하려면 4.0 버전에 대한 수동 업그레이드 단계를 따르십시오. 만약 차트의 이전 버전으로 업그레이드하려면 이전 버전용 업그레이드 단계를 따르십시오.

업그레이드하기 전에 설정된 값을 검토하고, 설정을 “과적정”하게 했는지에 대해 곰곰히 생각해보십시오. 우리는 수정된 값을 유지하고 대부분의 차트 기본값을 활용하길 기대합니다. 다음 단계에서 이를 확인하는 방법에 대해 다룹니다.

다음은 GitLab를 업그레이드하는 단계입니다:

  1. 업그레이드하고자 하는 특정 버전에 대한 변경 기록을 확인하십시오.
  2. 배포 문서를 단계별로 진행하십시오.

  3. 이전에 제공한 값을 추출하십시오: 

    helm get values gitlab > gitlab.yaml
  4. 업그레이드 중에 전달해야 하는 모든 값에 대해 결정하십시오. GitLab는 합리적인 기본값을 갖고 있으며, 업그레이드 중에 위 명령에서 모든 값을 전달하려고 시도할 수 있지만, 이로 인해 구성이 차트 버전 간에 변경되었을 수 있으며 매끄럽게 매핑되지 않을 수 있습니다. 명시적으로 설정하고 싶은 최소한의 값을 유지하고, 해당 업그레이드 프로세스 중에 이들을 전달하는 것이 좋습니다.

  5. 앞서 추출한 값으로 업그레이드를 수행하십시오: 

    helm upgrade gitlab gitlab/gitlab \
  --version <새 버전> \
  -f gitlab.yaml \
  --set gitlab.migrations.enabled=true \
  --set ...

주요 데이터베이스 업그레이드 중에 gitlab.migrations.enabled를 false로 설정하도록 요청드립니다. 향후 업데이트를 위해 명시적으로 이를 true로 다시 설정하십시오.

번들 PostgreSQL 차트 업그레이드

참고: 번들 PostgreSQL 차트를 사용하지 않는 경우 (postgresql.install이 false인 경우), 이 단계를 수행할 필요가 없습니다.

번들 PostgreSQL을 13 버전으로 업그레이드

PostgreSQL 13은 GitLab 14.1 이후로 지원됩니다. PostgreSQL 13은 중요한 성능 향상을 가져왔습니다.

번들 PostgreSQL을 13 버전으로 업그레이드하려면 다음 단계가 필요합니다:

  1. 기존 데이터베이스 준비.
  2. 기존 PostgreSQL 데이터 삭제.
  3. postgresql.image.tag 값을 13.6.0으로 업데이트하고 새로운 PostgreSQL 13 데이터베이스를 만들기 위해 차트를 다시 설치합니다.
  4. 데이터베이스 복원.

번들 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 업그레이드 단계에 문서화되어 있습니다.

7.0 버전으로 업그레이드

경고: 차트의 6.x 버전에서 최신 7.0 릴리스로 업그레이드하는 경우, 업그레이드를 위해 먼저 최신 6.11.x 패치 릴리스로 업데이트해야 합니다. 7.0 릴리스 노트에 지원되는 업그레이드 경로가 설명되어 있습니다.

7.0.x 릴리스는 업그레이드를 수행하기 위해 수동 단계가 필요할 수 있습니다.

  • 클러스터 내부 Redis 서비스를 제공하기 위해 번들 bitnami/Redis 서브차트를 사용하는 경우, GitLab 차트의 7.0 버전으로 업그레이드하기 전에 Redis를 위한 StatefulSet을 수동으로 삭제해야 합니다. 아래의 번들된 Redis 서브차트 업그레이드 설정을 따르세요.

번들된 Redis 서브차트 업데이트

GitLab 차트의 7.0 릴리스는 번들된 bitnami/Redis 서브차트를 이전에 설치된 11.3.4에서 버전 16.13.2로 업데이트했습니다. 서브차트의 redis-master StatefulSet에 적용된 matchLabels의 변경으로, StatefulSet을 수동으로 삭제하지 않고 업그레이드하면 다음 오류가 발생합니다: 

Error: UPGRADE FAILED: cannot patch "gitlab-redis-master" with kind StatefulSet: StatefulSet.apps "gitlab-redis-master" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy' and 'minReadySeconds' are forbidden

RELEASE-redis-master StatefulSet을 삭제하려면:

  1. webservice, sidekiq, kas, 그리고 gitlab-exporter deployments의 레플리카 수를 0으로 축소하세요: 

    kubectl scale deployment --replicas 0 --selector 'app in (webservice, sidekiq, kas, gitlab-exporter)' --namespace <namespace>

  2. RELEASE-redis-master StatefulSet을 삭제하세요: 

    kubectl delete statefulset RELEASE-redis-master --namespace <namespace>
    • <namespace>를 GitLab 차트를 설치한 네임스페이스로 대체해야 합니다.

그런 다음 표준 업그레이드 단계를 따르세요. Helm이 변경 사항을 병합하는 방식 때문에, 1단계에서 축소한 deployments를 수동으로 확장해야 할 수 있습니다.

global.redis.password의 사용

global.redis.password의 구성 유형 충돌을 완화하기 위해 global.redis.password 사용을 폐기했습니다. 대신에 global.redis.auth를 사용하세요.

포용성 알림을 표시하는 동시에, helm upgrade로부터 다음 경고 메시지를 볼 경우: 

coalesce.go:199: warning: destination for password is a table. Ignoring non-table value

이는 당신이 values 파일에서 global.redis.password를 설정한 것을 나타냅니다.

Ingresses에서 useNewIngressForCerts 사용

기존 차트를 7.x에서 나중 버전으로 업그레이드하고 global.ingress.useNewIngressForCerts를 true로 변경하는 경우, 기존의 cert-manager Certificate 오브젝트를 업데이트하여 acme.cert-manager.io/http01-override-ingress-name 주석을 삭제해야 합니다.

이 변경을 해야 하는 이유는 이 속성이 false로 설정되어 있을 때 (기본값), 이 주석이 Certificates에 기본적으로 추가되며, cert-manager가 그 인그레스 메서드를 식별하는 데 사용하기 때문입니다. 이 주석은 단순히 이 속성을 false로 변경함으로써 자동으로 삭제되지 않습니다. 기존 인그레스에 대해 cert-manager가 이전 동작을 계속 사용하는 것을 막기 위해 수동 조치가 필요합니다.

버전 6.0으로 업그레이드

경고: 차트의 5.x 버전에서 최신 6.0 릴리스로 업그레이드하는 경우, 업그레이드가 작동하려면 먼저 최신 5.10.x 패치 릴리스로 업데이트해야 합니다. 6.0 릴리스 노트에는 지원되는 업그레이드 경로에 대해 설명되어 있습니다.

6.0 릴리스로 업그레이드하려면 먼저 최신 5.10.x 패치 릴리스에 있어야 합니다. 이후에 6.0에 대해 추가적인 수동 변경 사항이 필요하지 않으므로 일반 릴리스 업그레이드 단계를 따를 수 있습니다.

버전 5.9으로 업그레이드

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

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

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

  1. 왼쪽 사이드바에서 아래쪽에 있는 관리자 영역을 선택합니다.
  2. Settings > Metrics and profiling을 선택합니다.
  3. Metrics - Prometheus를 확장합니다.
  4. Health and performance metrics endpoint 활성화가 활성화되어 있는지 확인합니다.
  5. 영향을 받는 pod를 다시 시작합니다.

해당 시나리오에 대한 추가 대화는 닫힌 이슈에서 확인할 수 있습니다.

버전 5.5으로 업그레이드

task-runner 차트는 5.5.0에서 이름이 변경되었고 (toolbox로 이름이 변경되었으며 삭제되었습니다). 따라서 구성에서 task-runner 언급을 toolbox로 변경해야 합니다. 5.5 버전 이상에서는 toolbox 차트를 사용하고, 5.4 버전 이하에서는 task-runner 차트를 사용하세요.

객체 저장소 비밀값 누락 오류

5.5 이상으로 업그레이드하면 다음과 유사한 오류가 발생할 수 있습니다. 

오류: 업그레이드 실패: (gitlab/charts/gitlab/charts/toolbox/templates/deployment.yaml:227:23)에서 실행 오류: 유효한 backups.objectStorage.config.secret이 필요합니다!

오류 메시지에 언급된 시크릿이 이미 존재하고 올바른 경우, 이 오류는 여전히 toolbox 대신에 task-runner를 참조하는 객체 저장소 구성 값 때문입니다. 이 문제를 해결하려면 구성에서 task-runner를 toolbox로 이름을 변경하세요.

오류 메시지에 대한 명확화에 관한 오픈 이슈가 있습니다.

버전 5.0으로 업그레이드

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

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

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

외부 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 릴리스 업그레이드 프로세스 문제 해결

  • 업그레이드 중에 실패가 발생하면 세부 정보를 확인하기 위해 gitlab-upgrade-check 팟의 설명을 확인하는 것이 유용할 수 있습니다: 

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

4.8: Praefect 업그레이드 중 저장소 데이터 분실

Praefect 차트는 아직 제품으로 사용하기에 적합하다고 보지 않습니다.

차트 (GitLab 13.8) 버전 4.8로 업그레이드하기 전에 Praefect를 활성화한 경우, Gitaly의 StatefulSet 이름에 가상 스토리지 이름이 포함될 것임에 유의하십시오.

Praefect 차트의 4.8 버전에서는 여러 개의 가상 스토리지를 지정할 수 있는 기능이 추가되어 StatefulSet 이름을 변경해야 합니다.

기존의 Praefect 관리 Gitaly StatefulSet 이름 (따라서 연관된 PersistentVolumeClaims)은 변경되어 저장소 데이터가 손실된 것처럼 보일 것입니다.

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

  • 모든 저장소가 Gitaly 클러스터 전체에서 동기화되어 있으며 GitLab이 업그레이드 중이 아닙니다. 저장소가 동기화되어 있는지 확인하려면 Praefect 팟 중 하나에서 다음 명령을 실행하세요: 

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

  • 완전하고 테스트된 백업이 있습니다.

저장소 데이터는 이전 PersistentVolumeClaims에 연결하여 이전 PersistentVolumes에 다시 연결하는 지침을 제공하는 지속적 볼륨 관리 문서를 따라 복원할 수 있습니다.

이 프로세스의 중요한 단계는 이전 지속적 볼륨의 persistentVolumeReclaimPolicy를 Retain으로 설정하는 것입니다. 이 단계를 빠뜨리면 실제 데이터 손실이 발생할 가능성이 있습니다.

문서를 검토한 후, 관련된 이슈 댓글에 프로시저의 요약이 스크립트로 제공됩니다(https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2532#note_506467539).

PersistentVolumes를 다시 연결한 후, Praefect에서 read-only로 설정된 것으로 보이는 경우, Praefect 컨테이너에서 다음을 실행하여 확인하세요: 

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

이전 지속적 볼륨에서 모든 Git 저장소가 동기화되어 있는 경우, Praefect에서 Gitaly 클러스터를 고치기 위해 각 저장소에 대해 accept-dataloss 프로시저를 사용할 수 있습니다.

우리는 이것이 Praefect를 고치기 위한 최선의 접근 방법인지 확인하기 위해 이슈를 열어 두었습니다.