Configura l'autenticazione su Artifact Registry per i repository di pacchetti Python

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

Quando utilizzi un'applicazione di terze parti per connetterti a un repository, devi eseguire l'autenticazione in Artifact Registry.

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

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 tutorial per la configurazione di Python di Google Cloud.
  3. Verifica che l'account utente o l'account di servizio che utilizzi disponga delle autorizzazioni necessarie per accedere al repository.

  4. Installa Google Cloud CLI, quindi initialize eseguendo questo comando: 

    gcloud init
  5. (Facoltativo) Configura i valori predefiniti per la gcloud CLI;interfaccia a riga di comando gcloud.

Panoramica

Artifact Registry supporta i seguenti metodi di autenticazione.

Libreria di keyring Python (consigliata)
Artifact Registry fornisce un backend del keyring per archiviare le credenziali per la connessione ai repository Artifact Registry.
Autenticazione password
Utilizza questa opzione quando non puoi usare il keyring e ti serve un'opzione che supporti l'autenticazione di base delle password.

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

Autenticazione con keyring

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

Artifact Registry fornisce il backend del keyring keyrings.google-artifactregistry-auth per gestire l'autenticazione con i repository di Artifact Registry.

Ordine di ricerca delle credenziali

Quando utilizzi il backend del keyring Artifact Registry, le tue credenziali non vengono archiviate 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. Credenziali fornite da Google Cloud CLI, incluse le credenziali utente del comando gcloud auth application-default login.

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

Configurazione del keyring

Per configurare l'autenticazione con il backend del keyring Artifact Registry:

  1. Installa la raccolta di keyring.

    pip install keyring

  2. Installare il backend 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 questo comando 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 attuale 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 località a livello di una o più regioni per il repository.

  5. Aggiungi le seguenti impostazioni al file .pypirc. La località 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 attuale 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 località a livello di una o più regioni per il repository.

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

    Per il file associato all'utente del tuo 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 cerchi solo nel repository, utilizza l'impostazione index-url e assicurati che non siano presenti altri indici di pacchetti configurati 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.

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

Autenticazione keyring con credenziali utente

Dopo aver configurato il keyring, puoi utilizzarlo con le tue credenziali utente nellgcloud CLI. Accedi a Google Cloud CLI prima di connetterti a un repository di pacchetti Python.

Esegui questo comando:

gcloud auth login

Autenticazione keyring con credenziali dell'account di servizio

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

  1. Crea un account di servizio o scegline uno 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 l'autenticazione con il tuo account di servizio:

    • Credenziali predefinite dell'applicazione (consigliato)

      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 tua chiave durante la connessione 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 di Compute Engine poiché Artifact Registry trova le credenziali dell'account di servizio VM prima delle credenziali nellgcloud CLI.

      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 richiedi l'autenticazione con nome utente e password.

Le chiavi dell'account di servizio sono credenziali di lunga durata. Segui queste linee guida per limitare l'accesso ai 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 Lettore Artifact Registry a un account di servizio che scarica solo artefatti.
  • 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 che agisca per conto della tua applicazione oppure scegli un account di servizio esistente che utilizzi per l'automazione.

    Avrai bisogno della posizione del file della chiave dell'account di servizio per configurare l'autenticazione con Artifact Registry. 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 all'account di servizio il ruolo Artifact Registry appropriato per fornire l'accesso al repository.

  3. Esegui questo comando 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 attuale 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 località a livello di una o più regioni per il repository.
    • KEY-FILE è il percorso del file di chiave JSON dell'account di servizio.

  4. Aggiungi le seguenti impostazioni al file .pypirc. Il percorso predefinito è 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 attuale 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 località a livello di una o più regioni per il repository.
    • KEY è la chiave con codifica Base64 nel file delle chiavi dell'account di servizio.

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

    Per il file associato all'utente del tuo 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 pip:

    [global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
    • KEY la chiave privata nel file delle chiavi 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