Configurare l'autenticazione in Artifact Registry per i repository di pacchetti Python

Questa pagina descrive come configurare l'autenticazione con un repository di pacchetti Python di Artifact Registry.

Devi autenticarti in Artifact Registry quando utilizzi un'applicazione di terze parti per connetterti a un repository.

Non è necessario configurare l'autenticazione per Cloud Build o Google Cloud gli ambienti di runtime come Google Kubernetes Engine e Cloud Run, ma devi verificare che le autorizzazioni richieste siano configurate.

Prima di iniziare

  1. Se il repository di destinazione non esiste, crea un nuovo repository di pacchetti Python.
  2. Verifica che Python 3 sia installato. Per le istruzioni di installazione, consulta il Google Cloud tutorial per la configurazione di Python.
  3. Verifica che l'account utente o l'account di servizio che utilizzi disponga delle autorizzazioni necessarie per accedere al repository.

  4. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init
  5. (Facoltativo) Configura i valori predefiniti per i comandi gcloud CLI.

Panoramica

Artifact Registry supporta i seguenti metodi di autenticazione.

Libreria keyring di Python (consigliata)
Artifact Registry fornisce un backend per i portachiavi per archiviare le credenziali per la connessione ai repository Artifact Registry.
Autenticazione con password
Utilizza questa opzione quando non puoi utilizzare il portachiavi e hai bisogno di un'opzione che supporti l'autenticazione di base con password.

Le istruzioni riportate in questa documentazione descrivono la configurazione di pip come unico indice dei pacchetti in cui pip cerca i pacchetti. Ti consigliamo di utilizzare repository virtuali per cercare i pacchetti tra i tuoi pacchetti privati in Artifact Registry e i pacchetti pubblici di PyPI anziché configurare più indici dei pacchetti nel file di configurazione di pip. Lo strumento pip non cerca gli indici dei pacchetti in un ordine particolare, pertanto i tuoi consumatori potrebbero scaricare o installare per errore un pacchetto pubblico con lo stesso nome di uno dei tuoi pacchetti privati. I repository virtuali ti consentono di configurare le priorità per le origini upstream per ridurre questo rischio di confusione delle dipendenze.

Autenticazione con il portachiavi

La libreria keyring di Python offre alle applicazioni un modo per accedere ai backend keyring, ovvero ai depositi delle credenziali del sistema operativo e di terze parti.

Artifact Registry fornisce il backend della chiave keyrings.google-artifactregistry-auth per gestire l'autenticazione con i repository Artifact Registry.

Ordine di ricerca delle credenziali

Quando utilizzi il backend della chiave dell'Artifact Registry, le tue credenziali non vengono memorizzate nel progetto Python. Artifact Registry cerca invece le credenziali nel seguente ordine:

  1. Credenziali predefinite dell'applicazione (ADC), una strategia che cerca le credenziali nel seguente ordine:

    1. Credenziali definite nella variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

    2. Credenziali fornite dall'account di servizio predefinito per Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o Cloud Functions.

  2. Le credenziali fornite da Google Cloud CLI, incluse le credenziali utente del comando gcloud auth application-default login.

La variabile GOOGLE_APPLICATION_CREDENTIALS rende esplicito l'account per l'autenticazione, semplificando la risoluzione dei problemi. Se non utilizzi la variabile, verifica che gli account che potrebbero essere utilizzati dall'ADC dispongano delle autorizzazioni richieste. Ad esempio, l'account di servizio predefinito per le VM Compute Engine, i nodi Google Kubernetes Engine e le revisioni Cloud Run ha accesso in sola lettura ai repository. Se intendi eseguire il caricamento da questi ambienti utilizzando l'account di servizio predefinito, devi modificare le autorizzazioni.

Configurazione del portachiavi

