Mengonfigurasi autentikasi ke Artifact Registry untuk repositori paket Python

Halaman ini menjelaskan cara mengonfigurasi autentikasi dengan repositori paket Python Artifact Registry.

Anda harus melakukan autentikasi ke Artifact Registry saat menggunakan aplikasi pihak ketiga untuk terhubung ke repositori.

Anda tidak perlu mengonfigurasi autentikasi untuk lingkungan runtime Cloud Build atau Google Cloud seperti Google Kubernetes Engine dan Cloud Run, tetapi Anda harus memastikan bahwa izin yang diperlukan telah dikonfigurasi.

Sebelum memulai

Jika repositori target tidak ada, buat repositori paket Python baru.
Pastikan Python 3 telah diinstal. Untuk mengetahui petunjuk penginstalan, lihat tutorial Google Cloud untuk menyiapkan Python.
Pastikan akun pengguna atau akun layanan yang Anda gunakan memiliki izin yang diperlukan untuk mengakses repositori.
Instal Google Cloud CLI, lalu initialize dengan menjalankan perintah berikut:
```
gcloud init
```
Catatan: Jika Anda telah menginstal gcloud CLI sebelumnya, pastikan Anda memiliki versi baru dengan menjalankan gcloud components update.
(Opsional) Konfigurasikan default untuk perintah gcloud CLI.

Ringkasan

Artifact Registry mendukung metode autentikasi berikut.

Library keyring Python (Direkomendasikan): Artifact Registry menyediakan backend keyring untuk menyimpan kredensial guna terhubung ke repositori Artifact Registry.
Autentikasi sandi: Gunakan opsi ini jika Anda tidak dapat menggunakan keyring dan memerlukan opsi yang mendukung autentikasi sandi dasar.

Petunjuk dalam dokumentasi ini menjelaskan cara mengonfigurasi pip sebagai satu-satunya indeks paket yang ditelusuri pip untuk paket. Sebaiknya gunakan repositori virtual untuk menelusuri paket di seluruh paket pribadi Anda di Artifact Registry dan paket publik dari PyPI, bukan mengonfigurasi beberapa indeks paket di file konfigurasi pip. Alat pip tidak menelusuri indeks paket dalam urutan tertentu, sehingga konsumen Anda mungkin salah mendownload atau menginstal paket publik dengan nama yang sama dengan salah satu paket pribadi Anda. Repositori virtual memungkinkan Anda mengonfigurasi prioritas untuk sumber upstream guna mengurangi risiko kebingungan dependensi ini.

Mengautentikasi dengan keyring

Library keyring Python memberi aplikasi cara untuk mengakses backend keyring, yang berarti sistem operasi dan penyimpanan kredensial pihak ketiga.

Artifact Registry menyediakan keyrings.google-artifactregistry-auth backend keyring untuk menangani autentikasi dengan repositori Artifact Registry.

Urutan penelusuran kredensial

Saat Anda menggunakan backend keyring Artifact Registry, kredensial Anda tidak akan disimpan di project Python. Sebagai gantinya, Artifact Registry akan menelusuri kredensial dengan urutan berikut:

Kredensial Default Aplikasi (ADC), strategi yang mencari kredensial dengan urutan berikut:
1. Kredensial yang ditentukan dalam variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.
2. Kredensial yang disediakan oleh akun layanan default untuk Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine, atau Cloud Functions.
Kredensial yang diberikan oleh Google Cloud CLI, termasuk kredensial pengguna dari perintah gcloud auth application-default login.

Variabel GOOGLE_APPLICATION_CREDENTIALS membuat akun untuk autentikasi eksplisit, sehingga mempermudah pemecahan masalah. Jika Anda tidak menggunakan variabel tersebut, pastikan setiap akun yang mungkin digunakan ADC memiliki izin yang diperlukan. Misalnya, akun layanan default untuk VM Compute Engine, node Google Kubernetes Engine, dan revisi Cloud Run memiliki akses hanya baca ke repositori. Jika ingin mengupload dari lingkungan ini menggunakan akun layanan default, Anda harus mengubah izinnya.

Menyiapkan keyring

