히스토리

• GitLab 18.0에서 virtual_registry_maven이라는 플래그로 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.1에서 기능 플래그가 maven_virtual_registry로 변경되었습니다. 기본적으로 비활성화되어 있습니다. 기능 플래그 virtual_registry_maven이 제거되었습니다.
• GitLab 18.1에서 실험에서 베타로 변경되었습니다.
• GitLab 18.2에서 GitLab.com, GitLab Self-Managed 및 GitLab Dedicated에서 활성화되었습니다.

GitLab 가상 레지스트리를 사용하여 단일의 잘 알려진 URL 뒤에서 여러 업스트림 레지스트리의 패키지를 프록시하고 캐시합니다.

이 방법을 사용하면 여러 업스트림 레지스트리 대신 하나의 가상 레지스트리를 사용하도록 애플리케이션을 구성할 수 있습니다.

사전 요구 사항#

가상 레지스트리를 구성하려면:

• Maintainer 또는 Owner 역할을 가진 최상위 그룹이 필요합니다.
• 가상 레지스트리 설정이 활성화되어 있는지 확인합니다. 기본적으로 활성화되어 있지만 관리자가 끌 수 있습니다.
• 의존성 프록시 설정이 활성화되어 있는지 확인합니다. 기본적으로 활성화되어 있지만 관리자가 끌 수 있습니다.
• 지원되는 패키지 형식에 대한 인증을 구성해야 합니다.

가상 레지스트리 끄기#

가상 레지스트리는 기본적으로 켜져 있습니다.

사전 요구 사항:

• 가상 레지스트리를 끄려면 관리자여야 합니다.

가상 레지스트리를 끄려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 설정 > 패키지 및 레지스트리를 선택합니다.
3. 가상 레지스트리 아래에서 가상 레지스트리 활성화 토글을 끕니다.

지원되는 패키지 형식#

• Maven 패키지
• 컨테이너 이미지

가상 레지스트리 인증#

히스토리

• GitLab 18.9에서 최상위 그룹 내 프로젝트의 직접 멤버에 대한 액세스가 제거되었습니다.

가상 레지스트리 엔드포인트는 다음 토큰 중 하나로 사용할 수 있습니다:

• 개인 액세스 토큰.
• 고려 중인 가상 레지스트리를 호스팅하는 최상위 그룹의 그룹 배포 토큰.
• 고려 중인 가상 레지스트리를 호스팅하는 최상위 그룹의 그룹 액세스 토큰.
• CI/CD 작업 토큰.
• Bearer 헤더 또는 쿼리 파라미터로 전송되는 OAuth 2.0 토큰.

토큰에는 다음 범위 중 하나가 필요합니다:

• api
• read_virtual_registry

액세스 토큰과 CI/CD 작업 토큰은 사용자로 확인됩니다. 확인된 사용자는 다음 중 하나여야 합니다:

• Guest, Planner, Reporter, Developer, Maintainer, 또는 Owner 역할을 가진 최상위 그룹의 직접 구성원.
• read_virtual_registry 권한을 가진 최소 액세스 커스텀 역할이 있는 최상위 그룹의 직접 구성원.
• GitLab 인스턴스 관리자.

가상 레지스트리 관리#

최상위 그룹의 가상 레지스트리를 관리합니다.

가상 레지스트리 만들기#

지원되는 패키지 형식 중 어느 것에 대해서도 가상 레지스트리를 만들 수 있습니다.

가상 레지스트리를 만들 때:

• 레지스트리는 주어진 패키지 형식의 최상위 그룹에서 호스팅됩니다. 프로젝트와 하위 그룹은 지원되지 않습니다.
• 가상 레지스트리 객체는 사용 가능한 업스트림의 순서가 있는 목록(최대 20개)에 링크됩니다. 각 업스트림은 외부 레지스트리를 가리킵니다.
• 외부 레지스트리는 공개 또는 비공개일 수 있습니다. 비공개 레지스트리의 자격 증명은 업스트림 자체에 저장되므로 패키지 관리자 구성에 저장할 필요가 없습니다.

가상 레지스트리 보기#

가상 레지스트리를 보려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 배포 > 가상 레지스트리를 선택합니다.

가상 레지스트리 편집#