Per configurare l'autenticazione con il backend della chiave dell'Artifact Registry:

  1. Installa la libreria keyring.

    pip install keyring

  2. Installa il backend di Artifact Registry.

    pip install keyrings.google-artifactregistry-auth

  3. Elenca i backend per confermare l'installazione.

    keyring --list-backends

    L'elenco deve includere

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

  4. Esegui il comando seguente per stampare la configurazione del repository da aggiungere al progetto Python.

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

    Sostituisci i seguenti valori:

    • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
    • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
    • LOCATION è la posizione regionale o multiregionale del repository.

  5. Aggiungi le seguenti impostazioni al file .pypirc. La posizione predefinita è:

    • Linux e macOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/

    Sostituisci i seguenti valori:

    • PYTHON-REPO-ID è un ID del repository a cui puoi fare riferimento con strumenti come Twine.
    • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
    • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
    • LOCATION è la posizione regionale o multiregionale del repository.

  6. Aggiungi il tuo repository al file di configurazione di pip. La posizione del file dipende dal fatto che tu voglia aggiornare il file per utente o il file specifico per un ambiente virtuale che stai utilizzando.

    Per il file associato all'utente del sistema operativo:

    • Unix: $HOME/.config/pip/pip.conf o $HOME/.pip/pip.conf
    • macOS: /Library/Application Support/pip/pip.conf o $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini o %USERPROFILE%\pip\pip.ini

    Per gli ambienti virtuali:

    • Unix e macOS: $VIRTUAL_ENV/pip.conf
    • Windows: %VIRTUAL_ENV%\pip.ini

    Per configurare pip in modo che esegua la ricerca solo nel tuo repository, utilizza l'impostazione index-url e assicurati che non siano configurati altri indici dei pacchetti con l'impostazione extra-index-url.

    [global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

    La stringa /simple/ alla fine del percorso del repository indica che il repository implementa l'API Python Simple Repository.

L'ambiente Python è ora configurato per l'autenticazione con Artifact Registry.

Autenticazione del portachiavi con le credenziali utente

Dopo aver configurato il portachiavi, puoi utilizzarlo con le tue credenziali utente nella CLI gcloud. Accedi a Google Cloud CLI prima di collegarti a un repository di pacchetti Python.

Esegui questo comando:

gcloud auth login

Autenticazione del portachiavi con le credenziali dell'account di servizio

Dopo aver configurato il portachiavi, puoi configurare un account di servizio per l'autenticazione.

  1. Crea un account di servizio o scegli un account di servizio esistente che utilizzi per l'automazione.
  2. Concedi il ruolo Artifact Registry specifico all'account di servizio per fornire l'accesso al repository.

  3. Utilizza una delle seguenti opzioni per autenticarti con il tuo account di servizio:

    • Credenziali predefinite dell'applicazione (opzione consigliata)

      Assegna il percorso del file della chiave dell'account di servizio alla variabile GOOGLE_APPLICATION_CREDENTIALS in modo che l'helper per le credenziali di Artifact Registry possa ottenere la chiave quando si connette ai repository.

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • Credenziali dell'interfaccia a riga di comando gcloud

      Prima di connetterti a un repository, accedi come account di servizio. Evita questa opzione se ti connetti ai repository dalle VM Compute Engine poiché Artifact Registry trova le credenziali del service account della VM prima delle credenziali nella CLI gcloud.

      gcloud auth activate-service-account --key-file=KEY-FILE

    Sostituisci KEY-FILE con il percorso del file della chiave dell'account di servizio.

Autenticazione con una chiave dell'account di servizio

Utilizza questo approccio quando è richiesta l'autenticazione con nome utente e password.

Le chiavi dell'account di servizio sono credenziali a lungo termine. Utilizza le seguenti linee guida per limitare l'accesso ai tuoi repository:

  • Valuta la possibilità di utilizzare un account di servizio dedicato per interagire con i repository.
  • Concedi il ruolo Artifact Registry minimo richiesto dall'account di servizio. Ad esempio, assegna il ruolo Artifact Registry Reader a un account di servizio che scarica solo gli elementi.
  • Se i gruppi della tua organizzazione richiedono livelli di accesso diversi a repository specifici, concedi l'accesso a livello di repository anziché a livello di progetto.
  • Segui le best practice per la gestione delle credenziali.

Per configurare l'autenticazione:

  1. Crea un account di servizio per agire per conto della tua applicazione o scegli un account di servizio esistente che utilizzi per l'automazione.

    Per configurare l'autenticazione con Artifact Registry, devi conoscere la posizione del file della chiave dell'account di servizio. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Account di servizio.

    Vai alla pagina Account di servizio

  2. Concedi il ruolo Artifact Registry appropriato all'account di servizio per fornire l'accesso al repository.

  3. Esegui il comando seguente per stampare la configurazione del repository da aggiungere al progetto Python.

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE

    Sostituisci i seguenti valori:

    • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
    • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
    • LOCATION è la posizione regionale o multiregionale del repository.
    • KEY-FILE è il percorso del file della chiave JSON dell'account di servizio.

  4. Aggiungi le seguenti impostazioni al file .pypirc. La posizione predefinita per il file di configurazione pip per utente è:

    • Linux e 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

    Sostituisci i seguenti valori:

    • PYTHON-REPO-ID è un ID del repository a cui puoi fare riferimento con strumenti come Twine.
    • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
    • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
    • LOCATION è la posizione regionale o multiregionale del repository.
    • KEY è la chiave codificata in base64 nel file della chiave dell'account di servizio.

  5. Aggiungi il tuo repository al file di configurazione di pip. La posizione del file di configurazione di pip dipende da se vuoi aggiornare il file per utente o il file specifico per un ambiente virtuale che stai utilizzando.

    Per il file associato all'utente del sistema operativo:

    • Unix: $HOME/.config/pip/pip.conf o $HOME/.pip/pip.conf
    • macOS: /Library/Application Support/pip/pip.conf o $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini o %USERPROFILE%\pip\pip.ini

    Per gli ambienti virtuali:

    • Unix e macOS: $VIRTUAL_ENV/pip.conf
    • Windows: %VIRTUAL_ENV%\pip.ini

    Aggiungi la seguente riga al file di configurazione di pip:

    [global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
    • KEY la chiave privata nel file della chiave dell'account di servizio.
    • La stringa /simple/ alla fine del percorso del repository indica che il repository implementa l'API Python Simple Repository.

Passaggi successivi