Helm v2에서 Helm v3로 마이그레이션하기

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

Helm v2는 2020년 11월에 공식적으로 사용 중단되었습니다. GitLab Helm 차트 버전 5.0(GitLab 앱 버전 14.0)부터 Helm v2.x를 사용한 설치 및 업그레이드는 더 이상 지원되지 않습니다. 향후 GitLab 업데이트를 받으려면 Helm v3로 마이그레이션해야 합니다.

Helm v2와 Helm v3 간의 변경 사항

Helm v3는 Helm v2와 호환되지 않는 많은 변경 사항을 도입합니다. 주요 변경 사항 중 일부는 Tiller 요구 사항의 제거와 클러스터에서 릴리스 정보를 저장하는 방식 변경입니다. Helm v3 변경 사항 개요 및 Helm v2 FAQ 변경 사항에서 더 자세히 읽어보세요.

응용 프로그램을 배포하는 데 사용하는 Helm 차트가 최신 또는 이전 버전의 Helm과 호환되지 않을 수 있습니다. Helm v2로 배포되고 관리되는 여러 응용 프로그램이 있는 경우 이들 역시 Helm v3와 호환되는지 확인해야 합니다. GitLab Helm 차트는 GitLab Helm 차트 v3.0.0 버전부터 Helm v3.0.2 이상을 지원합니다. Helm v2는 더 이상 지원되지 않습니다.

현재 실행 중인 응용 프로그램의 관점에서는 Helm v2에서 v3로 마이그레이션을 수행할 때 아무런 변화가 없습니다. Helm v2에서 v3로의 마이그레이션은 일반적으로 안전하지만, 예방 조치로 Helm v2의 백업을 꼭 수행하시기 바랍니다.

Helm v2에서 Helm v3로 마이그레이션하는 방법

Helm 2to3 플러그인을 사용하여 GitLab 릴리스를 Helm v2에서 Helm v3로 마이그레이션할 수 있습니다. 이 마이그레이션 플러그인에 대한 더 자세한 설명과 몇 가지 예시는 Helm 블로그 게시물을 참조하세요: Helm v2에서 Helm v3로 마이그레이션하는 방법입니다.

여러 사람이 GitLab Helm 설치를 관리하는 경우 각 로컬 머신에서 helm3 2to3 move config를 수행해야 할 수 있습니다. helm3 2to3 convert는 한 번만 수행하면 됩니다.

알려진 문제

마이그레이션 후 “UPGRADE FAILED: cannot patch” 오류가 표시됨

마이그레이션 후에 후속 업그레이드가 실패할 수 있는 오류가 다음과 비슷하게 표시될 수 있습니다:

Error: UPGRADE FAILED: cannot patch "..." with kind Deployment: Deployment.apps "..." is invalid: spec.selector:
Invalid value: v1.LabelSelector{...}: field is immutable

또는

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

이는 Cert Manager 및 Redis 종속성과 관련된 Helm 2에서 3으로의 마이그레이션에 대한 알려진 문제 때문입니다. 요약하자면, 일부 배포 및 스테이트풀 세트의 heritage 레이블은 불변이며 Helm 2에서 설정된 ‘Tiller’에서 Helm 3에서 설정된 ‘Helm’으로 변경할 수 없습니다. 따라서 이를 강제로 교체해야 합니다.

이를 해결하기 위해 다음 지침을 사용하세요:

note
이 지침은 _자원을 강제로 교체_하며, 특히 Redis StatefulSet에 주의가 필요합니다. 이 StatefulSet에 연결된 데이터 볼륨이 안전하고 intact 상태인지 확인해야 합니다.
  1. cert-manager 배포를 교체합니다(활성화된 경우).
kubectl get deployments -l app=cert-manager -o yaml | sed "s/Tiller/Helm/g" | kubectl replace --force=true -f -
kubectl get deployments -l app=cainjector -o yaml | sed "s/Tiller/Helm/g" | kubectl replace --force=true -f -
  1. (선택 사항) Redis StatefulSet이 사용하는 PV에서 persistentVolumeReclaimPolicy를 Retain으로 설정합니다.
    이는 PV가 실수로 삭제되지 않도록 하기 위함입니다.
kubectl patch pv <PV-NAME> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
  1. 기존 Redis PVC의 heritage 레이블을 Helm으로 설정합니다.
kubectl label pvc -l app=redis --overwrite heritage=Helm
  1. Redis StatefulSet을 종속성 없이 교체합니다.
kubectl get statefulsets.apps -l app=redis -o yaml | sed "s/Tiller/Helm/g" | kubectl replace --force=true --cascade=false -f -

Helm 업그레이드 후 마이그레이션 시 RBAC 문제

마이그레이션이 완료된 후 Helm 업그레이드를 실행할 때 다음 오류가 발생할 수 있습니다:

Error: UPGRADE FAILED: pre-upgrade hooks failed: warning: Hook pre-upgrade gitlab/templates/shared-secrets/rbac-config.yaml failed: roles.rbac.authorization.k8s.io "gitlab-shared-secrets" is forbidden: user "your-user-name@domain.tld" (groups=["system:authenticated"]) is attempting to grant RBAC permissions not currently held:
{APIGroups:[""], Resources:["secrets"], Verbs:["get" "list" "create" "patch"]}

Helm2는 이러한 작업을 수행하기 위해 Tiller 서비스 계정을 사용했습니다. Helm3는 더 이상 Tiller를 사용하지 않으며, 명령을 실행하기 위해서는 사용자가 적절한 RBAC 권한을 보유해야 합니다. 클러스터 관리자로 helm upgrade를 실행하더라도 마찬가지입니다. 본인에게 전체 RBAC 권한을 부여하려면 다음을 실행하세요:

kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=your-user-name@domain.tld

그 후, helm upgrade가 정상적으로 작동해야 합니다.