Mengonfigurasi autentikasi ke Artifact Registry untuk repositori paket Python

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

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

Artifact Registry mendukung metode autentikasi berikut untuk repositori paket Python:

  • Token akses: Gunakan token akses dalam otomatisasi, pipeline CI/CD, build container, atau lingkungan tempat penginstalan library key ring tidak didukung.
  • Library key ring Python (Direkomendasikan untuk pengembangan lokal): Gunakan opsi ini di workstation developer untuk menangani penggantian kredensial secara otomatis.
  • Autentikasi sandi: Gunakan opsi ini saat aplikasi tidak mendukung Kredensial Default Aplikasi, tetapi mendukung autentikasi dengan nama pengguna dan sandi.

Sebelum memulai

  1. Jika repositori target tidak ada, buat repositori paket Python baru.
  2. Pastikan Python 3 telah diinstal. Untuk mengetahui petunjuk penginstalan, lihat Google Cloud tutorial untuk menyiapkan Python.
  3. Pastikan akun pengguna atau akun layanan yang Anda gunakan memiliki izin yang diperlukan untuk mengakses repositori.

  4. Instal Google Cloud CLI. Setelah penginstalan, inisialisasi Google Cloud CLI dengan menjalankan perintah berikut: 

    gcloud init

    Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  5. (Opsional) Konfigurasi default untuk perintah gcloud CLI.

Membuat token untuk autentikasi

Untuk mengautentikasi paket Anda di Artifact Registry, Anda harus membuat token autentikasi terlebih dahulu. Kemudian, Anda dapat menggunakan token ini saat membuat permintaan dari paket Anda ke Artifact Registry.

Anda dapat membuat token akses oauth2 menggunakan Google Cloud atau token oauth2l di luar Google Cloud.

Token akses berlaku selama 60 menit. Buat token akses sesaat sebelum menjalankan perintah yang berinteraksi dengan repositori. Jika masa berlaku token akses Anda telah berakhir, Anda harus membuat token akses baru.

Membuat token menggunakan gcloud

Untuk membuat token akses oauth2 menggunakan Google Cloud, jalankan perintah berikut:

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

Sekarang Anda dapat mereferensikan ACCESS_TOKEN saat membuat permintaan dari paket Python ke Artifact Registry.

Membuat token tanpa menggunakan gcloud

Untuk membuat token akses hanya menggunakan oauth2l CLI, lakukan hal berikut:

  1. Instal oauth2l versi terbaru dengan menjalankan perintah berikut:

    go install github.com/google/oauth2l@latest

  2. Jalankan perintah berikut:

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

    Google Cloud membuat token hash SHA256 dan menyimpannya dalam variabel ACCESS_TOKEN. Anda kini dapat mereferensikan ACCESS_TOKEN saat membuat permintaan dari paket Python ke Artifact Registry.

Mengautentikasi dengan pip

Setelah mengekspor ACCESS_TOKEN, Anda dapat meneruskannya ke pip untuk menginstal paket:

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

Mengautentikasi dengan key ring

Library key ring Python menyediakan cara bagi aplikasi untuk mengakses backend key ring, yang berarti penyimpanan kredensial pihak ketiga dan sistem operasi. Artifact Registry menyediakan backend keyring keyrings.google-artifactregistry-auth untuk menangani autentikasi dengan repositori Artifact Registry.

Petunjuk di bagian ini menjelaskan cara mengonfigurasi pip sebagai satu-satunya indeks paket yang ditelusuri pip untuk menemukan 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 dalam file konfigurasi pip. Alat pip tidak menelusuri indeks paket dalam urutan tertentu, sehingga konsumen Anda mungkin secara keliru 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 memitigasi risiko kebingungan dependensi ini.

Urutan penelusuran kredensial

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

  1. Kredensial Default Aplikasi (ADC), strategi yang mencari kredensial dalam 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 Run Functions.

  2. 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 menjadi eksplisit, sehingga memudahkan pemecahan masalah. Jika Anda tidak menggunakan variabel, pastikan semua 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 Anda berencana mengupload dari lingkungan ini menggunakan akun layanan default, Anda harus mengubah izin.

