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

Devi eseguire l'autenticazione 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 Cloudper gli ambienti di runtime come Google Kubernetes Engine e Cloud Run, ma devi verificare che siano configurate le autorizzazioni richieste.

Artifact Registry supporta i seguenti metodi di autenticazione per i repository di pacchetti Python:

  • Token di accesso: utilizza i token di accesso in automazione, pipeline CI/CD, build di container o ambienti in cui l'installazione della libreria del portachiavi non è supportata.
  • Libreria Python Keyring (consigliata per lo sviluppo locale): utilizza questa opzione sulle workstation degli sviluppatori per gestire automaticamente l'aggiornamento delle credenziali.
  • Autenticazione con password: utilizza questa opzione quando un'applicazione non supporta le credenziali predefinite dell'applicazione, ma supporta l'autenticazione con un nome utente e una password.

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 per l'installazione, consulta l'Google Cloud esercitazione per la configurazione di Python.
  3. Verifica che l'account utente o il account di servizio che stai utilizzando disponga delle autorizzazioni richieste per accedere al repository.

  4. Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente: 

    gcloud init

    Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

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

Generare token per l'autenticazione

Per autenticare il pacchetto in Artifact Registry, devi prima generare un token di autenticazione. Puoi quindi utilizzare questo token quando effettui richieste dal tuo pacchetto ad Artifact Registry.

Puoi generare un token di accesso oauth2 utilizzando Google Cloud o un token oauth2l al di fuori di Google Cloud.

I token di accesso sono validi per 60 minuti. Genera un token di accesso poco prima di eseguire comandi che interagiscono con i repository. Se il token di accesso è scaduto, devi generarne uno nuovo.

Genera un token utilizzando gcloud

Per generare un token di accesso oauth2 utilizzando Google Cloud, esegui il seguente comando:

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

Ora puoi fare riferimento a ACCESS_TOKEN quando effettui richieste dal tuo pacchetto Python ad Artifact Registry.

Genera un token senza utilizzare gcloud

Per generare un token di accesso utilizzando solo la CLI oauth2l, segui questi passaggi:

  1. Installa l'ultima versione di oauth2l eseguendo questo comando:

    go install github.com/google/oauth2l@latest

  2. Esegui questo comando:

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

    Google Cloud genera un token hash SHA256 e lo memorizza nella variabile ACCESS_TOKEN. Ora puoi fare riferimento a ACCESS_TOKEN quando effettui richieste dal tuo pacchetto Python ad Artifact Registry.

Esegui l'autenticazione con pip

Dopo aver esportato ACCESS_TOKEN, puoi passarlo a pip per installare i pacchetti:

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

Esegui l'autenticazione con la chiave automatizzata

La libreria Python keyring fornisce alle applicazioni un modo per accedere ai backend keyring, ovvero ai sistemi operativi e agli archivi delle credenziali di terze parti. Artifact Registry fornisce il backend del portachiavi keyrings.google-artifactregistry-auth per gestire l'autenticazione con i repository Artifact Registry.

Le istruzioni in questa sezione descrivono la configurazione di pip come unico indice dei pacchetti in cui pip cerca i pacchetti. Ti consigliamo di utilizzare i repository virtuali per cercare i pacchetti nei tuoi 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 un ordine particolare, quindi 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 mitigare questo rischio di confusione delle dipendenze.

Ordine di ricerca delle credenziali

Quando utilizzi il backend del portachiavi Artifact Registry, le credenziali non vengono archiviate nel tuo progetto Python. 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 Run 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, il che semplifica la risoluzione dei problemi. Se non utilizzi la variabile, verifica che tutti gli account che ADC potrebbe utilizzare dispongano delle autorizzazioni richieste. Ad esempio, il service account predefinito per le VM Compute Engine, i nodi Google Kubernetes Engine e le revisioni di Cloud Run ha accesso in sola lettura ai repository. Se intendi eseguire il caricamento da questi ambienti utilizzando il account di servizio predefinito, devi modificare le autorizzazioni.

Configurare le chiavi automatizzate

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

  1. Installa la libreria del portachiavi.

    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 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 corrente o predefinito.
    • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, questo 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 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, questo viene utilizzato quando questo flag viene omesso dal comando.
    • LOCATION è la posizione regionale o multiregionale del 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 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 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 di 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 in gcloud CLI. Accedi a Google Cloud CLI prima di connetterti a un repository di pacchetti Python.

Esegui questo comando:

gcloud auth login

Autenticazione del portachiavi con le credenziali del account di servizio

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

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

    • Credenziali predefinite dell'applicazione (consigliato)

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

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • Credenziali gcloud CLI

      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 deaccount di serviziont VM prima delle credenziali in gcloud CLI.

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

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

Configura l'autenticazione con password con le chiavi del account di servizio

Utilizza questo approccio quando richiedi l'autenticazione con un nome utente e una password.

Le chiavi del service account sono credenziali di lunga durata. 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 dalaccount di serviziot. Ad esempio, assegna il ruolo Lettore Artifact Registry a unaccount di serviziot che scarica solo gli artefatti.
  • Se i gruppi della tua organizzazione richiedono diversi livelli di accesso 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 service account che agisca per conto della tua applicazione oppure scegli un service account esistente che utilizzi per l'automazione.

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

    Vai alla pagina Service account

  2. Concedi il ruolo Artifact Registry appropriato al account di servizio 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 corrente o predefinito.
    • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, questo 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 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, questo 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 del 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 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 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 del account di servizio.
    • La stringa /simple/ alla fine del percorso del repository indica che il repository implementa l'API Python Simple Repository.

Passaggi successivi