Gestire i moduli Go

Questa pagina spiega come gestire i moduli Go pacchettizzati archiviati in Artifact Registry.

Prima di iniziare

1. Se il repository di destinazione non esiste, creane uno nuovo. Scegli Go come formato del repository.
2. Verifica di disporre delle autorizzazioni richieste per il repository.
3. (Facoltativo) Configura le impostazioni predefinite per i comandi gcloud.
4. Installa Go 1.15 o versioni successive.

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

   gcloud components install package-go-module

6. Configura Go per l'autenticazione con Artifact Registry.

Nota: Artifact Registry non supporta il flag -tool del modulo Go.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire i moduli, chiedi all'amministratore di concederti i seguenti ruoli IAM sul repository:

• Visualizza moduli: Lettore Artifact Registry (roles/artifactregistry.reader)
• Scarica o installa i moduli: Artifact Registry Reader (roles/artifactregistry.reader)
• Aggiungi moduli a un repository: Artifact Registry Writer (roles/artifactregistry.writer)
• Elimina moduli: Amministratore repository Artifact Registry (roles/artifactregistry.repoAdmin)

Per ulteriori informazioni 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.

Caricare un modulo

Modalità repository: standard

Per creare un pacchetto e caricare un modulo nel repository, esegui questo comando:

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=MODULE_PATH \
      --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 posizione regionale o multiregionale del repository.
• MODULE_PATH con il percorso del modulo. Ad esempio: example.com/foo Per saperne di più, consulta il riferimento ai 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 patch.
• SOURCE_LOCATION con il percorso della directory principale del modulo Go. Se ometti il flag --source, il valore predefinito è la directory corrente.

Il modulo viene caricato su Artifact Registry.

Per ulteriori informazioni sulla creazione di moduli Go, consulta questo tutorial.

Caricare una nuova versione del modulo

Modalità repository: standard

Per caricare una nuova versione del modulo nel progetto, nel repository e nella posizione predefiniti quando i valori predefiniti sono configurati, esegui il seguente comando con il nuovo numero di versione:

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

Sostituisci VERSION con la versione del modulo aggiornato. Ad esempio, per caricare la versione 0.1.1 di un modulo con il percorso example.com/foo, esegui il seguente comando:

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v0.1.1 \
      --source=SOURCE_LOCATION

Per contrassegnare un modulo come versione pre-release, aggiungi un trattino dopo VERSION e accoda gli identificatori pre-release del modulo:

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION-PRE_RELEASE_IDENTIFIERS \
      --source=SOURCE_LOCATION

Sostituisci PRE_RELEASE_IDENTIFIERS con caratteri alfanumerici ASCII e trattini separati da punti. Ad esempio, per caricare una pre-release di un modulo con il modulo di percorso example.com/foo identificato da alpha.x.12m.5, esegui il seguente comando:

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v1.0.0-alpha.x.12m.5 \
      --source=SOURCE_LOCATION

Nota: gli identificatori di pre-release devono essere costituiti da caratteri alfanumerici ASCII e trattini separati da punti. I metadati non sono supportati. Per ulteriori informazioni sul controllo delle versioni, consulta Semantic Versioning 2.0.0 e questo post del blog per dettagli specifici di Go.

Caricare una nuova versione principale

Modalità repository: standard

Le versioni principali non sono compatibili con le versioni precedenti. Per impedire agli utenti di importare una modifica che provoca un errore, le versioni principali successive a v1 devono avere percorsi dei moduli diversi rispetto alle versioni precedenti. A partire dal giorno v2, la versione principale viene aggiunta alla fine del percorso del modulo.

Ad esempio, il percorso del modulo per v2.0.0 di example.com/foo sarebbe example.com/foo/v2.

La best practice consigliata è sviluppare le versioni principali dopo v1 in directory separate denominate in base al suffisso della versione principale.

Per caricare una nuova versione principale 2.0.0 di un modulo con il percorso example.com/foo nel progetto, nel repository e nella posizione predefiniti quando i valori predefiniti sono configurati:

  gcloud artifacts go upload --module-path=example.com/foo/v2 --version=v2.0.0

Elenca moduli

Modalità repository: standard, remoto, virtuale

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

  gcloud artifacts packages list

L'output sarà 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

Modalità repository: standard, remoto, virtuale

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

  gcloud artifacts versions list --package=MODULE_PATH

L'output sarà 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

Utilizzare un modulo come dipendenza

Modalità repository: standard, remoto, virtuale

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. Segui le istruzioni per configurare l'autenticazione e l'ambiente Go in Configurare l'autenticazione per Go.

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@latest refresh
   

2. Se il tuo modulo non ha ancora un file go.mod, cambia directory nella cartella del modulo ed esegui go mod init per creare un file go.mod per il tuo pacchetto.

     go mod init MODULE_PATH
   

   Sostituisci MODULE_PATH con il percorso del modulo memorizzato in Artifact Registry. Per ulteriori informazioni, consulta le Informazioni di riferimento sui moduli Go.

3. Per richiedere la versione del modulo 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

4. Includi il percorso del modulo come di consueto nella sezione import del file main.go.

   Ad esempio, per importare un modulo con il percorso example.com/foo archiviato in Artifact Registry, la sezione di importazione potrebbe essere simile alla seguente:

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

5. Esegui go mod tidy per scaricare le dipendenze:

     go mod tidy
   

6. Esegui il modulo come di consueto:

     go run .
   

   Il modulo archiviato in Artifact Registry viene scaricato e utilizzato come dipendenza.

Elimina i moduli Go inclusi nel pacchetto

Modalità repository: standard, remoto

Puoi eliminare un pacchetto e tutte le relative versioni oppure eliminare una versione specifica.

• Una volta eliminato un pacchetto, non puoi annullare l'azione.

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

1. Open the Repositories page in the Google Cloud console.

   Apri la pagina Repositori

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Select the package that you want to delete.

4. Click DELETE.

5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

Replace the following:

• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

1. Open the Repositories page in the Google Cloud console.

   Apri la pagina Repositori

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Click a package to view versions of that package.

4. Select versions that you want to delete.

5. Click DELETE.

6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

Replace the following:

• VERSION is the name of the version to delete.
• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

Passaggi successivi

• Prova la guida rapida di Go.
• Scarica singoli file associati a un modulo o a una versione senza utilizzare i comandi Go.