Archiviare i moduli Go in Artifact Registry

Archiviare i moduli Go in Artifact Registry

I repository Go di Artifact Registry ti consentono di archiviare, controllare le versioni e condividere moduli Go privati nei tuoi progetti. In questa guida rapida, creerai un repository, impacchetterai e caricherai un modulo di esempio e importerai il modulo come dipendenza.

Prima di iniziare

Accedi al tuo Account Google.

Se non ne hai già uno, registrati per creare un nuovo account.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

1. Installa l'ultima versione principale o la penultima versione principale di Go. Le versioni precedenti non sono supportate.
2. Installa il componente aggiuntivo gcloud CLI package-go-module:
   

   gcloud components install package-go-module

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e gestire repository di moduli Go di Artifact Registry, chiedi all'amministratore di concederti il ruolo IAM Artifact Registry Administrator (roles/artifactregistry.admin) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Crea un repository

Per creare e configurare un nuovo repository:

1. Esegui questo comando per creare un nuovo repository.

   gcloud artifacts repositories create REPOSITORY \
       --repository-format=go \
       --location=LOCATION \
       --description=DESCRIPTION
   

   Sostituisci quanto segue:

   • REPOSITORY è il nome del repository. Per ogni posizione del repository in un progetto, i nomi dei repository devono essere univoci.
   • LOCATION è la posizione regionale o multiregionale per il repository. Puoi omettere questo flag se imposti un valore predefinito. Per visualizzare un elenco delle località supportate, esegui il comando gcloud artifacts locations list.
   • DESCRIPTION è una descrizione facoltativa del repository. Non includere dati sensibili, poiché le descrizioni dei repository non sono criptate.

2. Esegui questo comando per visualizzare i dettagli del repository.

     gcloud artifacts repositories describe --location=LOCATION REPOSITORY
   

   L'output è simile al seguente:

     Encryption: Google-managed key
     Repository Size: 0.000MB
     createTime: '2022-06-03T20:20:01.644813Z'
     format: GO
     mode: STANDARD_REPOSITORY
     name: projects/my-project/locations/us-west1/repositories/my-repo
     updateTime: '2022-06-03T20:20:01.644813Z'
   

Imposta i valori predefiniti per i comandi gcloud

Puoi semplificare i comandi gcloud CLI configurando i valori predefiniti per progetto, repository e località. Una volta configurati i valori predefiniti, i tag --project, --location e --repository non sono necessari.

Pacchettizzare e caricare un modulo Go

I pacchetti del componente aggiuntivo package-go-module gcloud CLI pacchettizzano i moduli Go, consentendoti di creare versioni e caricarle su Artifact Registry utilizzando il comando gcloud.

Crea un modulo Go

Per prima cosa, crea un semplice modulo Go da caricare nel repository.

1. Nella tua home directory, crea una directory denominata "foo" per il tuo modulo

   mkdir foo
   

2. Passa alla directory del modulo ed esegui go mod init per creare un file go.mod per il modulo.

     cd foo \
     go mod init example.com/foo
   

   Sostituisci example.com/foo con il percorso del modulo. Per saperne di più, consulta le Informazioni di riferimento sui moduli Go.

3. Crea un file foo.go nella directory foo con il seguente contenuto:

   
   package foo
   
   const HelloWorld = "Hello World!"
   

Crea il pacchetto del modulo e caricalo

Pacchettizza e carica il modulo nel repository:

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=example.com/foo \
      --version=VERSION \
      --source=SOURCE_LOCATION

Sostituisci quanto segue:

• PROJECT con il tuo Google Cloud ID progetto.
• REPOSITORY con il nome del repository in cui è archiviato il pacchetto.
• LOCATION con la località regionale o multiregionale del repository.
• example.com/foo con il percorso del modulo. Per ulteriori informazioni, consulta le Informazioni di riferimento sui moduli Go.
• VERSION con la versione semantica del modulo nel formato vX.Y.Z, dove X è la versione principale, Y è la versione secondaria e Z è la versione della patch.
• SOURCE_LOCATION con il percorso della directory radice del modulo Go. Se ometti il flag --source, il valore predefinito è la directory corrente.

Il modulo viene caricato su Artifact Registry.

Per saperne di più sulla creazione di moduli Go, consulta questo tutorial.

Moduli elenco

Esegui questo comando per esaminare il modulo Go caricato nel progetto, nel repository e nella località predefiniti quando sono configurati i valori predefiniti:

  gcloud artifacts packages list

L'output è simile al seguente:

  Listing items under project my-project, location us-west1, repository my-repo.

  PACKAGE                   CREATE_TIME          UPDATE_TIME
  example.com/foo           2022-06-03T20:43:39  2022-06-20T20:37:40

