Python 패키지 저장소용 Artifact Registry에 대한 인증 구성

이 페이지에서는 Artifact Registry Python 패키지 저장소로 인증을 구성하는 방법을 설명합니다.

제3자 애플리케이션을 사용하여 저장소에 연결할 때는 Artifact Registry에 인증해야 합니다.

Cloud Build 또는 Google Kubernetes Engine 및 Cloud Run과 같은 Google Cloud 런타임 환경에 대한 인증을 구성할 필요는 없지만 필요한 권한이 구성되어 있는지 확인해야 합니다.

시작하기 전에

대상 저장소가 없으면 새 Python 패키지 저장소를 만듭니다.
Python 3이 설치되어 있는지 확인합니다. 설치 안내는 Google Cloud Python 설정 튜토리얼을 참조하세요.
사용 중인 사용자 계정 또는 서비스 계정에 저장소에 액세스하는 데 필요한 권한이 있는지 확인합니다.
Google Cloud CLI를 설치한 후 다음 명령어를 실행하여 초기화합니다.
```
gcloud init
```
참고: gcloud CLI를 이전에 설치했으면 gcloud components update를 실행하여 최신 버전을 사용할 수 있는지 확인합니다.
(선택사항) cloud CLI 명령어의 기본값을 구성합니다.

개요

Artifact Registry는 다음과 같은 인증 방법을 지원합니다.

Python 키링 라이브러리(권장): Artifact Registry는 키링 백엔드를 제공하여 Artifact Registry 저장소에 연결하기 위한 사용자 인증 정보를 저장합니다.
비밀번호 인증: 키링을 사용할 수 없고 기본 비밀번호 인증을 지원하는 옵션이 필요한 경우에 이 옵션을 사용합니다.

이 문서의 안내에서는 pip에서 패키지를 검색하는 유일한 패키지 색인으로 pip를 구성하는 방법을 설명합니다. pip 구성 파일에서 여러 패키지 색인을 구성하는 대신 가상 저장소를 사용하여 Artifact Registry의 비공개 패키지와 PyPI의 공개 패키지에서 패키지를 검색하는 것이 좋습니다. pip 도구는 특정 순서로 패키지 색인을 검색하지 않으므로 소비자가 비공개 패키지 중 하나와 이름이 같은 공개 패키지를 잘못 다운로드하거나 설치할 수 있습니다. 가상 저장소를 사용하면 업스트림 소스의 우선순위를 구성하여 이러한 종속 항목 혼동 위험을 완화할 수 있습니다.

키링으로 인증

Python 키링 라이브러리는 운영체제 및 서드 파티 사용자 인증 정보 저장소를 의미하는 키링 백엔드에 액세스하는 방법을 애플리케이션에 제공합니다.

Artifact Registry는 keyrings.google-artifactregistry-auth 키링 백엔드를 제공하여 Artifact Registry 저장소의 인증을 처리합니다.

사용자 인증 정보 검색 순서

Artifact Registry 키링 백엔드를 사용하면 사용자 인증 정보가 Python 프로젝트에 저장되지 않습니다. 대신 Artifact Registry가 다음 순서로 사용자 인증 정보를 검색합니다.

애플리케이션 기본 사용자 인증 정보(ADC) - 다음 순서로 사용자 인증 정보를 찾는 전략
1. GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 정의된 사용자 인증 정보
2. Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine 또는 Cloud Functions의 기본 서비스 계정에서 제공하는 사용자 인증 정보
gcloud auth application-default login 명령어의 사용자 인증 정보를 포함한 Google Cloud CLI에서 제공하는 사용자 인증 정보

GOOGLE_APPLICATION_CREDENTIALS 변수를 사용하면 인증용 계정이 명시적으로 표시되어 문제 해결이 간편해집니다. 이 변수를 사용하지 않는 경우 ADC에서 사용할 수 있는 모든 계정에 필요한 권한이 있는지 확인합니다. 예를 들어 Compute Engine VM, Google Kubernetes Engine 노드, Cloud Run 버전의 기본 서비스 계정은 저장소에 대한 읽기 전용 액세스 권한이 있습니다. 기본 서비스 계정을 사용하여 이러한 환경에서 업로드하려면 권한을 수정해야 합니다.

키링 설정

Artifact Registry 키링 백엔드로 인증을 설정하려면 다음 안내를 따르세요.

키링 라이브러리를 설치합니다.
```
pip install keyring
```

Artifact Registry 백엔드를 설치합니다.

