GitLab CI/CD 트러블슈팅 모음(CI/CD)

1. CI 패키지 설치 단계 최적화 ( Setup Stage + 증분 캐시 적용 )

---

 

2. CI 캐시 스냅샷 누적 문제 및 키 전략 표준화

---

 

3. GitLab CI/CD 캐시 Miss 문제 및 MinIO 기반 개선

---

3-1. 어떤 문제가 있었을까?

GitLab CI/CD에서 Job이 실행될 때, 
Runner의 슬롯 단위로 캐시가 분리되어 있어 Job간 캐시 공유가 이뤄지지 않았다...

이로 인해 특정 Job에서 이미 캐시된 결과물이 존재하는 상황에도, 
→ 매 실행마다 패키지 및 의존성을 다시 Full 다운로드하는 비효율이 발생하였다.

 

[ Runner 설정만으로 해결이 어려웠던 이유 ]

GitLab Runner의 로컬 캐시는 구조적으로 "슬롯 단위 격리 + 실행 안정성 중심" 설계로 되어 있어
"공유 효율성"과 "동시성 안정성"을 동시에 만족시키기 어렵다.

1) 슬롯 분리 구조 (기본 동작)
Runner
 ├── Slot 0 → cache A (local volume)
 ├── Slot 1 → cache B (local volume)
 └── Slot 2 → cache C (local volume)
 
 [문제점]
 - 슬롯 간 캐시 공유 불가..
 - 동일 캐시 의존성이 슬롯마다 중복 저장
 결과: disk 낭비 또는 Full install 비효율
 
 
 2) 볼륨 공유 방식 (강제 설정)
 Slot 0 ─┐
Slot 1 ─┼── /shared/cache (same volume)
Slot 2 ─┘

[문제점]
- 동시에 캐시 의존성에 접근할 경우 → 레이스 컨디션 발생
- 캐시 손상 위험

즉, Runner 로컬 캐시는 구조적으로 격리하면 안전하지만 공유가 안되고, 공유하면 안전하지 않은 구조입니다.

---

3-2. 어떤 선택지를 비교했고 왜 MinIO를 선택했는가?

GitLab Runner의 '공유 효율성'과 '동시성 안정성'간의 트레이드오프를 해결하기 위해, 동시 쓰기 시 파일 오염이 없는 "객체 교체" 방식의 객체 스토리지 도입 필요성을 느꼈습니다.

 

[ 개선된 아키텍처 ]

                ┌──────────────────────┐
                │   GitLab CI/CD      │
                └─────────┬────────────┘
                          │
                ┌─────────▼────────────┐
                │   GitLab Runner      │
                │ (Slot-based Execution│
                └─────────┬────────────┘
                          │
        ┌─────────────────┴─────────────────┐
        │                                   │
   Cache Upload                       Cache Download
        │                                   │
        └──────────────┬────────────────────┘
                       ▼
        ┌────────────────────────────────────┐
        │  Object Storage Central Cache Hub  │
        │  (S3-compatible key-value store)   │
        └────────────────────────────────────┘

 

[ 객체 오브젝트 선택지 비교 ]

각 슬롯 간 캐시 공유를 위해 Key 기반 접근이 가능한 중앙 저장소 구조가 필요했으며, 이에 따라 S3 호환 스토리지인 AWS S3 vs MinIO를 비교하였습니다.

비교 항목	AWS S3	MinIO
네트워크	외부 인터넷 경유 (지연 발생 가능)	사내망/로컬 통신 (고속)
비용	저장/전송량 기반 지속 과금	자체 인프라 기반 (추가 비용 거의 없음)
구축 난이도	IAM, 권한 등 설정 복잡	Docker 기반 간단 구축
운영 환경	클라우드 중심	온프레미스 최적화

• 최종 선택: MinIO
  • 비용 부담 없이 S3 AP 호환 구조 사용 가능
  • 데모/온프레미스 환경 특성상 클라우드 대비 단순하고 적합

하지만 추후 오브젝트 스토리지 대규모 확장 시, MinIO는 고가용성(HA) 아키텍처 구성과 인프라 유지보수를 위한 자체 운영 비용이 부담되는 반면, AWS S3는 완전 관리형 구조로 운영 리스크 없는 무제한 확장을 지원하므로 S3로의 전환을 고려할 수 있습니다.

---

3-3. 무엇을 실행했는가?

• MinIO 서버를 구축하여 S3 호환 객체 스토리지 구성 MinIO 구축 가이드(CI/CD)

MinIO 구축 가이드(CI/CD)

 

[ GitLab Runner 설정 변경 ]

## /etc/gitlab-runner/config.toml

[runners.cache]
  Type = "s3"
  Shared = true

  [runners.cache.s3]
    ServerAddress = "192.168.56.60:12000"
    AccessKey = "admin"
    SecretKey = "admin12345"
    BucketName = "gitlab-ci-cache"
    Insecure = true

• [runners.cache]를 로컬 캐시 → S3(MinIO)로 전환
• 모든 Job이 동일한 캐시 버킷( gitlab-ci-cache ) 사용하도록 설정
• CI 파이프라인에서는 기존 전역 캐시 키( uv-cache-global )를 유지하여 모든 Job이 동일 캐시를 참조하도록 구조를 단일화

---

3-4. 어떤 결과가 나왔고 어떻게 측정했는가?

• 캐시 적중률 100% 달성
• 빌드 시간 대폭 단축
  • 캐시 Miss(기존)
    • 전체 Job 실행: 6분 26초
    • 패키지 설치: Prepared 218 packages in 5m 37s
    • uv resolve: uv resolve: 3.37s
  • 캐시 Hit(개선 후)
    • 전체 Job 실행: 약 1분 39초
    • cache restore: 약 1분 39초 (다운로드 포함 but 재사용됨)
    • 패키지 설치 46.70s
    • uv resolve: 309ms
• 러너 디스크 안정화
  • 슬롯별로 생성되던 중복 캐시 볼륨이 제거되어 디스크 누수 문제 해결

항목	Cache Miss	Cache Hit
전체 Job	6분 26초	1분 39초
uv resolve	3.37s	0.309s
패키지 설치	5분 37초	46초
다운로드	전체 발생	대부분 생략

---

3-5. 최종 정리

GitLab CI/CD 캐시를 MinIO 기반 중앙 저장소로 전환하여 캐시 적중률 100%를 달성하고, 빌드 시간을 약 6분 → 1분 30초 수준으로 단축하였다. 또한 로컬 Docker 기반 캐시 볼륨 생성 문제를 제거하여 디스크 누수 구조를 해결하였다.

---