OS 패키지 문제 해결

Artifact Registry에서 OS 패키지를 관리할 때 문제가 발생할 경우 도움이 될 수 있는 문제 해결 단계에 대해 알아보세요.

OS 패키지의 Artifact Registry 원격 저장소 문제를 해결하는 방법에 대한 자세한 내용은 원격 저장소 문제 해결을 참조하세요.

인증 및 권한 문제

패키지 설치와 같은 작업을 위해 저장소에 연결할 수는 없습니다. 패키지 관리자의 출력에는 인증 또는 권한의 문제를 나타내는 401 또는 403 오류가 포함됩니다.

Apt 오류 예시:

Err:1 ar+https://us-central1-apt.pkg.dev/projects/my-project my-package Release
  Error downloading: code 401

E: Failed to fetch https://us-central1-apt.pkg.dev/projects/my-project/dists/quickstart-apt-repo/main/binary-amd64/Packages  403  Forbidden [IP: 74.125.20.82 443]
E: Some index files failed to download. They have been ignored, or old ones used instead.

Yum 오류 예시:

/repodata/repomd.xml: [Errno 14] HTTPS Error 403 - Forbidden

이러한 오류의 원인은 여러 가지가 있습니다. VM이 다음 요구사항을 충족하는지 확인합니다.

  1. VM에 연결된 서비스 계정이 있는지 확인합니다.

    Compute Engine VM

    1. VM 인스턴스 페이지로 이동합니다.

    2. VM 목록에서 VM의 이름을 클릭합니다.

      세부정보 탭에서 서비스 계정 및 액세스 범위가 API 및 ID 관리에 표시됩니다.

    기본적으로 Compute Engine VM은 Compute Engine 기본 서비스 계정을 사용하며 액세스 범위가 제한되어 있습니다. 기본 서비스 계정 이메일 주소는 PROJECT_NUMBER-compute@developer.gserviceaccount.com 형식입니다.

    서비스 계정을 변경하거나 서비스 계정을 VM에 연결하려면 인스턴스의 서비스 계정 및 액세스 범위 변경을 참조하세요.

    기타 VM

    다른 VM에서는 VM을 대신할 서비스 계정이 있어야 합니다.

    1. 서비스 계정이 없는 경우 서비스 계정을 만듭니다.

    2. 별도의 단계에서 권한을 구성할 필요가 없도록 서비스 계정을 만드는 동안 Artifact Registry 리더(roles.artifactregistry.reader) 역할을 부여합니다.

  2. VM 서비스 계정에 저장소에 대한 읽기 권한과 cloud-platform API 액세스 범위가 있는지 확인합니다.

    Compute Engine VM

    Artifact Registry는 VM 서비스 계정 사용자 인증 정보를 자동으로 가져옵니다. 필요한 구성은 기본 서비스 계정을 사용하는지 또는 사용자 관리 서비스 계정을 사용하는지에 따라 달라집니다.

    기본 서비스 계정

    VM에서 기본 서비스 계정을 사용하는 경우 이 서비스 계정에는 기본적으로 편집자 역할이 있으며, 이 역할에는 동일한 프로젝트의 저장소에 대한 읽기 권한이 포함됩니다. 저장소가 VM과 다른 프로젝트에 있는 경우 Artifact Registry 리더 역할을 VM 서비스 계정에 부여합니다.

    또한 기본 서비스 계정에는 필요한 일부 API 액세스 범위가 없습니다.

    cloud-platform 액세스 범위를 설정하려면 다음 안내를 따르세요.

    1. VM 인스턴스를 중지하고 INSTANCE를 VM 인스턴스 이름으로 바꿉니다.

      gcloud compute instances stop INSTANCE

    2. 액세스 범위를 설정합니다.

      gcloud compute instances set-service-account INSTANCE \
    --scopes=cloud-platform

    3. VM 인스턴스를 다시 시작합니다.

      gcloud compute instances start INSTANCE
    사용자 관리 서비스 계정
    VM에서 사용자 관리 서비스 계정을 사용하는 경우 Artifact Registry 리더 역할을 VM 서비스 계정에 부여합니다. 사용자 관리 서비스 계정에는 cloud-platform 액세스 범위가 있습니다.

    기타 VM

    Artifact Registry 리더 역할을 VM 서비스 계정에 부여합니다. 기본적으로 사용자 관리 서비스 계정에는 cloud-platform 액세스 범위가 있습니다.

  3. VM이 저장소에 액세스하도록 준비하는 단계를 따랐는지 확인합니다. Apt 또는 Yum 준비 안내를 참조하세요.

  4. 저장소에 액세스하도록 Apt 또는 Yum을 올바르게 구성했는지 확인합니다.

    Compute Engine VM에서 Apt 저장소에 연결하는 경우 저장소 URL에 ar+ 프리픽스가 포함되어 있는지 확인합니다.

사용자 인증 정보 도우미 문제

VM이 Apt 사용자 인증 정보 도우미를 찾을 수 없는 경우 다음 오류 메시지가 표시됩니다.