기존 가상 레지스트리를 편집하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 배포 > 가상 레지스트리를 선택합니다.
3. 레지스트리 유형 아래에서 레지스트리 보기를 선택합니다.
4. 편집할 레지스트리의 행에서 편집 (✏️)을 선택합니다.
5. 변경 사항을 적용하고 변경 사항 저장을 선택합니다.

가상 레지스트리 삭제#

가상 레지스트리를 삭제하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 배포 > 가상 레지스트리를 선택합니다.
3. 레지스트리 유형 아래에서 레지스트리 보기를 선택합니다.
4. 레지스트리 탭 아래의 삭제할 레지스트리 행에서 편집 (✏️)을 선택합니다.
5. 레지스트리 삭제를 선택합니다.
6. 확인 대화 상자에서 삭제를 선택합니다.

업스트림 레지스트리 관리#

최상위 그룹의 가상 레지스트리에서 업스트림 레지스트리를 관리합니다.

업스트림 레지스트리 보기#

업스트림 레지스트리를 보려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 배포 > 가상 레지스트리를 선택합니다.
3. 레지스트리 유형 아래에서 레지스트리 보기를 선택합니다.
4. 사용 가능한 모든 업스트림을 보려면 업스트림 탭을 선택합니다.

업스트림 레지스트리 편집#

업스트림 레지스트리를 편집하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 배포 > 가상 레지스트리를 선택합니다.
3. 레지스트리 유형 아래에서 레지스트리 보기를 선택합니다.
4. 업스트림 탭을 선택합니다.
5. 편집할 업스트림의 행에서 편집 (✏️)을 선택합니다.
6. 변경 사항을 적용하고 변경 사항 저장을 선택합니다.

업스트림 레지스트리 재정렬#

업스트림 레지스트리의 순서는 패키지를 쿼리하는 우선순위를 결정합니다.

업스트림 레지스트리의 순서를 변경하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 배포 > 가상 레지스트리를 선택합니다.
3. 레지스트리 유형 아래에서 레지스트리 보기를 선택합니다.
4. 레지스트리 탭 아래에서 레지스트리를 선택합니다.
5. 업스트림 아래에서 업스트림 위로 이동 또는 업스트림 아래로 이동을 선택하여 업스트림을 재정렬합니다.

업스트림 순서에 대한 모범 사례:

• 내부 패키지를 우선시하기 위해 비공개 레지스트리를 공개 레지스트리 앞에 배치합니다.
• 가장 많은 패키지가 있는 레지스트리를 목록 상단에 우선시합니다. 이 방법은:
  • 우선순위가 높은 레지스트리가 요청을 이행할 가능성을 높입니다
  • 유효한 업스트림 레지스트리를 찾기 위해 전체 순서 목록을 탐색하는 것을 방지합니다
• 더 빠르거나 신뢰할 수 있는 레지스트리를 목록에서 더 높은 위치에 배치합니다.
• 공개 종속성의 대체 수단으로 공개 레지스트리를 마지막에 배치합니다.
• 패키지가 가장 적은 레지스트리를 목록 하단에 배치합니다.

업스트림 순서에 대한 자세한 내용은 업스트림 우선순위를 참조하세요.

캐싱 시스템#

모든 업스트림 레지스트리에는 다음을 수행하는 캐싱 시스템이 있습니다:

• 요청을 캐시 항목에 저장합니다
• GitLab 가상 레지스트리에서 동일한 요청에 대한 응답을 제공합니다

이렇게 하면 같은 패키지를 요청할 때 가상 레지스트리가 업스트림에 다시 연락할 필요가 없습니다.

요청된 경로가 사용 가능한 업스트림 중 어느 것에도 캐시되지 않은 경우:

1. 가상 레지스트리는 요청을 이행할 수 있는 업스트림을 찾기 위해 순서가 있는 업스트림 목록을 탐색합니다.
2. 요청을 이행할 수 있는 업스트림이 발견되면 가상 레지스트리는 필요한 경우 제공된 자격 증명으로 업스트림에서 응답을 가져옵니다.

요청된 경로가 사용 가능한 업스트림 중 어느 것에 캐시된 경우:

