데브옵스
폐쇄망 Maven 빌드가 429를 만난다면 - GitLab Virtual Registry로 의존성 에러 해결하기
두줄요약
폐쇄망 Maven 빌드에서 발생하는 429 에러의 원인과 구조를 정리하고 GitLab Maven Virtual Registry로 해결하는 방법을 설명했습니다. 캐싱 프록시와 upstream 순서 설정으로 외부 요청을 줄이는 실전 팁도 함께 다뤘습니다.
문제 상황
- 폐쇄망 CI에서 NAT 게이트웨이 뒤 Maven 빌드가 Maven Central 429 응답으로 자주 중단되는 현상
- IP 공유, Maven Resolver의 기본 병렬 다운로드, 동적 rate limit이 겹치며 재시도만으로는 원인 파악이 어려운 구조
원인 분석
- 외부에서 동일 IP로 묶이는 NAT 환경 특성상 여러 빌드·사용자 트래픽이 한도에 합산되는 문제
- 기본 5개 병렬 다운로드로 짧은 시간에 다수 요청이 발생하는 Maven Resolver 동작
- Maven Central의 IP별 동적 consumption limits로 예측 가능한 고정 한도 부재
해결 방법
- GitLab Maven Virtual Registry를 캐싱 프록시로 두어 외부 의존성 요청을 흡수하는 구조로 전환
- 사내 비공개 레지스트리 → Apache Releases·Spring → Maven Central 순으로 upstream을 배치
- settings.xml의 mirror 설정과 GitLab 토큰 인증으로 클라이언트 연결 구성