E: Unable to locate package apt-transport-artifact-registry

이 오류는 Apt 저장소 서명 키가 포함되어 있지 않은 이미지로 만든 VM에 apt-transport-artifact-registry 패키지를 설치하려고 할 때 발생합니다.

이 문제를 해결하려면 다음 단계를 따르세요.

  1. VM에 서명 키를 설치합니다.

    Debian VM

    다음 명령어를 사용하여 Apt 저장소 서명 키를 설치합니다.

    curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add -

    LOCATION을 저장소 위치로 바꿉니다.

    Ubuntu VM

    다음 명령어를 사용하여 Apt 저장소 서명 키를 설치합니다.

    curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add - && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

    LOCATION을 저장소 위치로 바꿉니다.

  2. VM 준비 단계를 다시 시도합니다.

인증 플러그인 문제

Yum 또는 DNF 인증 플러그인에 문제가 있으면 다음 오류 메시지가 표시됩니다.

Plugin "artifact-registry" can't be imported

이 오류는 여러 가지 이유로 발생할 수 있습니다. 오류를 해결하려면 플러그인을 직접 실행하여 종속 항목을 확인하거나 Python 문제를 확인하거나 가능한 다른 기본적인 문제를 파악합니다.

플러그인을 직접 실행하려면 다음 명령어 중 하나를 사용합니다.

  • Yum 플러그인의 경우:

    python /usr/lib/yum-plugins/artifact-registry.py

  • DNF 플러그인의 경우:

    python3 /usr/lib/pythonVERSION-NUMBER/site-packages/dnf-plugins/artifact-registry.py

    VERSION-NUMBER를 Linux 배포판의 기본 Python 버전으로 바꿉니다. 예를 들어 Enterprise Linux 8에는 Python 3.6이 포함되어 있습니다.

    설치된 플러그인 패키지의 파일을 나열하여 Python 라이브러리 디렉터리의 이름을 확인할 수 있습니다.

    rpm -ql dnf-plugin-artifact-registry|grep artifact-registry.py

최근에 업로드된 아티팩트 누락

Apt 또는 Yum 클라이언트가 최근 저장소에 업로드했거나 가져온 패키지를 찾지 못하는 경우 Apt 또는 Yum 패키지 색인을 다시 생성하는 프로세스가 아직 완료되지 않았기 때문일 수 있습니다.

소규모 저장소의 경우 Apt 또는 Yum 색인 파일을 다시 생성하려면 몇 초가 걸릴 수 있습니다. 대규모 저장소의 경우 색인을 다시 생성하는 데 몇 분 이상 걸릴 수 있습니다.

패키지가 저장소에 성공적으로 추가되었는지 확인하려면 Google Cloud CLI를 사용하여 패키지의 파일을 나열합니다. 다음 명령어를 실행합니다.

gcloud artifacts files list \
    --package=PACKAGE \
    --project=PROJECT-ID \
    --repository=REPOSITORY \
    --location=LOCATION

예를 들어 다음 명령어를 사용하여 python3-gflags_1.5.1-5_all.deb이라는 python-gflags 패키지가 us-central1-apt.pkg.dev\apt-project\apt-repo 저장소에 성공적으로 업로드되었는지 확인할 수 있습니다.

gcloud artifacts files list \
    --package=python-gflags \
    --project=apt-project \
    --repository=apt-repo \
    --location=us-central1

패키지가 성공적으로 업로드된 경우 다음 예시와 같이 출력에는 파일 이름에 고유한 식별자가 있는 파일이 표시됩니다.

FILE                                                                  CREATE_TIME          UPDATE_TIME          SIZE (MB)  OWNER
pool/python3-gflags_1.5.1-5_all_2414c7af6a64c99a5f488aad366d637a.deb  2023-01-12T20:39:53  2023-01-12T20:39:53  0.035      projects/apt-project/locations/us-central1/repositories/apt-repo/packages/python3-gflags/versions/1.5.1-5

업로드 또는 가져온 일부 패키지에 대한 인증 오류

파일을 가져오거나 업로드하는 시간이 인증 토큰 만료 기간을 초과하면 만료 기간이 지난 업로드는 실패합니다. 토큰은 받은 후 60분 후에 만료됩니다. 토큰이 만료되면 가져오기 명령어의 출력에 다음 예시와 비슷한 오류가 표시됩니다.

errors:
- error:
    code: 16
    message: The request does not have valid authentication credentials.
  gcsSource:
    uris:
    - gs://my-bucket/debs/python/python3-gflags_1.5.1-5_all.deb

이 문제를 해결하려면 다음 안내를 따르세요.

  1. 일괄 가져오기 대신 개별적으로 패키지를 추가할 수 있는지 확인하는 경우에만 특정 패키지를 업로드하거나 가져옵니다.
  2. 여러 패키지가 실패한 경우 작업이 토큰 만료 기간을 초과하지 않도록 소규모 배치로 가져오거나 업로드합니다.