1. 가상 레지스트리는 응답을 전달하기 전에 캐시 항목을 새로 고쳐야 하는지 여부를 확인하기 위해 캐시 유효 기간을 확인합니다.
2. 캐시가 유효한 경우 업스트림의 캐시 항목이 요청을 이행합니다.
   • 우선순위가 낮은 업스트림이 캐시에 요청이 있고, 우선순위가 높은 업스트림이 파일을 갖고 있지만 요청을 캐시하지 않은 경우 우선순위가 낮은 업스트림이 요청을 이행합니다. 가상 레지스트리는 업스트림의 순서 목록을 다시 탐색하지 않습니다.

가상 레지스트리는 요청을 이행할 업스트림을 찾을 수 없는 경우 404 Not Found 오류를 반환합니다.

캐시 유효 기간#

캐시 유효 기간은 캐시 항목이 요청을 이행하는 데 유효한 것으로 간주되는 시간(시간)을 설정합니다.

가상 레지스트리가 기존 캐시 항목에서 가져오기 전에 항목을 새로 고쳐야 하는지 여부를 결정하기 위해 캐시 유효 기간을 확인합니다.

항목이 유효 기간 외부에 있는 경우 가상 레지스트리는 업스트림 응답이 캐시의 응답과 동일한지 확인합니다. 만약:

• 응답이 동일한 경우 항목이 요청을 이행하는 데 사용됩니다.
• 응답이 동일하지 않은 경우 업스트림 캐시 항목을 덮어쓰기 위해 업스트림에서 응답을 다시 다운로드합니다.

네트워크 조건으로 인해 가상 레지스트리가 업스트림에 연결할 수 없는 경우 업스트림은 사용 가능한 캐시 항목으로 요청을 제공합니다.

가상 레지스트리가 캐시에서 요청과 관련된 응답을 가지고 있는 한 유효 기간 외부에 있더라도 해당 요청이 이행됩니다.

캐시 유효 기간 설정#

캐시 유효 기간은 요청을 이행하는 가상 레지스트리의 전반적인 성능에 중요합니다. 외부 레지스트리에 연락하는 것은 비용이 많이 드는 작업입니다. 더 짧은 유효 기간은 검사 횟수를 늘리고 더 긴 기간은 줄입니다.

0으로 설정하여 캐시 유효 검사를 끌 수 있습니다.

캐시 유효 기간의 기본값은 24시간입니다.

업스트림이 대상으로 하는 외부 레지스트리가 불변의 응답을 가지고 있다고 알려진 경우 캐시 유효 기간을 0으로 설정해야 합니다. 이는 종종 공식 공개 레지스트리의 경우입니다. 자세한 내용은 지원되는 패키지 형식을 확인하세요.

업스트림을 만들거나 편집할 때 캐시 유효 기간을 구성합니다.

캐시된 패키지 보기#

업스트림 레지스트리에서 캐시된 패키지를 보려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 배포 > 가상 레지스트리를 선택합니다.
3. 레지스트리 유형 아래에서 레지스트리 보기를 선택합니다.
4. 업스트림 탭 아래에서 업스트림을 선택합니다.
5. 캐시된 패키지의 캐시 메타데이터를 봅니다.

캐시 항목 삭제#

캐시 항목을 삭제하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 배포 > 가상 레지스트리를 선택합니다.
3. 레지스트리 유형 아래에서 레지스트리 보기를 선택합니다.
4. 레지스트리 탭 아래에서 레지스트리를 선택합니다.
5. 업스트림 옆에서 모든 캐시 지우기를 선택합니다.
   • 특정 캐시 항목을 삭제하려면 업스트림 옆에서 캐시 지우기를 선택합니다.

캐시 항목을 삭제하면 가상 레지스트리가 해당 파일에 대한 요청을 다음에 받을 때 업스트림 목록을 다시 탐색하여 요청을 이행할 수 있는 업스트림을 찾습니다.

오브젝트 스토리지 사용량#

캐시 항목은 dependency_proxy 버킷의 오브젝트 스토리지에 파일을 저장합니다.

오브젝트 스토리지 사용량은 최상위 그룹의 오브젝트 스토리지 사용 제한에 포함됩니다.

정리 정책#

히스토리

