GitLab on Joonlog

GitLab Container Registry에 Docker Push 실패 TroubleShooting

Thu, 04 Dec 2025 09:00:00 +0900

GitLab Omnibus 설정 간 URL에 공인/사설 IP 혼용 시 Docker Push 실패 문제 해결

문제 상황

GitLab 웹 콘솔은 외부에서 접근해야 하니 공인 IP로 접근 필요
Jenkins나 다른 WAS 서버에서 이미지 Pull/Push할때 사설 IP로 접근 필요
- 그래서 gitlab.rb 파일에 external_url은 공인 IP, registry_external_url은 사설 IP 로 설정한 상황
- 여기서 docker push 테스트 시 푸시가 중간에서 끊김

원인 분석

GitLab Container Registry는 push 과정에서 이미지 blob을 업로드할 때, GitLab의 canonical URL(=external_url)을 기준으로 내부 리다이렉트 동작을 수행
동작 과정
1. 사용자는 사설 IP(registry_external_url)로 push 요청을 보냄
2. Registry는 manifest 처리 과정에서 GitLab API 엔드포인트를 호출함 → 이때 GitLab의 external_url(공인 IP)을 참조
3. 사설 → 공인으로 트래픽 루프가 발생
4. 클라우드 서버라 루프백이 막혀 있어 트래픽이 중간에 끊김
즉 GitLab의 두 URL이 서로 다른 네트워크 망을 가리킴으로 인해 redirect loop 구조가 발생

조치

external_url, registry_external_url을 IP가 아닌 도메인으로 설정
도메인은 공인 IP와 매핑하고, 사설 IP가 필요한 WAS 서버나 Jenkins 서버에서는 hosts 설정으로 IP를 사설 IP로 지정되도록 설정

결론

GitLab Container Registry는 push 과정에서 canonical URL을 기반으로 내부 API 호출 및 redirect가 발생하기 때문에 external_url과 registry_external_url 이 서로 다른 네트워크를 가리키면 push 실패가 발생할 수 있다.

이를 해결하려면 url을 도메인으로 설정해서 리다이렉트가 발생하지 않도록 해야 한다.

Linux 환경에서 GitLab Omnibus 설치

Sat, 25 Oct 2025 09:00:00 +0900

로컬 리눅스 환경에서 GitLab Omnibus를 설치하는 방법

컨테이너 이미지를 저장하기 위한 이미지 레지스트리 사용

환경

OS: Rocky 8.10

설치

패키지 설치

1

dnf install -y ca-certificates tzdata policycoreutils-python-utils

GitLab Omnibus 설치

Comunity Edition

1
2
3


curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash

EXTERNAL_URL="http://<IP/도메인>" dnf install -y gitlab-ce

GitLab 설정

/etc/gitlab/gitlab.rb

콘솔 접근 경로

1
2


# 기본 외부 URL 설정 
external_url "http://<IP/도메인>"

이미지 레지스트리

1
2


gitlab_rails['registry_enabled'] = true
registry_external_url "http://<IP/도메인>:5050"

레지스트리 경로가 https가 아닌 http이므로, 이미지를 푸시할 때 해당 서버에서 docker insecure 설정이 필요함

1
2
3
4
5
6
7


vim /etc/docker/daemon.json
---------------------------
{
 "insecure-registries": [
 "<ip/도메인>:5050"
 ]
}

(선택) 리포지토리 저장 위치 변경

1
2
3
4
5
6
7
8


gitaly['configuration'] = {
 storage: [
 {
 name: 'default',
 path: '/data/gitlab/repositories',
 },
 ],
}

(선택) 이미지 레지스트리 저장 위치 변경

1

gitlab_rails['registry_path'] = "/data/gitlab/registry"

설정 적용
1

gitlab-ctl reconfigure

루트 비밀번호 확인
- 루트 비밀번호가 저장된 파일은 24시간 뒤에 자동 삭제
1

cat /etc/gitlab/initial_root_password
http://로 콘솔 접근
- 정상 접근 확인!

참고

GitLab Omnibus Install 공식 문서: https://docs.gitlab.com/install/package/almalinux/

K8S에 구축한 GitLab Registry에 Container Image 푸시 시 blob upload unknown 에러 TroubleShooting

Sat, 27 Sep 2025 09:00:00 +0900

GitLab을 Helm Chart로 구축 + 브라우저에서 GitLab 접근 시 80 포트가 아닌 다른 포트로 접근해야 할 경우 발생하는 이슈 GitLab Helm Chart의 포트 설정이 80/443으로 고정되어 있기 때문에 발생

환경

자체 관리형 kubernetes이기에 외부용 L7 로드밸런서로 haproxy를 사용 중인 경우
helm chart로 GitLab 서버를 구축한 경우
외부에서 브라우저로 GitLab UI 접근 시 80포트가 아닌 8080과 같은 별도의 포트로만 접근해야하는 제약사항이 있는 경우

문제 상황