pip install keyrings.google-artifactregistry-auth

백엔드를 나열하여 설치를 확인합니다.
```
keyring --list-backends
```
이 목록에는 다음 항목이 포함됩니다.
- ChainerBackend(priority:10)
- GooglePythonAuth(priority: 9)
다음 명령어를 실행하여 Python 프로젝트에 추가할 저장소 구성을 출력합니다.
```
gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION
```
다음 값을 바꿉니다.
- PROJECT는 프로젝트 ID입니다. 이 플래그를 생략하면 현재 프로젝트 또는 기본 프로젝트가 사용됩니다.
- REPOSITORY는 저장소 ID입니다. 기본 Artifact Registry 저장소를 구성한 경우 이 플래그가 명령어에서 생략되었을 때 사용됩니다.
- LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
.pypirc 파일에 다음 설정을 추가합니다. 기본 위치는 다음과 같습니다.
- Linux 및 macOS: $HOME/.pypirc
- Windows: %USERPROFILE%\.pypirc
```
[distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
```
다음 값을 바꿉니다.
- PYTHON-REPO-ID는 Twine과 같은 도구로 참조할 수 있는 저장소 ID입니다.
- PROJECT는 프로젝트 ID입니다. 이 플래그를 생략하면 현재 프로젝트 또는 기본 프로젝트가 사용됩니다.
- REPOSITORY는 저장소 ID입니다. 기본 Artifact Registry 저장소를 구성한 경우 이 플래그가 명령어에서 생략되었을 때 사용됩니다.
- LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
pip 구성 파일에 저장소를 추가합니다. 파일 위치는 사용자별 파일을 업데이트할지 아니면 사용 중인 가상 환경에 해당하는 파일을 업데이트할지에 따라 달라집니다.

운영체제 사용자와 연결된 파일의 경우:
- Unix: $HOME/.config/pip/pip.conf 또는 $HOME/.pip/pip.conf
- macOS: /Library/Application Support/pip/pip.conf 또는 $HOME/.config/pip/pip.conf
- Windows: %APPDATA%\pip\pip.ini 또는 %USERPROFILE%\pip\pip.ini
가상 환경의 경우:
- Unix 및 macOS: $VIRTUAL_ENV/pip.conf
- Windows: %VIRTUAL_ENV%\pip.ini
저장소만 검색하도록 pip를 구성하려면 index-url 설정을 사용하고 extra-index-url 설정으로 구성된 다른 패키지 색인이 없는지 확인합니다.
```
[global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
```
저장소 경로 끝에 있는 /simple/ 문자열은 저장소에서 Python Simple Repository API를 구현함을 나타냅니다.

이제 Python 환경이 Artifact Registry로 인증하도록 구성되었습니다.

사용자 인증 정보를 사용한 키링 인증

키링을 설정한 후에 gcloud CLI에서 사용자 인증 정보로 키링을 사용할 수 있습니다. Python 패키지 저장소에 연결하기 전에 Google Cloud CLI에 로그인합니다.

다음 명령어를 실행합니다.

gcloud auth login

서비스 계정 사용자 인증 정보를 사용한 키링 인증

키링을 설정한 후에 인증을 위한 서비스 계정을 설정할 수 있습니다.

서비스 계정을 만들거나 자동화에 사용할 기존 서비스 계정을 선택합니다.
저장소 액세스 권한을 부여하기 위해 서비스 계정에 적절한 Artifact Registry 역할을 부여합니다.
다음 옵션 중 하나를 사용하여 서비스 계정으로 인증합니다.
- 애플리케이션 기본 사용자 인증 정보(권장)
  
  저장소와 연결할 때 Artifact Registry 사용자 인증 정보 도우미가 키를 가져올 수 있도록 서비스 계정 키 파일 위치를 변수 GOOGLE_APPLICATION_CREDENTIALS에 할당합니다.
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
- gcloud CLI 사용자 인증 정보
  
  저장소에 연결하려면 먼저 서비스 계정으로 로그인하세요. Artifact Registry는 gcloud CLI에서 사용자 인증 정보보다 VM 서비스 계정 사용자 인증 정보를 먼저 찾으므로 Compute Engine VM에서 저장소에 연결하는 경우 이 옵션을 사용하지 마세요.
```
gcloud auth activate-service-account --key-file=KEY-FILE
```
KEY-FILE을 서비스 계정 키 파일의 경로로 바꿉니다.

서비스 계정 키로 인증

