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

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

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

Artifact Registry는 Python 패키지 저장소에 대해 다음과 같은 인증 방법을 지원합니다.

• 액세스 토큰: 자동화, CI/CD 파이프라인, 컨테이너 빌드 또는 키링 라이브러리 설치가 지원되지 않는 환경에서 액세스 토큰을 사용합니다.
• Python 키링 라이브러리 (로컬 개발에 권장): 개발자 워크스테이션에서 이 옵션을 사용하여 사용자 인증 정보 새로고침을 자동으로 처리합니다.
• 비밀번호 인증: 애플리케이션에서 애플리케이션 기본 사용자 인증 정보를 지원하지 않지만 사용자 이름과 비밀번호를 사용한 인증을 지원하는 경우 이 옵션을 사용합니다.

시작하기 전에

1. 대상 저장소가 없으면 새 Python Package Repository를 만듭니다.
2. Python 3이 설치되어 있는지 확인합니다. 설치 안내는Google Cloud Python 설정 튜토리얼을 참조하세요.
3. 사용 중인 사용자 계정이나 서비스 계정에 저장소에 액세스하는 데 필요한 권한이 있는지 확인합니다.

4. Google Cloud CLI를 설치합니다. 설치 후 다음 명령어를 실행하여 Google Cloud CLI를 초기화합니다.

   gcloud init

   외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

5. (선택사항) cloud CLI 명령어의 기본값을 구성합니다.

인증용 토큰 생성

Artifact Registry에서 패키지를 인증하려면 먼저 인증 토큰을 생성해야 합니다. 그런 다음 패키지에서 Artifact Registry로 요청할 때 이 토큰을 사용할 수 있습니다.

Google Cloud 를 사용하여 oauth2 액세스 토큰을 생성하거나 Google Cloud외부에서 oauth2l 토큰을 생성할 수 있습니다.

액세스 토큰은 60분 동안 유효합니다. 저장소와 상호작용하는 명령어를 실행하기 직전에 액세스 토큰을 생성합니다. 액세스 토큰이 만료된 경우 새 액세스 토큰을 생성해야 합니다.

gcloud를 사용하여 토큰 생성

Google Cloud를 사용하여 oauth2 액세스 토큰을 생성하려면 다음 명령어를 실행합니다.

export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

이제 Python 패키지에서 Artifact Registry로 요청을 보낼 때 ACCESS_TOKEN를 참조할 수 있습니다.

gcloud를 사용하지 않고 토큰 생성

oauth2l CLI만 사용하여 액세스 토큰을 생성하려면 다음 단계를 따르세요.

1. 다음 명령어를 실행하여 최신 버전의 oauth2l를 설치합니다.

   go install github.com/google/oauth2l@latest
   

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

   export ACCESS_TOKEN="oauth2l fetch --scope cloud-platform"
   

   Google Cloud 는 SHA256 해시 토큰을 생성하고 ACCESS_TOKEN 변수에 저장합니다. 이제 Python 패키지에서 Artifact Registry로 요청할 때 ACCESS_TOKEN를 참조할 수 있습니다.

pip로 인증

ACCESS_TOKEN를 내보낸 후 pip에 전달하여 패키지를 설치할 수 있습니다.

pip install PACKAGE --index-url https://$ACCESS_TOKEN@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

키링으로 인증

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

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

사용자 인증 정보 검색 순서

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

1. 애플리케이션 기본 사용자 인증 정보(ADC) - 다음 순서로 사용자 인증 정보를 찾는 전략

   1. GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 정의된 사용자 인증 정보

   2. Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine 또는 Cloud Run 함수의 기본 서비스 계정에서 제공하는 사용자 인증 정보

2. gcloud auth application-default login 명령어의 사용자 인증 정보를 포함한 Google Cloud CLI에서 제공하는 사용자 인증 정보

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

키링 설정

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

1. 키링 라이브러리를 설치합니다.

   pip install keyring
   

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

   pip install keyrings.google-artifactregistry-auth
   

3. 백엔드를 나열하여 설치를 확인합니다.

   keyring --list-backends
   

   이 목록에는 다음 항목이 포함됩니다.

   • ChainerBackend(priority:10)
   • GooglePythonAuth(priority: 9)

4. 다음 명령어를 실행하여 Python 프로젝트에 추가할 저장소 구성을 출력합니다.

   gcloud artifacts print-settings python --project=PROJECT \
       --repository=REPOSITORY \
       --location=LOCATION
   

   다음 값을 바꿉니다.

   • PROJECT는 프로젝트 ID입니다. 이 플래그를 생략하면 현재 프로젝트 또는 기본 프로젝트가 사용됩니다.
   • REPOSITORY는 저장소 ID입니다. 기본 Artifact Registry 저장소를 구성한 경우 이 플래그가 명령어에서 생략되었을 때 사용됩니다.
   • LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.

5. .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은 저장소의 리전 또는 멀티 리전 위치입니다.

6. 저장소를 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 Package Repository에 연결하기 전에 Google Cloud CLI에 로그인합니다.

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

gcloud auth login

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

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

1. 서비스 계정을 만들거나 자동화에 사용할 기존 서비스 계정을 선택합니다.
2. 저장소 액세스 권한을 부여하기 위해 서비스 계정에 적절한 Artifact Registry 역할을 부여합니다.

3. 다음 옵션 중 하나를 사용하여 서비스 계정으로 인증합니다.

   • 애플리케이션 기본 사용자 인증 정보(권장)

     저장소와 연결할 때 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 리더를 할당합니다.
• 조직의 그룹에 특정 저장소에 대한 여러 액세스 수준이 필요한 경우 프로젝트 수준이 아닌 저장소 수준에서 액세스 권한을 부여합니다.
• 사용자 인증 정보 관리 권장사항을 따릅니다.

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

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

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

   서비스 계정 페이지로 이동

2. 저장소 액세스 권한을 부여하기 위해 서비스 계정에 적절한 Artifact Registry 역할을 부여합니다.

3. 다음 명령어를 실행하여 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 키 파일의 경로입니다.

4. .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로 인코딩된 키입니다.

5. 저장소를 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를 구현함을 나타냅니다.

다음 단계

• 저장소에 대한 액세스 구성
• 저장소 관리 알아보기
• 패키지 관리 알아보기