Proxmox 기반 쿠버네티스 클러스터에 GitLab을 Helm으로 신규 설치하면서 겪은 문제들을 정리합니다. 공식 문서만 보고 따라가면 최신 차트 버전에서 특히 막히는 지점들이 있어서, 실제로 부딪힌 순서대로 씁니다.

상황

기존에 gitlab-postgresql, gitlab-redis 서브차트만 배포된 상태에서 GitLab 본체(webservice, gitaly, sidekiq 등)를 새로 설치해야 했습니다.

bash

helm upgrade --install gitlab gitlab/gitlab \ --create-namespace --namespace gitlab \ -f gitlab-values.yaml

이 한 줄이 통과되기까지 몇 가지 큰 장벽이 있었습니다.

1. 최신 차트에서 번들 서브차트가 완전히 사라짐

기존 values.yaml에 있던 postgresql.install, redis.install, minio.install 같은 설정이 최신 GitLab Helm chart에서는 아예 거부됩니다. 번들 postgresql/redis/minio 서브차트가 차트에서 완전히 제거됐기 때문입니다.

해결: 기존 release와 PVC/시크릿을 정리하고, bitnami/postgresql, bitnami/redis를 완전히 독립된 release로 재설치했습니다. 이후 GitLab 본체는 gitlab-values.yaml에서 외부 DB/Redis로 연결하도록 구성했습니다.

2. MinIO 기본값이 3노드 클러스터에 안 맞음

MinIO를 기본 설정(distributed 모드, 16 replicas)으로 설치하면 3노드 클러스터에서는 Pod 다수가 Pending 상태에 머뭅니다.

해결: mode=standalone, replicas=1로 재설치.

3. Gateway API CRD 충돌

GitLab 19.0부터 차트 기본값이 Gateway API + 번들 Envoy Gateway로 바뀌면서, 두 가지 문제가 연달아 발생했습니다.

• 설치 단계: Kubernetes 클러스터 버전(v1.30.14)이 CEL 함수를 지원하지 않아 Gateway API CRD와 기존 Calico CRD가 충돌 → --skip-crds 옵션으로 우회

• 배포 후: haproxy-ingress가 이미 있는 상태에서 envoy-gateway Pod가 계속 CrashLoopBackOff로 재생성됨

두 번째 문제는 envoy-gateway.enabled 같은 잘못된 키로는 해결이 안 되고, 올바른 키인 global.gatewayApi.enabled=false와 installEnvoy=false를 함께 설정해야 envoy-gateway가 완전히 사라집니다.

4. 백업 오브젝트 스토리지 설정 경로 오류

global.appConfig.backups.objectStorage라는 경로로 설정했다가 실패했는데, 이 경로 자체가 존재하지 않습니다. 올바른 경로는 global.appConfig.backups.bucket / tmpBucket이며, 실제 오브젝트 스토리지 연결 정보는 gitlab.toolbox.backups.objectStorage.config에 지정해야 합니다.

5. PostgreSQL 기본 리소스로는 마이그레이션이 끝나지 않음

설치는 성공해도 gitlab-postgresql이 기본 리소스(memory 192Mi)로는 GitLab 스키마 마이그레이션(1,893개)을 처리하다가 계속 재시작하며 마이그레이션이 끝없이 실패했습니다.

해결: primary.resources를 memory 1~2Gi, cpu 500m~1로 상향. 이후 마이그레이션이 끝까지 완료되고 admin 계정과 시드 데이터까지 정상 생성됐습니다.

정리

최신 GitLab Helm chart로 신규 설치할 때 체크리스트:

1. values.yaml에 postgresql/redis/minio install 옵션이 남아있는지 → 최신 차트는 거부함, 독립 release로 분리

2. MinIO는 클러스터 노드 수에 맞게 mode/replicas 조정

3. Gateway API 관련 CRD 충돌 여부 → --skip-crds

4. Envoy Gateway 비활성화는 global.gatewayApi.enabled=false + installEnvoy=false로

5. PostgreSQL 리소스를 기본값보다 넉넉히 (최소 1Gi 메모리) 잡을 것

이 다섯 가지만 미리 알고 시작해도 설치 시간을 상당히 줄일 수 있습니다.