Menyiapkan key ring

Untuk menyiapkan autentikasi dengan backend ring kunci Artifact Registry:

  1. Instal library key ring.

    pip install keyring

  2. Instal backend Artifact Registry.

    pip install keyrings.google-artifactregistry-auth

  3. Mencantumkan backend untuk mengonfirmasi penginstalan.

    keyring --list-backends

    Daftar harus mencakup

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

  4. 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 default akan digunakan.
    • REPOSITORY adalah ID repositori. Jika Anda mengonfigurasi repositori Artifact Registry default, repositori tersebut akan digunakan jika flag ini tidak disertakan dalam perintah.
    • LOCATION adalah lokasi regional atau multi-regional untuk repositori.

  5. 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 rujuk dengan alat seperti Twine.
    • PROJECT adalah project ID. Jika flag ini dihilangkan, project saat ini atau default akan digunakan.
    • REPOSITORY adalah ID repositori. Jika Anda mengonfigurasi repositori Artifact Registry default, repositori tersebut akan digunakan jika flag ini tidak disertakan dalam perintah.
    • LOCATION adalah lokasi regional atau multi-regional untuk repositori.

  6. Tambahkan repositori Anda ke file konfigurasi pip. Lokasi file bergantung pada apakah Anda ingin memperbarui 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 mengimplementasikan Python Simple Repository API.

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

autentikasi key ring dengan kredensial pengguna

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

Jalankan perintah berikut:

gcloud auth login

autentikasi key ring dengan kredensial akun layanan

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

  1. Buat akun layanan, atau pilih akun layanan yang sudah ada yang Anda gunakan untuk otomatisasi.
  2. Berikan peran Artifact Registry tertentu ke akun layanan untuk memberikan akses repositori.

  3. 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 sehingga helper kredensial Artifact Registry dapat memperoleh kunci Anda saat terhubung dengan repositori.

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • Kredensial gcloud CLI

      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.

Mengonfigurasi autentikasi sandi dengan kunci akun layanan

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

Kunci akun layanan adalah kredensial yang dapat digunakan untuk jangka 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 peran 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 tingkat project.
  • Ikuti praktik terbaik untuk mengelola kredensial.

Untuk mengonfigurasi autentikasi:

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

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

    Buka halaman Service Accounts

  2. Berikan peran Artifact Registry yang sesuai ke akun layanan untuk memberikan akses repositori.

  3. 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 default akan digunakan.
    • REPOSITORY adalah ID repositori. Jika Anda mengonfigurasi repositori Artifact Registry default, repositori tersebut akan digunakan jika flag ini tidak disertakan dalam perintah.
    • LOCATION adalah lokasi regional atau multi-regional untuk repositori.
    • KEY-FILE adalah jalur ke file kunci JSON akun layanan.

  4. Tambahkan setelan berikut ke file .pypirc. Lokasi default 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 rujuk dengan alat seperti Twine.
    • PROJECT adalah project ID. Jika flag ini dihilangkan, project saat ini atau default akan digunakan.
    • REPOSITORY adalah ID repositori. Jika Anda mengonfigurasi repositori Artifact Registry default, repositori tersebut akan digunakan jika flag ini tidak disertakan dalam perintah.
    • LOCATION adalah lokasi regional atau multi-regional untuk repositori.
    • KEY adalah kunci berenkode base64 di file kunci akun layanan Anda.

  5. Tambahkan repositori Anda ke file konfigurasi pip. Lokasi file konfigurasi pip bergantung pada apakah Anda ingin memperbarui 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

    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 dalam file kunci akun layanan Anda.
    • String /simple/ di akhir jalur repositori menunjukkan bahwa repositori mengimplementasikan Python Simple Repository API.

Langkah berikutnya