Helm v2에서 Helm v3로 이주

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

Helm v2가 공식적으로 Deprecated되었습니다, 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로 마이그레이션하는 방법

GitLab 릴리즈를 Helm v2에서 Helm v3로 마이그레이션하려면 Helm 2to3 플러그인을 사용할 수 있습니다. 이 마이그레이션 플러그인에 대한 자세한 설명과 예제는 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으로의 마이그레이션과 관련된 알려진 이슈로, 일부 배포와 StatefulSet의 heritage 레이블이 변경 불가능하여 Tiller(Helm 2가 설정)에서 Helm(Helm 3이 설정)으로 변경할 수 없습니다. 따라서 이들을 강제로 대체해야 합니다.

이를 해결하려면 다음 지침을 사용하십시오:

note
이 지침은 리소스를 강제로 대체합니다. 특히 Redis StatefulSet을 대체합니다. 해당 StatefulSet에 연결된 데이터 볼륨이 안전하고 유지되도록 보장해야 합니다.
  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-이름> -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를 사용하지 않으며 클러스터 관리자로 helm upgrade를 실행 중이더라도 사용자 계정에 적절한 RBAC 권한이 있어야 합니다. 자신에게 전체 RBAC 권한을 부여하려면 다음을 실행하십시오. 

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

그 후에 helm upgrade가 잘 작동해야 합니다.