사용자 이름과 비밀번호를 사용한 인증이 필요한 경우 이 방법을 사용합니다.

서비스 계정 키는 장기 사용자 인증 정보입니다. 다음 가이드라인을 사용하여 저장소에 대한 액세스를 제한합니다.

저장소와 상호작용할 수 있도록 전용 서비스 계정을 사용하는 것이 좋습니다.
서비스 계정에 필요한 최소한의 Artifact Registry 역할을 부여합니다. 예를 들어 아티팩트만 다운로드하는 서비스 계정에 Artifact Registry 리더를 할당합니다.
조직의 그룹에 특정 저장소에 대한 여러 액세스 수준이 필요한 경우 프로젝트 수준이 아닌 저장소 수준에서 액세스 권한을 부여합니다.
사용자 인증 정보 관리 권장사항을 따릅니다.

인증을 구성하려면 다음 안내를 따르세요.

애플리케이션 대신 작동하도록 서비스 계정을 만들거나 자동화에 사용할 기존 서비스 계정을 선택합니다.

Artifact Registry로 인증을 설정하려면 서비스 계정 키 파일의 위치가 필요합니다. 기존 계정의 경우 서비스 계정 페이지에서 키를 보고 새 키를 만들 수 있습니다.

서비스 계정 페이지로 이동

참고: 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 가능한 한 서비스 계정 키보다 안전한 대안을 선택해야 합니다. 서비스 계정 키로 인증해야 하는 경우 비공개 키와 서비스 계정 키 관리 권장사항에 설명된 기타 작업을 보호해야 합니다. 서비스 계정 키를 만들 수 없는 경우 서비스 계정 키 생성이 조직에 중지될 수 있습니다. 자세한 내용은 보안 기반 조직 리소스 관리를 참조하세요.
저장소 액세스 권한을 부여하기 위해 서비스 계정에 적절한 Artifact Registry 역할을 부여합니다.
다음 명령어를 실행하여 Python 프로젝트에 추가할 저장소 구성을 출력합니다.
```
gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE
```
다음 값을 바꿉니다.
- PROJECT는 프로젝트 ID입니다. 이 플래그를 생략하면 현재 프로젝트 또는 기본 프로젝트가 사용됩니다.
- REPOSITORY는 저장소 ID입니다. 기본 Artifact Registry 저장소를 구성한 경우 이 플래그가 명령어에서 생략되었을 때 사용됩니다.
- LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
- KEY-FILE은 서비스 계정 JSON 키 파일의 경로입니다.
.pypirc 파일에 다음 설정을 추가합니다. 사용자별 pip 구성 파일의 기본 위치는 다음과 같습니다.
- Linux 및 macOS: $HOME/.pypirc
- Windows: %USERPROFILE%\.pypirc
```
[distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
username: _json_key_base64
password: KEY
```
다음 값을 바꿉니다.
- PYTHON-REPO-ID는 Twine과 같은 도구로 참조할 수 있는 저장소 ID입니다.
- PROJECT는 프로젝트 ID입니다. 이 플래그를 생략하면 현재 프로젝트 또는 기본 프로젝트가 사용됩니다.
- REPOSITORY는 저장소 ID입니다. 기본 Artifact Registry 저장소를 구성한 경우 이 플래그가 명령어에서 생략되었을 때 사용됩니다.
- LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
- KEY는 서비스 계정 키 파일에 있는 base64로 인코딩된 키입니다.
저장소를 pip 구성 파일에 추가합니다. pip 구성 파일 위치는 사용자별 파일 또는 사용 중인 가상 환경과 관련된 파일을 업데이트할지 여부에 따라 다릅니다.

운영체제 사용자와 연결된 파일의 경우 다음 명령어를 실행합니다.
- Unix: $HOME/.config/pip/pip.conf 또는 $HOME/.pip/pip.conf
- macOS: /Library/Application Support/pip/pip.conf 또는 $HOME/.config/pip/pip.conf
- Windows: %APPDATA%\pip\pip.ini 또는 %USERPROFILE%\pip\pip.ini
가상 환경의 경우:
- Unix 및 macOS: $VIRTUAL_ENV/pip.conf
- Windows: %VIRTUAL_ENV%\pip.ini
다음 줄을 pip 구성 파일에 추가합니다.
```
[global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
```
- KEY는 서비스 계정 키 파일의 비공개 키입니다.
- 저장소 경로 끝에 있는 /simple/ 문자열은 저장소에서 Python Simple Repository API를 구현함을 나타냅니다.