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

Prima di iniziare

Se il repository di destinazione non esiste, crea un nuovo repository di pacchetti Python.
Verifica che Python 3 sia installato. Per le istruzioni di installazione, consulta il Google Cloud tutorial per la configurazione di Python.
Verifica che l'account utente o il account di servizio che stai utilizzando disponga delle autorizzazioni necessarie per accedere al repository.
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.

Nota: se hai installato gcloud CLI in precedenza, assicurati di avere l'ultima versione eseguendo gcloud components update.
(Facoltativo) Configura le impostazioni predefinite per i comandi gcloud CLI.

Panoramica

Artifact Registry supporta i seguenti metodi di autenticazione.

Libreria Python keyring (consigliata): Artifact Registry fornisce un backend keyring per archiviare le credenziali per la connessione ai repository di Artifact Registry.
Autenticazione password: Utilizza questa opzione quando non puoi utilizzare keyring 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 di 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 di 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.

Autenticazione con keyring

La libreria Python keyring fornisce alle applicazioni un modo per accedere ai backend keyring, ovvero ai sistemi operativi e agli archivi di credenziali di terze parti.

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

Ordine di ricerca delle credenziali

Quando utilizzi il backend keyring di Artifact Registry, le tue credenziali non vengono archiviate nel tuo progetto Python. Artifact Registry cerca invece le credenziali nel seguente ordine:

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 dal account di servizio predefinito per Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o Cloud Run Functions.
Credenziali fornite da Google Cloud CLI, incluse le credenziali utente dal 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.

Configurazione di keyring

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

Installa la libreria keyring.
```
pip install keyring
```

Installa il backend di Artifact Registry.

pip install keyrings.google-artifactregistry-auth

Elenca i backend per confermare l'installazione.
```
keyring --list-backends
```
L'elenco dovrebbe includere
- ChainerBackend(priority:10)
- GooglePythonAuth(priority: 9)
Esegui il comando seguente per stampare la configurazione del repository da aggiungere al tuo 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 località regionale o multi-regionale del repository.
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 località regionale o multi-regionale del repository.
Aggiungi il 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 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 cerchi solo il tuo repository, utilizza l'index-url impostazione e assicurati che non siano configurati altri indici di pacchetti con l'extra-index-url impostazione.
```
[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 keyring con credenziali utente

Dopo aver configurato keyring, 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 keyring con credenziali del account di servizio

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

Crea un service account o scegli un account di servizio esistente che utilizzi per l'automazione.
Concedi il ruolo specifico di Artifact Registry al account di servizio per fornire l'accesso al repository.
Utilizza una delle seguenti opzioni per eseguire l'autenticazione con il tuo account di servizio:
- Credenziali predefinite dell'applicazione (consigliate)
  
  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 del account di servizio della 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 key file.

Autenticazione con una chiave del account di servizio

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

Le chiavi del service account sono credenziali a lunga durata. Utilizza le seguenti 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 minimo di Artifact Registry richiesto dal account di servizio. Ad esempio, assegna il ruolo di lettore di 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:

Crea un service account che agisca per conto della tua applicazione o scegli un service account esistente che utilizzi per l'automazione.

Avrai bisogno della posizione del file della chiave del account di servizio per configurare l'autenticazione con Artifact Registry. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Service account.

Vai alla pagina Service account

Nota: le chiavi dei service account comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi del service account quando è possibile. Se devi eseguire l'autenticazione con una chiave dell'account di servizio, sei responsabile della sicurezza della chiave privata e di altre operazioni descritte in Best practice per la gestione delle chiavi dei service account. Se non riesci a creare una chiave del service account, la creazione di chiavi del service account potrebbe essere disabilitata per la tua organizzazione. Per ulteriori informazioni, vedi Gestione delle risorse dell'organizzazione sicure per impostazione predefinita.
Se hai acquisito la chiave del service account da una fonte esterna, devi convalidarla prima dell'utilizzo. Per maggiori informazioni, consulta Requisiti di sicurezza per le credenziali di origine esterna.
Concedi il ruolo Artifact Registry appropriato al account di servizio per fornire l'accesso al repository.
Esegui il comando seguente per stampare la configurazione del repository da aggiungere al tuo 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 località regionale o multi-regionale del repository.
- KEY-FILE è il percorso del file della chiave JSON del account di servizio .
Aggiungi le seguenti impostazioni al file .pypirc. La località predefinita del file di configurazione di 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 località regionale o multi-regionale del repository.
- KEY è la chiave con codifica Base64 nel file della chiave del account di servizio.
Aggiungi il repository al file di configurazione di pip. La posizione del file di configurazione di 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.