패키지에 대한 의존성 프록시

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
Status: Beta
caution
의존성 프록시는 베타입니다. 이 기능을 사용하기 전에 문서를 주의 깊게 검토하세요.

GitLab 패키지에 대한 의존성 프록시는 자주 가져오는 패키지에 대한 로컬 프록시입니다.
프로젝트 수준에서 작동하는 풀 스루 캐시로 구현됩니다.

패키지는 업스트림 패키지 레지스트리에서 가져오고 자동으로
프로젝트의 패키지 레지스트리에 게시됩니다. 이후 동일한 요청은 프로젝트의
패키지 레지스트리로 서비스를 제공합니다. 의존성 프록시를 사용하여
업스트림 레지스트리로의 불필요한 트래픽을 줄일 수 있습니다.

의존성 프록시 활성화

패키지에 대한 의존성 프록시를 사용하려면, 프로젝트가 올바르게 설정되어 있는지 확인하고, 캐시에서 가져오는 사용자가 필요한 인증을 가지고 있는지 확인하세요:

  1. 전역 구성에서 다음 기능이 비활성화된 경우 활성화하세요:
  2. 프로젝트 설정에서 package 기능이 비활성화된 경우 활성화하세요. 기본값으로 활성화됨.
  3. 인증 방법 추가하기. 의존성 프록시는 패키지 레지스트리와 같은 인증 방법을 지원합니다:

고급 캐싱

가능한 경우, 패키지에 대한 의존성 프록시는 프로젝트의 패키지 레지스트리에 패키지를 저장하기 위해 고급 캐싱을 사용합니다.

고급 캐싱은 프로젝트의 패키지 레지스트리와
업스트림 패키지 레지스트리 간의 일관성을 검증합니다. 업스트림 레지스트리에 파일이 업데이트된 경우,
의존성 프록시는 이를 사용하여 캐시된 파일을 업데이트합니다.

고급 캐싱이 지원되지 않으면, 의존성 프록시는 기본 동작으로 돌아갑니다:

  • 요청된 파일이 프로젝트의 패키지 레지스트리에서 발견되면 반환됩니다.
  • 파일이 발견되지 않으면 업스트림 패키지 레지스트리에서 가져옵니다.

고급 캐싱 지원은 업스트림 패키지 레지스트리가
의존성 프록시 요청에 어떻게 응답하는지에 따라 달라지며,
사용하는 패키지 형식에 따라 달라집니다.

Maven
패키지 레지스트리 고급 캐싱 지원 여부?
GitLab 예
Maven Central 예
Artifactory 예
Sonatype Nexus 예
GitHub Packages 아니요

권한

의존성 프록시가 파일을 가져오면 다음이 발생합니다:

  1. 의존성 프록시는 프로젝트의 패키지 레지스트리에서 파일을 검색합니다.
    이것은 읽기 작업입니다.
  2. 의존성 프록시는 프로젝트의 패키지 레지스트리에 패키지 파일을 게시할 수 있습니다.
    이것은 쓰기 작업입니다.

두 단계가 모두 실행되는지는 사용자 권한에 따라 다릅니다.
의존성 프록시는 패키지 레지스트리와 동일한 권한을 사용합니다.

프로젝트 가시성 최소 역할 패키지 파일을 읽을 수 있나요? 패키지 파일을 쓸 수 있나요? 동작
공개 익명 아니요 아니요 요청 거부됨.
공개 손님 예 아니요 캐시 또는 원격 레지스트리에서 패키지 파일 반환.
공개 개발자 예 예 캐시 또는 원격 레지스트리에서 패키지 파일 반환. 파일은 캐시에 게시됨.
내부 익명 아니요 아니요 요청 거부됨
내부 손님 예 아니요 캐시 또는 원격 레지스트리에서 패키지 파일 반환.
내부 개발자 예 예 캐시 또는 원격 레지스트리에서 패키지 파일 반환. 파일은 캐시에 게시됨.
비공개 익명 아니요 아니요 요청 거부됨
비공개 보고자 예 아니요 캐시 또는 원격 레지스트리에서 패키지 파일 반환.
비공개 개발자 예 예 캐시 또는 원격 레지스트리에서 패키지 파일 반환. 파일은 캐시에 게시됨.

최소한 의존성 프록시를 사용할 수 있는 모든 사용자는 프로젝트의 패키지 레지스트리도 사용할 수 있습니다.

캐시가 시간이 지나면서 적절하게 채워지도록 하려면, 최소한 개발자 역할을 가진 사용자가 의존성 프록시를 사용하여 패키지를 가져오도록 해야 합니다.

클라이언트 구성하기

의존성 프록시에 대한 클라이언트 구성은 패키지 레지스트리에 대한 클라이언트 구성과 유사합니다.

Maven 패키지용

Maven 패키지의 경우, 패키지 레지스트리에서 지원하는 모든 클라이언트 가 의존성 프록시에서 지원됩니다:

  • mvn
  • gradle
  • sbt

인증을 위해 Maven 패키지 레지스트리에서 허용되는 모든 방법을 사용할 수 있습니다.
기본 HTTP 인증 방법을 사용하는 것이 복잡성이 적기 때문에 권장됩니다.

