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으로 마이그레이션하는 방법

헬름 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

이는 Helm 2에서 Helm 3으로의 마이그레이션 중 Cert Manager 및 Redis 종속성에 문제가 있기 때문입니다. 요점은 일부 배포 및 StatefulSet의 heritage 라벨이 불변이며 Tiller(Helm 2에서 설정)에서 Helm(Helm 3에서 설정)로 변경할 수 없다는 것입니다. 따라서 이들을 강제로 대체해야 합니다.

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

참고: 이 지침은 _리소스를 강제로 대체_합니다. 특히 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-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를 사용하지 않으며 사용자 계정은 helm upgrade를 실행할 때 적절한 RBAC 권한을 가져야 합니다. 심지어 클러스터 관리자로 helm upgrade를 실행 중이더라도, 자신에게 적절한 RBAC 권한을 부여하려면 다음을 실행하십시오: 

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

이후에는 helm upgrade가 제대로 작동해야 합니다.