GitLab Managed Apps에서 Cluster Management Projects로 마이그레이션 (더 이상 사용되지 않음)

요약

GitLab Managed Apps는 사용자가 직접 제어하는 Cluster Management 프로젝트로 대체되면서 더 이상 사용되지 않습니다. GitLab Managed Apps에서 Cluster Management 프로젝트로 마이그레이션하려면 아래 단계를 따릅니다.

GitLab Managed Apps는 사용자가 직접 제어하는 Cluster Management 프로젝트로 대체되면서 더 이상 사용되지 않습니다. 프로젝트를 통해 클러스터 애플리케이션을 관리하면 종료된 GitLab Managed Apps를 사용할 때보다 훨씬 유연하게 클러스터를 관리할 수 있습니다. Cluster Management 프로젝트로 마이그레이션하려면 GitLab Runner를 사용할 수 있어야 하고 Helm에 익숙해야 합니다.

Cluster Management Project로 마이그레이션#

GitLab Managed Apps에서 Cluster Management 프로젝트로 마이그레이션하려면 아래 단계를 따릅니다. 예시가 포함된 동영상 안내도 함께 참고합니다.

Cluster Management Project 템플릿을 기반으로 새 프로젝트를 만듭니다.
클러스터에서 이 프로젝트에 대한 에이전트를 설치합니다.
프로젝트 템플릿의 .gitlab-ci.yml에 안내된 대로, KUBE_CONTEXT CI/CD 변수를 새로 설치한 에이전트의 컨텍스트로 설정합니다.
사전 구성된 .gitlab-ci.yml 파일을 사용해 Helm v2 릴리스로 배포된 앱을 탐지합니다.
- 기본 GitLab Managed Apps 네임스페이스를 덮어쓴 적이 있다면 .gitlab-ci.yml을 편집해 스크립트가 올바른 네임스페이스를 인수로 받는지 확인합니다.
```
script:
  - gl-fail-if-helm2-releases-exist <your_custom_namespace>
```
- 기본 이름(gitlab-managed-apps)을 그대로 두었다면 스크립트는 이미 설정되어 있습니다.
어느 경우든 파이프라인을 수동으로 실행하고 detect-helm2-releases job의 로그를 읽어 보유한 Helm v2 릴리스가 있는지 확인합니다.
Helm v2 릴리스가 없다면 이 단계를 건너뜁니다. 있다면 Helm 공식 문서의 Helm v2에서 Helm v3으로 마이그레이션하는 방법을 따르고, 마이그레이션이 성공했다고 확신한 뒤에 Helm v2 릴리스를 정리합니다.
이 단계에서는 이미 Helm v3 릴리스만 남아 있어야 합니다. 메인 ./helmfile.yaml에서 이 프로젝트로 관리하려는 애플리케이션의 경로 주석을 해제합니다. 관리하려는 애플리케이션의 주석을 한 번에 모두 해제할 수도 있지만, 진행 도중 혼란을 겪지 않으려면 앱마다 다음 단계를 따로 반복하는 편이 좋습니다.
해당 앱에 배포된 차트 버전과 일치하도록 연관된 applications/{app}/helmfiles.yaml을 편집합니다. GitLab Runner Helm v3 릴리스를 예로 들면 다음과 같습니다.

