Configurare l'autenticazione per Go

L'autenticazione dell'ambiente client con Artifact Registry ti consente di archiviare moduli Go privati e recuperarli come dipendenze di build.

Opzioni di autenticazione

La configurazione dell'autenticazione è diversa per il caricamento e il download dei pacchetti.

Autenticazione per i caricamenti

Quando pacchettizza e carica un modulo Go in Artifact Registry, lo strumento gcloud CLI cerca le credenziali nel tuo ambiente per configurare l'autenticazione nel seguente ordine, a meno che non venga passato il flag --json_key per utilizzare una chiave del account di servizio.

  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. Le credenziali fornite dal 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, semplificando 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 di Compute Engine, i nodi di Google Kubernetes Engine e le revisioni di Cloud Run ha accesso di sola lettura ai repository. Se intendi caricare da questi ambienti utilizzando il account di servizio predefinito, devi modificare le autorizzazioni.

Autenticazione per i download

Quando scarichi i moduli Go pacchettizzati da utilizzare come dipendenze da Artifact Registry, il file binario Go utilizza le credenziali nel file netrc per autenticarsi in Artifact Registry. Per semplificare il processo di autenticazione, puoi utilizzare l'helper per le credenziali Go per aggiornare i token nel file netrc per l'autenticazione in Artifact Registry.

La posizione del file netrc può essere impostata con la variabile di ambiente netrc. Se la variabile NETRC non è impostata, il comando go leggerà $HOME/.netrc su piattaforme di tipo UNIX o %USERPROFILE%\_netrc su Windows.

Artifact Registry supporta i seguenti metodi di autenticazione quando utilizzi le credenziali nel file netrc:

Credenziali di breve durata (consigliato)
Utilizza lo strumento di supporto delle credenziali Go di Artifact Registry per aggiornare i token di autenticazione nel file netrc utilizzando le credenziali nel tuo ambiente oppure aggiungi manualmente le credenziali di Artifact Registry al file netrc.
Utilizza una chiave del account di servizio
Utilizza questa opzione quando non puoi utilizzare le credenziali nel tuo ambiente per l'autenticazione. Puoi utilizzare lo strumento di supporto per le credenziali Go di Artifact Registry per aggiungere la chiave del account di servizio non criptata al file netrc o aggiungerla manualmente al file.

Prima di iniziare

  1. Installa Go 1.15 o versioni successive.

  2. Installa il componente aggiuntivo package-go-module di gcloud CLI:

    gcloud components install package-go-module

Configura l'ambiente Go

  1. Indica a Go di scaricare i moduli da Artifact Registry, dal proxy del modulo Go pubblico e poi dall'origine in questo ordine:

      export GOPROXY=https://LOCATION-go.pkg.dev/PROJECT/REPOSITORY,https://proxy.golang.org,direct

    Sostituisci quanto segue:

    • LOCATION è la località regionale o multiregionale del repository.
    • PROJECT è il tuo Google Cloud ID progetto.
    • REPOSITORY è il nome del repository in cui è archiviato il pacchetto.

  2. Escludi il tuo modulo dal controllo utilizzando il database pubblico dei checksum:

      export GONOSUMDB=MODULE_PATH_REGEX

    Sostituisci MODULE_PATH_REGEX con il percorso del modulo o con un'espressione regolare se vuoi escludere più moduli.

    Ad esempio, per escludere il modulo example.com/foo dal controllo utilizzando il database dei checksum pubblico, esegui questo comando:

      export GONOSUMDB=example.com/foo

    Il seguente comando esclude tutti i moduli con percorsi che iniziano con example.com dal controllo tramite il database di checksum pubblico:

      export GONOSUMDB=example.com/*

Aggiungi le credenziali di Artifact Registry al file netrc

  1. Esegui questo comando per aggiungere le tue credenziali di Artifact Registry al file netrc con l'helper per le credenziali Go:

      GOPROXY=proxy.golang.org \
      go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 \
      add-locations --locations=LOCATION \
      --json_key=PATH_TO_JSON_KEY

    Dove:

    • LOCATION è la località regionale o multiregionale del tuo repository. Per aggiungere più località, inseriscile come elenco separato da virgole.

    • PATH_TO_JSON_KEY (Facoltativo) Il percorso della chiave del account di servizio.

      L'helper per le credenziali Go aggiunge impostazioni al file netrc per l'autenticazione in Artifact Registry. Se passi il flag --json_key, la chiave viene aggiunta al file netrc per l'autenticazione della password.

  2. Se utilizzi credenziali di breve durata per l'autenticazione ad Artifact Registry, devi aggiornare il token OAuth eseguendo il seguente comando prima di utilizzare il modulo come dipendenza:

      GOPROXY=proxy.golang.org \
  go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 refresh

Autenticazione con una chiave del account di servizio

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

Le chiavi dei 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 dal account di servizio. Ad esempio, assegna il ruolo Artifact Registry Reader 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é 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 o 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 aggiungere le credenziali del account di servizio al file netrc con l'helper per le credenziali Go:

      GOPROXY=proxy.golang.org \
      go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 \
      add-locations --locations=LOCATION \
      --json_key=PATH_TO_JSON_KEY

    Dove:

    • LOCATION è la località regionale o multiregionale del tuo repository. Per aggiungere più località, inseriscile come elenco separato da virgole.

    • PATH_TO_JSON_KEY è il percorso del file della chiave JSON del account di servizio.

      L'helper per le credenziali Go aggiunge la chiave del account di servizio al file netrc per l'autenticazione della password.

È anche possibile aggiungere manualmente la chiave del account di servizio al file netrc nel seguente formato:

machine LOCATION.pkg.dev
login _json_key_base64
password KEY

Sostituisci quanto segue:

  • LOCATION con la località regionale o multiregionale del tuo repository.
  • KEY con la chiave con codifica Base64 nel file della chiave del account di servizio.

Aggiungi l'helper per le credenziali Go a GONOPROXY

Prima di utilizzare l'helper per le credenziali Go, devi aggiungerlo all'elenco GONOPROXY per forzare Go a scaricarlo direttamente da GitHub. Se hai altri moduli che vuoi scaricare direttamente dall'origine, puoi aggiungerli in un elenco separato da virgole, come mostrato nell'esempio seguente:

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

Dove MODULE_PATH1 e MODULE_PATH2 sono i percorsi dei moduli da scaricare dall'origine.

Per aggiungere l'helper per le credenziali Go all'elenco GONOPROXY ed eseguirlo per configurare le tue credenziali:

  1. Aggiungi l'helper per le credenziali Go al tuo GONOPROXY

      export GONOPROXY=github.com/GoogleCloudPlatform/artifact-registry-go-tools

  2. Esegui questo comando per aggiungere le tue credenziali di Artifact Registry al file netrc con lo strumento del pacchetto del modulo Go:

      GOPROXY=proxy.golang.org \
      go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 \
      add-locations --locations=LOCATION \
      [--json_key=path/to/service/account/key.json]

    Dove LOCATION è la località regionale o multiregionale del tuo repository. Per aggiungere più località, inseriscile come elenco separato da virgole.

    L'helper per le credenziali Go aggiunge impostazioni al file netrc per l'autenticazione in Artifact Registry. Se passi il flag --json_key, la chiave viene aggiunta al tuo file netrc per l'autenticazione con password.

Passaggi successivi