• GitLab 18.6에서 maven_virtual_registry라는 플래그로 도입되었습니다. 기본적으로 활성화되어 있습니다.
• GitLab 18.6에서 virtual_registry_cleanup_policies라는 플래그로 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.9에서 ui_for_virtual_registry_cleanup_policy라는 플래그로 정리 정책의 UI가 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.10에서 일반적으로 사용 가능해졌습니다. 기능 플래그 virtual_registry_cleanup_policies 및 ui_for_virtual_registry_cleanup_policy가 제거되었습니다.

가상 레지스트리는 성능과 가용성을 향상시키기 위해 업스트림 레지스트리의 패키지를 캐시합니다. 시간이 지남에 따라 이러한 캐시 항목이 누적되어 상당한 스토리지 공간을 소비할 수 있습니다. 정리 정책을 사용하여 캐시된 콘텐츠를 자동으로 관리하고 스토리지 사용량을 줄이세요.

정리 정책은 구성 가능한 규칙을 기반으로 캐시된 항목을 제거하는 예약된 작업입니다. 정리 정책이 실행되면 최근에 다운로드되지 않은 캐시 항목을 식별하고 스토리지에서 제거합니다.

정리 정책은 최상위 그룹의 모든 가상 레지스트리에 대해 설정됩니다.

정리 정책 워크플로우#

가상 레지스트리에서 정리 정책은:

1. 지정된 보존 기간 내에 다운로드되지 않은 캐시 항목을 식별합니다.
2. 오브젝트 스토리지에서 사용되지 않은 캐시 항목을 제거합니다.
3. 성능을 유지하기 위해 자주 액세스되는 캐시 항목을 보존합니다.

정리 정책은 업스트림 레지스트리에서 캐시된 콘텐츠에만 영향을 미칩니다. 다음에는 영향을 미치지 않습니다:

• 가상 레지스트리 구성
• 업스트림 레지스트리 설정
• 프로젝트의 패키지 레지스트리에 저장된 패키지

정리 정책 관리#

최상위 그룹의 가상 레지스트리에 대한 정리 정책을 관리합니다. 각 최상위 그룹은 해당 그룹의 모든 가상 레지스트리에 적용되는 최대 하나의 정리 정책을 가질 수 있습니다.

정리 정책 만들기#

정리 정책을 만들고 실행 빈도를 설정합니다.

사전 요구 사항:

• 최상위 그룹에 대한 Owner 역할이 있어야 합니다.
• 그룹에 대해 가상 레지스트리가 켜져 있어야 합니다.

정리 정책을 만들려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 설정 > 패키지 및 레지스트리를 선택합니다.
3. 가상 레지스트리 캐시 정리 정책 옆에서 정책 설정을 선택합니다.
4. 정리 정책 활성화 토글을 켭니다.
5. 정리 정책 설정을 구성합니다:
   • 정리 실행 드롭다운 목록에서 정리 정책이 실행되는 빈도를 선택합니다. 기본값은 매일입니다.
   • 마지막 (일) 이내에 액세스되지 않은 캐시 삭제 아래에서 숫자를 입력하여 사용되지 않은 캐시 항목이 삭제되는 빈도를 설정합니다. 기본값은 7일입니다. 1에서 365 사이여야 합니다.
   • 선택 사항. 이메일 알림 아래에서 이메일 알림을 받으려면 다음 확인란 중 하나 또는 둘 모두를 선택합니다:
     • 정리가 실행될 때 이메일 알림 보내기
     • 정리가 실패할 경우 이메일 알림 보내기
6. 변경 사항 저장을 선택합니다.

정리 정책 편집#

정리 정책이 실행되는 빈도를 결정하도록 정리 정책을 편집합니다.

사전 요구 사항:

• 최상위 그룹에 대한 Owner 역할.

정리 정책을 편집하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 설정 > 패키지 및 레지스트리를 선택합니다.
3. 가상 레지스트리 캐시 정리 정책 옆에서 정책 편집을 선택합니다.
4. 정리 정책을 변경합니다.
5. 변경 사항 저장을 선택합니다.

정리 정책 끄기#

최상위 그룹의 정리 정책을 끕니다. 끈 경우 정리 정책은 구성을 유지하지만 실행되지 않습니다. 기존 캐시 항목은 보존됩니다.