Untuk menyiapkan autentikasi dengan backend keyring Artifact Registry:

Instal library keyring.
```
pip install keyring
```

Instal backend Artifact Registry.

pip install keyrings.google-artifactregistry-auth

Menampilkan daftar backend untuk mengonfirmasi penginstalan.
```
keyring --list-backends
```
Daftar ini harus mencakup
- ChainerBackend(priority:10)
- GooglePythonAuth(priority: 9)
Jalankan perintah berikut untuk mencetak konfigurasi repositori yang akan ditambahkan ke project Python Anda.
```
gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION
```
Ganti nilai berikut:
- PROJECT adalah project ID. Jika flag ini dihilangkan, project saat ini atau project default akan digunakan.
- REPOSITORY adalah ID repositori. Jika Anda mengonfigurasi repositori Artifact Registry default, repositori tersebut akan digunakan saat flag ini dihilangkan dari perintah.
- LOCATION adalah lokasi regional atau multi-regional untuk repositori.
Tambahkan setelan berikut ke file .pypirc. Lokasi defaultnya adalah:
- Linux dan macOS: $HOME/.pypirc
- Windows: %USERPROFILE%\.pypirc
```
[distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
```
Ganti nilai berikut:
- PYTHON-REPO-ID adalah ID untuk repositori yang dapat Anda referensikan dengan alat seperti Twine.
- PROJECT adalah project ID. Jika flag ini dihilangkan, project saat ini atau project default akan digunakan.
- REPOSITORY adalah ID repositori. Jika Anda mengonfigurasi repositori Artifact Registry default, repositori tersebut akan digunakan saat flag ini dihilangkan dari perintah.
- LOCATION adalah lokasi regional atau multi-regional untuk repositori.
Tambahkan repositori Anda ke file konfigurasi pip. Lokasi file bergantung pada apakah Anda ingin mengupdate file per pengguna atau file khusus untuk lingkungan virtual yang Anda gunakan.

Untuk file yang terkait dengan pengguna sistem operasi Anda:
- Unix: $HOME/.config/pip/pip.conf atau $HOME/.pip/pip.conf
- macOS: /Library/Application Support/pip/pip.conf atau $HOME/.config/pip/pip.conf
- Windows: %APPDATA%\pip\pip.ini atau %USERPROFILE%\pip\pip.ini
Untuk lingkungan virtual:
- Unix dan macOS: $VIRTUAL_ENV/pip.conf
- Windows: %VIRTUAL_ENV%\pip.ini
Untuk mengonfigurasi pip agar hanya menelusuri repositori Anda, gunakan setelan index-url dan pastikan tidak ada indeks paket lain yang dikonfigurasi dengan setelan extra-index-url.
```
[global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
```
String /simple/ di akhir jalur repositori menunjukkan bahwa repositori menerapkan Python Simple Repository API.

Lingkungan Python Anda kini telah dikonfigurasi untuk melakukan autentikasi dengan Artifact Registry.

Autentikasi keyring dengan kredensial pengguna

Setelah menyiapkan keyring, Anda dapat menggunakan keyring dengan kredensial pengguna di gcloud CLI. Login ke Google Cloud CLI sebelum terhubung ke repositori paket Python.

Jalankan perintah berikut:

gcloud auth login

Autentikasi keyring dengan kredensial akun layanan

Setelah menyiapkan keyring, Anda dapat menyiapkan akun layanan untuk autentikasi.

Buat akun layanan, atau pilih akun layanan yang ada yang Anda gunakan untuk otomatisasi.
Berikan peran Artifact Registry spesifik ke akun layanan untuk memberikan akses repositori.
Gunakan salah satu opsi berikut untuk melakukan autentikasi dengan akun layanan Anda:
- Kredensial Default Aplikasi (Direkomendasikan)
  
  Tetapkan lokasi file kunci akun layanan ke variabel GOOGLE_APPLICATION_CREDENTIALS agar helper kredensial Artifact Registry dapat memperoleh kunci Anda saat terhubung dengan repositori.
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
- Kredensial CLI gcloud
  
  Sebelum terhubung ke repositori, login sebagai akun layanan. Hindari opsi ini jika Anda terhubung ke repositori dari VM Compute Engine karena Artifact Registry menemukan kredensial akun layanan VM sebelum kredensial di gcloud CLI.