다음 명령은 릴리스와 그 버전을 나열합니다.
```
helm ls -n gitlab-managed-apps

NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
runner gitlab-managed-apps 1 2021-06-09 19:36:55.739141644 +0000 UTC deployed gitlab-runner-0.28.0 13.11.0
```
{release}-v{chart_version} 형식으로 표시되는 CHART 칼럼에서 버전을 가져온 다음, 배포된 버전과 일치하도록 ./applications/gitlab-runner/helmfile.yaml의 version: 속성을 편집합니다. 이는 마이그레이션 도중 버전이 업그레이드되는 일을 막기 위한 안전 장치입니다. 앱을 다른 네임스페이스에 배포했다면 앞의 명령에서 gitlab-managed-apps를 해당 네임스페이스로 바꿉니다.
배포된 값과 일치하도록 앱에 연관된 applications/{app}/values.yaml을 편집합니다. 예를 들어 GitLab Runner의 경우는 다음과 같습니다.
1. 다음 명령의 출력을 복사합니다(내용이 클 수 있습니다).
```
helm get values runner -n gitlab-managed-apps -a --output yaml
```
2. 앞 명령의 출력으로 applications/gitlab-runner/values.yaml을 덮어씁니다.
이 안전 장치는 예기치 않은 기본값이 배포된 값을 덮어쓰지 않도록 보장합니다. 예를 들어 GitLab Runner의 gitlabUrl 이나 runnerRegistrationToken 이 실수로 덮어써질 수 있습니다.
일부 앱은 별도의 주의가 필요합니다.
- Ingress: 알려진 차트 이슈 때문에 ./gl-helmfile 명령을 실행할 때 spec.clusterIP: Invalid value가 나타날 수 있습니다. 이를 우회하려면 applications/ingress/values.yaml의 릴리스 값을 덮어쓴 뒤 omitClusterIP: false가 나오는 모든 위치를 omitClusterIP: true로 덮어써야 할 수 있습니다. 다른 방법으로는 kubectl get services -n gitlab-managed-apps를 실행해 이 IP들을 수집한 다음, 오류가 발생한 각 ClusterIP를 그 명령에서 얻은 값으로 덮어쓸 수도 있습니다.
- Vault: 이 애플리케이션은 Helm v2에서 사용하던 차트와 Helm v3에서 사용하는 차트 사이에 호환성이 깨지는 변경이 있습니다. 따라서 이 Cluster Management 프로젝트와 통합하는 유일한 방법은 앱을 제거하고 applications/vault/values.yaml에 제안된 차트 버전을 수용하는 것입니다.
- Cert-manager:
  - Kubernetes 1.20 이상을 사용하는 경우, 더 이상 사용되지 않는 cert-manager v0.10은 유효하지 않으며 업그레이드에 호환성이 깨지는 변경이 포함됩니다. 따라서 cert-manager v0.10을 백업하고 제거한 뒤 최신 cert-manager를 설치해야 합니다. 이 버전을 설치하려면 ./helmfile.yaml에서 applications/cert-manager/helmfile.yaml의 주석을 해제합니다. 그러면 새 버전을 설치하는 파이프라인이 트리거됩니다.
  - Kubernetes 1.20 미만을 사용하는 경우, 프로젝트의 메인 Helmfile(./helmfile.yaml)에서 applications/cert-manager-legacy/helmfile.yaml의 주석을 해제해 v0.10을 계속 사용할 수 있습니다.
    
    [!warning] cert-manager v0.10은 Kubernetes를 1.20 이상으로 업그레이드하면 동작하지 않습니다.
앞의 모든 단계를 마친 뒤 파이프라인을 수동으로 실행하고 apply job 로그를 확인해 애플리케이션이 정상적으로 탐지·설치되었는지, 예기치 않은 업데이트가 발생하지는 않았는지 살펴봅니다.

일부 애노테이션 체크섬과 다음 속성은 업데이트되는 것이 정상입니다.
```
--- heritage: Tiller
+++ heritage: Tiller
```

파이프라인이 성공하고 나면, Cluster Management 프로젝트로 관리하려는 다른 배포 앱에 대해서도 이 단계를 반복합니다.

cert-manager v0.10 백업 및 제거#

cert-manager v0.10 데이터를 백업하는 방법은 공식 문서를 참고합니다.
applications/cert-manager/helmfile.yaml 파일을 편집해 installed: true가 나오는 모든 위치를 installed: false로 설정하여 cert-manager를 제거합니다.
kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges,Secrets,ConfigMaps -n gitlab-managed-apps | grep certmanager 명령을 실행해 남아 있는 리소스를 검색합니다.
앞 단계에서 찾은 각 리소스를 kubectl delete -n gitlab-managed-apps {ResourceType} {ResourceName}로 삭제합니다. 예를 들어 cert-manager-controller라는 이름의 ConfigMap 타입 리소스를 찾았다면 다음을 실행해 삭제합니다. kubectl delete configmap -n gitlab-managed-apps cert-manager-controller

동영상 안내#

GMA에서 Cluster Management 프로젝트로 마이그레이션하는 예시는 다음 동영상에서 확인할 수 있습니다.

완전히 새로운 Cluster Management 프로젝트를 사용해 처음부터 마이그레이션. Helm v2 앱 마이그레이션도 다룹니다.
기존 GitLab Managed Apps CI/CD 프로젝트에서 마이그레이션.

GitLab Managed Apps에서 Cluster Management Projects로 마이그레이션 (더 이상 사용되지 않음)

GitLab v19.5

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-09-18

요약