helm chart로 GitLab 서버 구축 후 <도메인>:<포트>로 접근 시 포트가 제거된 후 도메인으로만 강제 리다이렉션 되는 현상 발생
- 404 에러
브라우저 → HAProxy(8080) → GitLab(80) → 리다이렉트 응답

해결 방법

HAproxy 설정을 통해 포트를 포함해서 리다이렉트 하도록 설정

http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1

정규식 분석:
- ^http://gitlab.<도메인>/(.*)$ - 매칭 패턴
- http://gitlab.<도메인>:8080/\1 - 치환 결과
- \1 = 첫 번째 그룹 (.*) 내용 (URL 경로)
- 변환 예시:
  - 원본: Location: http://gitlab.<도메인>/users/sign_in
  - 변환: Location: http://gitlab.<도메인>/users/sign_in
외부 브라우저에서 GitLab 접근 시 포트를 붙여서 접근해야 될 경우 반드시 설정
설정하지 않으면 접근 시 자동으로 포트가 제거된 상태로 리다이렉션되어 404 에러

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 # Host 기반 라우팅
 ...
 use_backend metallb_backend_gitlab if { hdr(host) -i gitlab.<도메인> }
 ...

backend metallb_backend_gitlab
 http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1
 server gitlab 172.27.1.102:80

결과

브라우저가 8080포트를 포함해서 리다이렉트
HAProxy를 통한 접속 유지

K8S에 구축한 GitLab UI 접근 시 접근 포트가 제거된 상태로 강제 리다이렉션 TroubleShooting

Thu, 25 Sep 2025 09:00:00 +0900

GitLab을 Helm Chart로 구축 + 브라우저에서 GitLab 접근 시 80 포트가 아닌 다른 포트로 접근해야 할 경우 발생하는 이슈 GitLab Helm Chart의 포트 설정이 80/443으로 고정되어 있기 때문에 발생

환경

자체 관리형 kubernetes이기에 외부용 L7 로드밸런서로 haproxy를 사용 중인 경우
helm chart로 GitLab 서버를 구축한 경우
외부에서 브라우저로 GitLab UI 접근 시 80포트가 아닌 8080과 같은 별도의 포트로만 접근해야하는 제약사항이 있는 경우

문제 상황

helm chart로 GitLab 서버 구축 후 <도메인>:<포트>로 접근 시 포트가 제거된 후 도메인으로만 강제 리다이렉션 되는 현상 발생
- 404 에러
브라우저 → HAProxy(8080) → GitLab(80) → 리다이렉트 응답

해결 방법

HAproxy 설정을 통해 포트를 포함해서 리다이렉트 하도록 설정

http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1

정규식 분석:
- ^http://gitlab.<도메인>/(.*)$ - 매칭 패턴
- http://gitlab.<도메인>:8080/\1 - 치환 결과
- \1 = 첫 번째 그룹 (.*) 내용 (URL 경로)
- 변환 예시:
  - 원본: Location: http://gitlab.<도메인>/users/sign_in
  - 변환: Location: http://gitlab.<도메인>/users/sign_in
외부 브라우저에서 GitLab 접근 시 포트를 붙여서 접근해야 될 경우 반드시 설정
설정하지 않으면 접근 시 자동으로 포트가 제거된 상태로 리다이렉션되어 404 에러

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 # Host 기반 라우팅
 ...
 use_backend metallb_backend_gitlab if { hdr(host) -i gitlab.<도메인> }
 ...

backend metallb_backend_gitlab
 http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1
 server gitlab 172.27.1.102:80

결과

브라우저가 8080포트를 포함해서 리다이렉트
HAProxy를 통한 접속 유지

자체 관리형 Kubernetes에서의 GitLab 구축

Wed, 24 Sep 2025 09:00:00 +0900

매니지드 K8S가 아닌 자체 관리형 K8S에서의 GitLab 구축 방법

UI 접근을 위한 외부 통신으로 MetalLB+HAproxy+Nginx Controller가 구성 되었다는 전제 하에 구축

CSP 환경이라면 Ingress 설정에서 AWS ALB Controller와 같은 로드밸런서를 사용해 훨씬 간편하게 구축 가능

GitLab 공식문서: ****https://docs.gitlab.com/install/install_methods/#helm-chart
GitLab Artifacthub 문서: https://artifacthub.io/packages/helm/gitlab/gitlab

GitLab 설치

Helm 리포지토리 추가

1
2


helm repo add gitlab https://charts.gitlab.io/
helm repo update

gitlab 네임스페이스 생성
1

kubectl create ns gitlab

gitlab-pv 생성(StorageClass 없을 시에만 진행)

기존에 사용하던 Ceph, Longhorn, EBS Driver, Harbor 같은 StorageClass가 없을 경우에 로컬 경로를 사용한 PV 할당 방법
- StorageClass가 있다면 PVC 생성 시 자동으로 PV가 할당되기 때문에 이 과정은 불필요

