Helm v2에서 Helm v3로 이전하기
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로 마이그레이션하는 방법
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에서 설정됨)으로 변경할 수 없습니다. 따라서 이들은 강제로 대체되어야 합니다.
이 문제를 해결하려면 다음 지침을 사용하십시오:
참고: 이 지침은 _강제로 리소스를 대체_합니다. 특히 Redis StatefulSet을 대체합니다. 이 StatefulSet에 첨부된 데이터 볼륨이 안전하고 그대로 유지되도록 보장해야 합니다.
- (활성화된 경우) 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 -
- (선택 사항) Redis StatefulSet이 요청하는 PV에
persistentVolumeReclaimPolicy를Retain으로 설정합니다. 이는 PV가 부주의하게 삭제되지 않도록 보장하기 위한 조치입니다.
kubectl patch pv <PV-NAME> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
- 기존 Redis PVC의
heritage라벨을Helm으로 설정합니다.
kubectl label pvc -l app=redis --overwrite heritage=Helm
- 캐스케이드 없이 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 권한이 있어야 합니다. 자신에게 완전한 RBAC 권한을 부여하려면 다음을 실행하세요:
kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=your-user-name@domain.tld
이후 helm upgrade가 정상적으로 작동해야 합니다.
도움말