Configura l'autenticazione nei repository di pacchetti Python

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

Quando ti connetti a un repository, devi autenticarti su Artifact Registry.

Non è necessario configurare l'autenticazione per ambienti di runtime Cloud Build o Google Cloud 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 istruzioni sull'installazione, consulta il tutorial su Google Cloud per la configurazione di Python.
  3. Verifica che l'account utente o l'account di servizio che stai utilizzando disponga delle autorizzazioni necessarie per accedere al repository.

  4. Installa Google Cloud CLI, quindi inizializzalo eseguendo il comando seguente: 

    gcloud init
  5. (Facoltativo) Configura le impostazioni predefinite per i comandi gcloud.

Panoramica

Artifact Registry supporta i seguenti metodi di autenticazione.

Libreria di portachiavi Python (consigliata)
Artifact Registry fornisce un backend per il keyring in cui archiviare le credenziali per la connessione ai repository Artifact Registry.
Autenticazione password
Usa questa opzione se non puoi utilizzare il keyring e vuoi usare un'opzione che supporti l'autenticazione di base della password.

Le istruzioni in questa documentazione descrivono la configurazione del pip come unico indice di pacchetto che il pip cerca i pacchetti. Consigliamo di utilizzare i repository virtuali per cercare pacchetti in tutti i pacchetti privati in Artifact Registry e nei pacchetti pubblici di PyPI, anziché configurare più indici di pacchetti nel file di configurazione pip. Lo strumento pip non cerca gli indici dei pacchetti in alcun ordine particolare, quindi 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à per le origini upstream per mitigare questo rischio di confusione tra le dipendenze.

Autenticazione con portachiavi

La libreria keyring Python offre alle applicazioni un modo per accedere ai backend dei keyring, vale a dire sistemi operativi e archivi di credenziali di terze parti.

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

Ordine di ricerca credenziali

Quando utilizzi il backend del keyring di Artifact Registry, le tue credenziali non vengono archiviate nel tuo progetto Python. Invece, Artifact Registry cerca 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 esplicito l'account per l'autenticazione, semplificando la risoluzione dei problemi. Se non utilizzi la variabile, verifica che tutti gli account che ADC potrebbero utilizzare dispongono delle autorizzazioni richieste. Ad esempio, l'account di servizio predefinito per le VM di Compute Engine, i nodi di Google Kubernetes Engine e le revisioni di Cloud Run hanno 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 in corso...

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

  1. Installa la libreria dei portachiavi.

    pip install keyring

  2. Installare 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 località a livello di una o più aree geografiche 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 per il 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 località a livello di una o più aree geografiche per il repository.

  6. Aggiungi il tuo 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 di 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 ambienti virtuali:

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

    Per configurare pip per cercare solo nel repository, utilizza l'impostazione index-url e assicurati che non siano configurati altri indici di pacchetto 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 dei keyring con credenziali utente

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

Esegui questo comando:

gcloud auth login

Autenticazione dei 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 scegli un account di servizio esistente che utilizzi per l'automazione.
  2. Concedi il ruolo appropriato di Artifact Registry all'account di servizio per fornire l'accesso al repository.

  3. Utilizza una delle seguenti opzioni per eseguire l'autenticazione con il tuo account di servizio:

    • Credenziali predefinite dell'applicazione (opzione consigliata)

      Assegna la posizione del file della chiave dell'account di servizio alla variabile GOOGLE_APPLICATION_CREDENTIALS in modo che l'helper delle credenziali di Artifact Registry possa ottenere la chiave durante la connessione ai repository.

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • Credenziali gcloud

      Prima di connetterti a un repository, accedi come account di servizio. Evita questa opzione se ti stai connettendo ai repository dalle VM di Compute Engine poiché Artifact Registry trova le credenziali dell'account di servizio VM prima delle credenziali in 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 devi eseguire l'autenticazione con un nome utente e una password.

Le chiavi degli account di servizio sono credenziali di lunga durata. Utilizza le seguenti linee guida per limitare l'accesso ai tuoi repository:

  • Prendi in considerazione l'utilizzo di un account di servizio dedicato per interagire con i repository.
  • Concedi il ruolo minimo di Artifact Registry richiesto dall'account di servizio. Ad esempio, assegna Artifact Registry a un account di servizio che scarica solo gli 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 per agire 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 il ruolo appropriato di Artifact Registry 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 località a livello di una o più aree geografiche per il repository.
    • KEY-FILE è il percorso del file 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 per il 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 località a livello di una o più aree geografiche per il repository.
    • KEY è la chiave con codifica base64 nel file della chiave dell'account di servizio.

  5. Aggiungi il tuo repository al file di configurazione pip. La posizione del file di configurazione PI 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 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 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