Visualizzare i dettagli della versione del modulo

Esegui questo comando per visualizzare le versioni del modulo nel progetto, nel repository e nella località predefiniti quando sono configurati i valori predefiniti:

  gcloud artifacts versions list --package=MODULE_PATH

L'output è simile al seguente:

  Listing items under project my-project, location us-west1, repository my-repo, package example.com/foo.

  VERSION  DESCRIPTION  CREATE_TIME          UPDATE_TIME
  v0.1.0                2022-06-03T20:43:39  2022-06-03T20:43:39
  v0.1.1                2022-06-20T20:37:40  2022-06-20T20:37:40

Scaricare i moduli

Per importare i moduli archiviati in Artifact Registry, devi indicare a Go di cercare le dipendenze da Artifact Registry e ignorare il database dei checksum.

Configura l'ambiente Go

1. Chiedi 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 posizione 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 modulo dal controllo utilizzando il database pubblico dei checksum:

     export GONOSUMDB=MODULE_PATH_REGEX
   

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

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

     export GONOSUMDB=example.com/foo
   

   Se vuoi che tutti i moduli con percorsi che iniziano con example.com vengano esclusi dal controllo utilizzando il database dei checksum pubblici, esegui il seguente comando:

     export GONOSUMDB=example.com/*
   

Autenticarsi in Artifact Registry

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 la procedura di autenticazione, puoi utilizzare lo strumento di assistenza 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.

Credenziali di breve durata (consigliato)

Utilizza lo strumento helper delle credenziali Go di Artifact Registry per aggiornare i token di autenticazione nel file netrc.

Utilizza una chiave del account di servizio

Utilizza questa opzione quando non puoi utilizzare le credenziali nel tuo ambiente per l'autenticazione. Aggiungi la chiave del account di servizio non criptata al file netrc.

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.

Aggiungi l'helper per le credenziali Go a GONOPROXY

Prima di utilizzare l'helper delle credenziali Go, devi aggiungerlo all'elenco GONOPROXY per forzare il download 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 dalla sorgente.

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 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 posizione regionale o multiregionale del 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 file netrc per l'autenticazione con password.

Utilizzare il modulo come dipendenza

1. Se utilizzi credenziali di breve durata per l'autenticazione in Artifact Registry, devi aggiornare il token OAuth eseguendo il seguente comando:

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

2. Nella tua home directory, crea una directory denominata "bar"

     mkdir bar
   

3. Passa alla directory del modulo ed esegui go mod init per creare un file go.mod per il pacchetto.

     cd bar \
     go mod init example.com/bar
   

   Sostituisci example.com/bar con il percorso del modulo. Per saperne di più, consulta il riferimento ai moduli Go.

4. Per richiedere la versione di foo archiviata in Artifact Registry, modifica il file go.mod in modo che sia simile al seguente:

   
   module example.com/bar
   
   go 1.19
   
   require example.com/foo v0.1.0
   

   Sostituisci quanto segue:

   • example.com/foo è il percorso del modulo richiesto
   • v0.1.0 è la versione archiviata in Artifact Registry

5. Crea un file main.go nella directory bar con i seguenti contenuti:

     
     package main
   
     import (
       "fmt"
   
       foo "example.com/foo"
     )
   
     func main() {
       fmt.Println(foo.HelloWorld)
     }
   
     
   

6. Esegui go mod tidy per scaricare le dipendenze, incluso il pacchetto foo:

     go mod tidy
   

7. Esegui il modulo della barra:

     go run .
   

   L'output è simile al seguente:

     Hello World!
   

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa pagina, segui questi passaggi.

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa pagina, segui questi passaggi. Prima di rimuovere il repository, assicurati che tutti i moduli che vuoi conservare siano disponibili in un'altra posizione.

1. Per eliminare il repository:

     gcloud artifacts repositories delete \
         --location=LOCATION \
         --project=PROJECT \
         REPOSITORY
   

   Sostituisci quanto segue:

   • LOCATION con la località regionale o multiregionale del repository.
   • PROJECT con il tuo Google Cloud ID progetto.
   • REPOSITORY con il nome del repository.

2. Se vuoi rimuovere il repository predefinito e le impostazioni di localizzazione configurate per la configurazione gcloud attiva, esegui i comandi seguenti:

     gcloud config unset artifacts/repository
     gcloud config unset artifacts/location
   

Passaggi successivi

• Scopri di più sulla configurazione dell'autenticazione.
• Scopri di più sulla gestione dei repository.
• Scopri di più sulla gestione dei moduli Go.
• Leggi le nostre risorse su DevOps ed esplora il programma di ricerca DevOps Research and Assessment.