사전 요구 사항:

• 최상위 그룹에 대한 Owner 역할.

정리 정책을 끄려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준에 있어야 합니다.
2. 설정 > 패키지 및 레지스트리를 선택합니다.
3. 가상 레지스트리 캐시 정리 정책 옆에서 정책 편집을 선택합니다.
4. 정리 정책 활성화 토글을 끕니다.
5. 변경 사항 저장을 선택합니다.

정리 정책 설정#

다음 설정을 사용하여 정리 정책을 제어합니다:

• 주기: 정리 정책이 실행되는 빈도를 제어합니다. 사용 가능한 옵션에는 일별, 주별 및 월별 간격이 포함됩니다.
• 보존 기간: 마지막 다운로드 후 캐시 항목이 유지되는 기간을 결정합니다. 이 기간 내에 다운로드되지 않은 항목은 제거 대상이 됩니다.

정리 정책 실행 모니터링#

정리 정책이 실행된 후 다음 실행 메트릭을 볼 수 있습니다:

• 정책이 마지막으로 실행된 시간.
• 정책이 다음에 실행될 예정인 시간.
• 제거된 캐시 항목 수.
• 해제된 총 스토리지 공간.
• 실행 중 발생한 오류.

이러한 메트릭은 필요에 따라 설정을 조정할 수 있도록 정리 정책의 효과를 이해하는 데 도움이 됩니다.

성능 고려 사항#

가상 레지스트리 성능은 다음과 같은 요소에 따라 달라질 수 있습니다:

• 요청된 파일이 업스트림 레지스트리에서 캐시되었는지 여부
• 파일이 존재하는지 여부에 대해 업스트림 레지스트리가 얼마나 빠르게 응답할 수 있는지
• 종속성을 가져오는 클라이언트와 GitLab 인스턴스와의 근접성

트레이드오프#

가상 레지스트리는 공개 레지스트리보다 더 고급입니다. 가상 레지스트리로 종속성을 가져올 때 공개 레지스트리와 같은 다른 레지스트리보다 더 오래 걸릴 수 있습니다.

공개 레지스트리와 비교하여 가상 레지스트리는 여러 업스트림 레지스트리와 인증도 지원합니다.

업스트림 우선순위#

업스트림 레지스트리는 순서가 있는 목록으로 구성됩니다. 가상 레지스트리가 패키지에 대한 요청을 받으면:

• 레지스트리는 요청을 이행할 수 있는 업스트림을 찾기 위해 순서가 있는 업스트림 목록을 탐색합니다.
• 요청된 파일이 업스트림에서 발견되면 가상 레지스트리는 해당 파일을 반환하고 향후 요청을 위해 캐시합니다. 캐싱은 가상 레지스트리를 통해 한 번 이상 가져온 경우 종속성의 가용성을 높입니다.
• 캐시에서 요청된 파일을 찾을 수 없는 경우 가상 레지스트리는 요청을 이행할 수 있는 가장 높은 우선순위의 업스트림을 찾기 위해 순서 목록을 탐색합니다.

이 시스템은 가상 레지스트리의 성능에 눈에 띄게 영향을 미칩니다.

사용에 따른 성능 향상#

가상 레지스트리를 만들면 구성된 각 업스트림의 캐시가 비어 있습니다. 각 요청은 가상 레지스트리가 요청을 이행하기 위해 사용 가능한 업스트림 레지스트리 목록을 탐색해야 합니다. 이러한 초기 요청은 이행하는 데 더 오래 걸립니다.

업스트림 레지스트리가 요청을 캐시하면 동일한 요청을 이행하는 시간이 줄어듭니다. 시간이 지남에 따라 더 많은 업스트림 레지스트리가 더 많은 요청을 캐시함에 따라 가상 레지스트리의 전반적인 성능이 향상됩니다.

CI/CD 캐시 사용#

GitLab CI/CD의 캐싱을 사용하여 작업이 가상 레지스트리에서 종속성을 다운로드할 필요가 없도록 할 수 있습니다.

이 방법은 실행 시간을 향상시키지만 각 종속성에 대한 스토리지도 중복시킵니다(종속성은 CI/CD 캐시와 가상 레지스트리에 저장됩니다).