클라이언트를 구성하려면:

  1. 기본 HTTP 인증 지침을 따르세요.

    엔드포인트 URL https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven를 사용하고 있는지 확인하세요.

  2. 클라이언트 구성을 완료하세요:

mvn

기본 HTTP 인증이 허용됩니다.
하지만 mvn이 더 적은 네트워크 요청을 사용하도록 하려면 사용자 지정 HTTP 헤더 인증을 사용하는 것이 좋습니다.

pom.xml 파일에 repository 요소를 추가하세요:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven</url>
  </repository>
</repositories>

여기서:

  • <project_id>는 의존성 프록시로 사용될 프로젝트의 ID입니다.
  • <id>에는 인증 구성에서 사용된 <server>의 이름이 포함됩니다.

기본적으로 Maven Central은 Super POM을 통해 먼저 확인됩니다.
하지만 mvn이 GitLab 엔드포인트를 먼저 확인하도록 강제할 수 있습니다. 그렇게 하려면 요청 전달 지침을 따르세요.

gradle

build.gradle 파일에 repositories 섹션을 추가하세요.

  • Groovy DSL에서:

    repositories {
    maven {
        url "https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven"
        name "GitLab"
        credentials(PasswordCredentials) {
            username = 'REPLACE_WITH_NAME'
            password = gitLabPrivateToken
        }
        authentication {
            basic(BasicAuthentication)
        }
    }
}

  • Kotlin DSL에서:

    repositories {
    maven {
        url = uri("https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven")
        name = "GitLab"
        credentials(BasicAuthentication::class) {
            username = "REPLACE_WITH_NAME"
            password = findProperty("gitLabPrivateToken") as String?
        }
        authentication {
            create("basic", BasicAuthentication::class)
        }
    }
}

이 예에서:

  • <project_id>는 의존성 프록시로 사용될 프로젝트의 ID입니다.
  • REPLACE_WITH_NAME은 기본 HTTP 인증 섹션에서 설명됩니다.
sbt

build.sbt 파일에 다음 줄을 추가하세요:

resolvers += ("gitlab" at "https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven")

credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<token>")

이 예에서:

  • <project_id>는 의존성 프록시로 사용될 프로젝트의 ID입니다.
  • <host>는 프로토콜 스킴이나 포트가 없는 <endpoint url>에 있는 호스트입니다. 예: gitlab.example.com.
  • <name>과 <token>은 기본 HTTP 인증 섹션에서 설명됩니다.

원격 레지스트리 구성

의존성 프록시는 다음으로 구성해야 합니다:

  • 원격 패키지 레지스트리의 URL.
  • 선택 사항. 필수 자격 증명.

그러한 매개변수를 설정하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 패키지 및 레지스트리를 선택합니다.
  3. 의존성 프록시 아래에서 패키지 형식에 대해 양식을 작성합니다:
Maven

모든 Maven 패키지 레지스트리는 의존성 프록시에 연결할 수 있습니다. Maven 패키지 레지스트리의 사용자 이름과 암호로 연결을 인증할 수 있습니다.

원격 Maven 패키지 레지스트리를 설정하거나 업데이트하려면 양식의 다음 필드를 업데이트합니다:

  • URL - 원격 레지스트리의 URL.
  • Username - 선택 사항. 원격 레지스트리와 함께 사용할 사용자 이름.
  • Password - 선택 사항. 원격 레지스트리와 함께 사용할 비밀번호.

사용자 이름과 비밀번호를 모두 설정하거나 두 필드를 모두 비워야 합니다.

문제 해결

수동 파일 풀 오류

cURL을 사용하여 수동으로 파일을 끌어올 수 있습니다.

그러나 다음 응답 중 하나를 경험할 수 있습니다:

  • 404 Not Found - 의존성 프록시 설정 객체를 찾을 수 없습니다. 존재하지 않거나 요구 사항이 충족되지 않았기 때문입니다.
  • 401 Unauthorized - 사용자가 제대로 인증되었지만 의존성 프록시 객체에 접근할 적절한 권한이 없습니다.
  • 403 Forbidden - GitLab 라이센스 수준에 문제가 있었습니다.
  • 502 Bad Gateway - 원격 패키지 레지스트리가 파일 요청을 처리할 수 없습니다. 의존성 프록시 설정을 확인하세요.
  • 504 Gateway Timeout - 원격 패키지 레지스트리가 시간 초과되었습니다. 의존성 프록시 설정을 확인하세요.
Maven
curl --fail-with-body --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/<group id and artifact id>/<version>/<file_name>"
  • <username> 및 <personal access token>은 GitLab 인스턴스의 의존성 프록시에 접근하기 위한 자격 증명입니다.
  • <project_id>는 프로젝트 ID입니다.
  • <group id and artifact id>는 Maven 패키지 그룹 ID 및 아티팩트 ID로 슬래시로 연결됩니다.
  • <version>은 패키지 버전입니다.
  • file_name은 파일의 정확한 이름입니다.

예를 들어, 다음과 같은 패키지가 주어진 경우:

  • 그룹 ID: com.my_company.
  • 아티팩트 ID: my_package.
  • 버전: 1.2.3.

패키지를 수동으로 끌어오는 요청은 다음과 같습니다:

curl --fail-with-body --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/com/my_company/my_package/1.2.3/my_package-1.2.3.pom"