1
2


vim gitlab-01-volume.yaml
kubectl apply -f gitlab-01-volume.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


apiVersion: v1
kind: PersistentVolume
metadata:
 name: gitlab-pv
spec:
 storageClassName: gitlab-pv
 accessModes:
 - ReadWriteOnce
 capacity:
 storage: 20Gi
 persistentVolumeReclaimPolicy: Retain
 hostPath:
 path: /data/gitlab-volume/

---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: gitlab-pv
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer

gitlab 설치

values.yaml 수정
- helm으로 설치

1
2
3
4


helm show values gitlab/gitlab > values.yaml
vim values.yaml

helm install gitlab -n gitlab -f values.yaml gitlab/gitlab

소스코드 리포지토리 설정

1
2
3
4
5
6


# GitLab Gitaly (Git 저장소)
gitlab:
 gitaly:
 persistence:
 storageClass: "longhorn"
 size: 20Gi

postgresql, redis 설정
- postgresql: gitlab 전체의 메타데이터 저장
  - redis: 사용자 세션, 백그라운드 작업, 캐시, 알림 등에 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# PostgreSQL
postgresql:
 primary:
 persistence:
 storageClass: "longhorn"
 size: 8Gi

# Redis 
redis:
 master:
 persistence:
 storageClass: "longhorn"
 size: 2Gi

minio설정
- https://docs.gitlab.com/charts/charts/globals#configure-minio-settings
- S3와 호환되는 오브젝트 스토리지

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


global:

 # minio 서비스 활성화
 minio:
 enabled: true

 # 바이너리 파일들이 오브젝트 스토리지를 사용할 수 있도록 설정
 appConfig:
 object_store
 enabled: true

 # Container Registry가 minio의 registry 버킷을 사용
 registry:
 bucket: registry

# minio가 Longhorn을 통한 PV 사용
minio:
 persistence:
 enabled: true
 size: 10Gi
 storageClass: longhorn

불필요한 기능 비활성화

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


global:
 lfs:
 enabled: false
 uploads:
 enabled: false
 toolbox:
 enabled: false

# GitLab KAS 비활성화 (Kubernetes Agent)
global:
 kas:
 enabled: false

# CI/CD 관련 비활성화
global:
 appConfig:
 artifacts:
 enabled: false
 packages:
 enabled: false

# 모니터링 비활성화
prometheus:
 install: false

# GitLab Runner 비활성화
gitlab-runner:
 install: false

도메인, 에디션(CE/EE)

1
2
3
4


global:
 edition: ce
 hosts:
 domain: <도메인>

http 접근을 위한 설정

1
2
3
4
5
6
7
8


global:
 hosts:
 https: false
 ingress:
 configureCertmanager: false
 tls:
 enabled: false
installCertmanager: false

GitLab UI

GitLab Helm Chart를 통해 ingress는 생성 완료!

values.yaml 내에 ingress 생성을 위한 nginx 설정이 포함되어 있음

HAproxy 설정

ingress를 조회하여 MetalLB로부터 부여받은 IP 확인

현재는 172.27.1.102

1
2
3
4


# kubectl get ingress -n gitlab
NAME CLASS HOSTS ADDRESS PORTS AGE
gitlab-registry gitlab-nginx registry.<도메인> 172.27.1.102 80 61m
gitlab-webservice-default gitlab-nginx gitlab.<도메인> 172.27.1.102 80 61m

확인한 IP를 HAproxy 설정에 추가

HAproxy 서버 공인 IP로 접근 시 gitlab의 Ingress로 통신되도록 설정
http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:<포트>/\\1
두 조건을 만족할 경우 설정 필요
- 외부 브라우저에서 GitLab 접근 시 포트를 붙여서 접근해야 될 경우
- 애플리케이션 내부적으로 url로 응답이 나오도록 설정되어 있을 경우
  - EX) GitLab 로그인 시 GitLab에 설정된 url 응답
설정하지 않으면 접근 시 자동으로 포트가 제거된 상태로 리다이렉션되어 404 에러

1
2
3


vim /etc/haproxy/haproxy.cfg
haproxy -c -f /etc/haproxy/haproxy.cfg
systemctl reload haproxy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 http-request set-header X-Forwarded-Host %[req.hdr(host)]
 http-request set-header X-Forwarded-Proto http
 http-request set-header X-Forwarded-Port %[dst_port]

 # Host 기반 라우팅
 use_backend metallb_backend_gitlab if { hdr(host) -m sub gitlab }
 # GitLab Container Registry를 위한 경로
 use_backend metallb_backend_gitlab if { hdr(host) -m sub registry }

backend metallb_backend_gitlab
 http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:<포트>/\\1
 server gitlab 172.27.1.100:80

접근 성공!

gitlab 관리자(root) 비밀번호 확인

1

kubectl get secret gitlab-gitlab-initial-root-password -n gitlab -o jsonpath="{.data.password}" | base64 --decode