```
gcloud auth activate-service-account --key-file=KEY-FILE
```
Ganti KEY-FILE dengan jalur ke file kunci akun layanan.

Mengautentikasi dengan kunci akun layanan

Gunakan pendekatan ini saat Anda memerlukan autentikasi dengan nama pengguna dan sandi.

Kunci akun layanan adalah kredensial yang berlaku dalam waktu lama. Gunakan panduan berikut untuk membatasi akses ke repositori Anda:

Pertimbangkan untuk menggunakan akun layanan khusus untuk berinteraksi dengan repositori.
Berikan peran Artifact Registry minimum yang diperlukan oleh akun layanan. Misalnya, tetapkan Pembaca Artifact Registry ke akun layanan yang hanya mendownload artefak.
Jika grup di organisasi Anda memerlukan tingkat akses yang berbeda ke repositori tertentu, berikan akses di tingkat repositori, bukan level project.
Ikuti praktik terbaik untuk mengelola kredensial.

Untuk mengonfigurasi autentikasi:

Buat akun layanan untuk bertindak atas nama aplikasi Anda, atau pilih akun layanan yang ada yang Anda gunakan untuk otomatisasi.

Anda memerlukan lokasi file kunci akun layanan untuk menyiapkan autentikasi dengan Artifact Registry. Untuk akun yang ada, Anda dapat melihat kunci dan membuat kunci baru di halaman Akun Layanan.

Buka halaman Service Accounts

Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus melakukan autentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan dalam Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.
Berikan peran Artifact Registry yang sesuai ke akun layanan untuk memberikan akses repositori.
Jalankan perintah berikut untuk mencetak konfigurasi repositori yang akan ditambahkan ke project Python Anda.
```
gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE
```
Ganti nilai berikut:
- PROJECT adalah project ID. Jika flag ini dihilangkan, project saat ini atau project default akan digunakan.
- REPOSITORY adalah ID repositori. Jika Anda mengonfigurasi repositori Artifact Registry default, repositori tersebut akan digunakan saat flag ini dihilangkan dari perintah.
- LOCATION adalah lokasi regional atau multi-regional untuk repositori.
- KEY-FILE adalah jalur ke file kunci JSON akun layanan.
Tambahkan setelan berikut ke file .pypirc. Lokasi default-nya adalah untuk file konfigurasi pip per pengguna adalah:
- Linux dan 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
```
Ganti nilai berikut:
- PYTHON-REPO-ID adalah ID untuk repositori yang dapat Anda referensikan dengan alat seperti Twine.
- PROJECT adalah project ID. Jika flag ini dihilangkan, project saat ini atau project default akan digunakan.
- REPOSITORY adalah ID repositori. Jika Anda mengonfigurasi repositori Artifact Registry default, repositori tersebut akan digunakan saat flag ini dihilangkan dari perintah.
- LOCATION adalah lokasi regional atau multi-regional untuk repositori.
- KEY adalah kunci yang dienkode base64 dalam file kunci akun layanan Anda.
Tambahkan repositori Anda ke file konfigurasi pip. Lokasi file konfigurasi pip bergantung pada apakah Anda ingin mengupdate file per pengguna atau file khusus ke lingkungan virtual yang Anda gunakan.

Untuk file yang terkait dengan pengguna sistem operasi Anda:
- Unix: $HOME/.config/pip/pip.conf atau $HOME/.pip/pip.conf
- macOS: /Library/Application Support/pip/pip.conf atau $HOME/.config/pip/pip.conf
- Windows: %APPDATA%\pip\pip.ini atau %USERPROFILE%\pip\pip.ini
Untuk lingkungan virtual:
- Unix dan macOS: $VIRTUAL_ENV/pip.conf
- Windows: %VIRTUAL_ENV%\pip.ini
Tambahkan baris berikut ke file konfigurasi pip:
```
[global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
```
- KEY kunci pribadi di file kunci akun layanan Anda.
- String /simple/ di akhir jalur repositori menunjukkan bahwa repositori menerapkan Python Simple Repository API.