Quando utilizzi un'applicazione di terze parti per connetterti a un repository Artifact Registry, devi eseguire l'autenticazione in Artifact Registry. Questa documentazione è incentrata sulla configurazione di Maven e Gradle.
Non è necessario configurare l'autenticazione per gli ambienti di runtime Cloud Build o Google Cloud, come Google Kubernetes Engine e Cloud Run, ma devi verificare che siano configurate le autorizzazioni richieste. Per saperne di più, consulta le informazioni su Cloud Build e sul deployment negli ambienti di runtime di Google Cloud.
Prima di iniziare
-
Installa Google Cloud CLI, quindi initialize eseguendo questo comando:
gcloud init
- (Facoltativo) Configura i valori predefiniti per i comandi gcloud.
Se stai configurando l'autenticazione con un repository standard, verifica il criterio della versione in modo da poter configurare correttamente il tuo progetto Maven per i tipi di pacchetti Java che puoi caricare.
Console
Apri la pagina Repositories nella console Google Cloud.
Fai clic sul repository per cui vuoi eseguire l'autenticazione.
La sezione Dettagli mostra il criterio relativo alla versione. Se il repository ha un criterio relativo alla versione degli snapshot, il campo Consenti sovrascrittura snapshot indica se gli snapshot possono sovrascrivere le versioni degli snapshot corrispondenti nel repository.
gcloud
Esegui questo comando per visualizzare una descrizione di un repository.
gcloud artifacts repositories describe REPOSITORY \ --project=PROJECT \ --location=LOCATION
Dove
- REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
- PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto attuale o predefinito.
- LOCATION è la località a livello di una o più regioni per il repository.
L'output del comando include informazioni sul criterio di versione in
mavenConfig
. In questo esempio, il repository ha un criterio di versione degli snapshot e gli snapshot non possono sovrascrivere versioni identiche nel repository.Encryption: Google-managed key createTime: '2021-10-04T19:39:10.897404Z' format: MAVEN mavenConfig: allowSnapshotOverwrites: false versionPolicy: SNAPSHOT
Se un repository non ha un criterio di versione, il valore di
mavenConfig
è{}
.
Panoramica
Artifact Registry supporta i seguenti metodi di autenticazione.
- Utilizzo di un helper per l'autenticazione
- Questa opzione offre la massima flessibilità. Quando includi l'helper nella configurazione di Maven o Gradle, Artifact Registry cerca le credenziali dell'account di servizio nell'ambiente.
- Specificare una chiave dell'account di servizio come credenziale
- Utilizza questa opzione quando un'applicazione non supporta le credenziali predefinite dell'applicazione, ma supporta l'autenticazione con nome utente e password.
Le chiavi dell'account di servizio sono credenziali di lunga durata. Segui queste 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 Artifact Registry minimo richiesto dall'account di servizio. Ad esempio, assegna Lettore Artifact Registry 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é a livello di progetto.
- Segui le best practice per la gestione delle credenziali.
Autenticazione con un assistente per le credenziali
Artifact Registry fornisce un wagon Maven e un plug-in Gradle come aiutanti per le credenziali. Quando utilizzi l'helper per le credenziali, le tue credenziali non vengono archiviate nel progetto Java. Artifact Registry cerca invece le credenziali nel seguente ordine:
Credenziali predefinite dell'applicazione (ADC), una strategia che cerca le credenziali nel seguente ordine:
Credenziali definite nella variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
.Credenziali fornite dall'account di servizio predefinito per Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o Cloud Functions.
Credenziali fornite da Google Cloud CLI, incluse le credenziali utente del comando
gcloud auth application-default login
.
La variabile GOOGLE_APPLICATION_CREDENTIALS
rende esplicita l'account
per l'autenticazione, il che semplifica la risoluzione dei problemi. Se non utilizzi la variabile, verifica che tutti gli account che potrebbero essere utilizzati da ADC dispongano delle autorizzazioni richieste. Ad esempio, l'account di servizio predefinito per le VM di Compute Engine, i nodi Google Kubernetes Engine e le revisioni di Cloud Run ha accesso di sola lettura ai repository. Se intendi caricare da questi ambienti utilizzando l'account di servizio predefinito, devi modificare le autorizzazioni.
Configura un account di servizio per un assistente per le credenziali
Per creare un account di servizio e configurare l'autenticazione utilizzando la variabile di ambiente:
Crea un account di servizio che agisca per conto della tua applicazione oppure scegli un account di servizio esistente che utilizzi per l'automazione.
Avrai bisogno della posizione del file della chiave dell'account di servizio per configurare l'autenticazione con Artifact Registry. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Account di servizio.
Concedi il ruolo Artifact Registry specifico all'account di servizio per fornire l'accesso al repository.
Assegna il percorso del file della chiave dell'account di servizio alla variabile
GOOGLE_APPLICATION_CREDENTIALS
, in modo che l'helper per le credenziali di Artifact Registry possa ottenere la tua chiave durante la connessione ai repository.export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
Dove KEY-FILE è il percorso del file della chiave dell'account di servizio.
Configura Maven
Configura Maven per il tipo di repository in uso.
Standard
Esegui questo comando per stampare la configurazione del repository da aggiungere al tuo progetto Java.
gcloud artifacts print-settings mvn \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION
Dove
- PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto attuale o predefinito.
- REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
- LOCATION è la località a livello di una o più regioni per il repository.
Aggiungi le impostazioni restituite alle sezioni appropriate nel file
pom.xml
per il tuo progetto Maven. Per i dettagli sulla struttura del file, consulta il riferimento POM di Maven.L'esempio seguente mostra le impostazioni per un repository in cui sono archiviate sia le versioni snapshot che quelle di release.
<distributionManagement> <snapshotRepository> <id>artifact-registry</id> <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url> </snapshotRepository> <repository> <id>artifact-registry</id> <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url> </repository> </distributionManagement> <repositories> <repository> <id>artifact-registry</id> <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories> <build> <extensions> <extension> <groupId>com.google.cloud.artifactregistry</groupId> <artifactId>artifactregistry-maven-wagon</artifactId> <version>2.2.1</version> </extension> </extensions> </build>
Gli elementi
<release>
e<snapshot>
indicano se il repository archivia i pacchetti di release, di snapshot o entrambi. Queste impostazioni devono corrispondere al criterio della versione del repository.L'elemento
<build>
definisce il vagone Artifact Registry come un'estensione. Per informazioni sul vagone, consulta la documentazione relativa agli strumenti Maven di Artifact Registry.
Remoto o virtuale
Modifica il file
pom.xml
nel progetto. Per i dettagli sulla struttura del file, consulta il riferimento POM di Maven.L'esempio seguente mostra le impostazioni per un repository remoto in cui sono archiviate sia le versioni snapshot che quelle di release. In questo esempio, il progetto ha una dipendenza da una versione del pacchetto Guava.
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.google.hello</groupId> <artifactId>repo-config</artifactId> <version>4.1-SNAPSHOT</version> <description>version 1 release</description> <properties> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> </properties> <dependencies> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>28.0-jre</version> </dependency> </dependencies> <repositories> <repository> <id>central</id> <name>Maven Central remote repository</name> <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME</url> <layout>default</layout> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories> <build> <extensions> <extension> <groupId>com.google.cloud.artifactregistry</groupId> <artifactId>artifactregistry-maven-wagon</artifactId> <version>2.2.1</version> </extension> </extensions> </build> </project>
La sezione
<repositories>
definisce il repository Artifact Registry. Per un repository remoto, l'elemento<id>
deve essere impostato sucentral
. Questa impostazione sostituisce il valore predefinito per l'ID repositorycentral
ereditato dal Super POM.La sezione
<build>
imposta il vagone Artifact Registry come estensione. Per informazioni sul vagone, consulta la documentazione relativa agli strumenti Maven di Artifact Registry.In questo esempio, la sezione
<dependencies>
imposta una dipendenza sulla versione del pacchetto Guava28.0-jre
.
Maven risolve alcune dipendenze prima di applicare un vagone definito in
pom.xml
, tra cui:- Riferimenti in un progetto Maven secondario a un progetto principale utilizzando l'elemento
<parent>
. - Dipendenze dei plug-in archiviate in Artifact Registry.
Se il tuo progetto deve risolvere queste dipendenze, devi utilizzare il meccanismo delle estensioni principali per assicurarti che Maven possa individuare i plug-in e i file POM principali.
Nel tuo progetto, crea il file
${maven.projectBasedir}/.mvn/extensions.xml
con i contenuti seguenti. L'elemento<extension>
definisce il vagone.<extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd"> <extension> <groupId>com.google.cloud.artifactregistry</groupId> <artifactId>artifactregistry-maven-wagon</artifactId> <version>2.2.1</version> </extension> </extensions>
Ora Maven può risolvere le dipendenze padre o plug-in da Artifact Registry.
- Riferimenti in un progetto Maven secondario a un progetto principale utilizzando l'elemento
La configurazione dell'autenticazione è stata completata.
Configura Gradle
Configura Gradle per il tipo di repository che stai utilizzando.
Standard
Esegui questo comando per stampare la configurazione del repository da aggiungere al tuo progetto Java.
gcloud artifacts print-settings gradle \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION
Dove
- PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto attuale o predefinito.
- REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
- LOCATION è la località a livello di una o più regioni per il repository.
Aggiungi le impostazioni del repository al file
build.gradle
. Il seguente esempio mostra la posizione relativa delle sezioni stampate.plugins { id "maven-publish" id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.1" } publishing { publications { mavenJava(MavenPublication) { groupId 'maven.example.id' from components.java } } repositories { maven { url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY" } } } repositories { maven { url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY" } }
La sezione
plugins
dichiara il plug-in Artifact Registry. Per informazioni sul plug-in, consulta la documentazione relativa agli strumenti Maven di Artifact Registry.La sezione
publishing
definisce i file da caricare e il repository Artifact Registry di destinazione. Puoi aggiornare l'elenco dei file nella sezionepublications
quando è tutto pronto per il caricamento. Per informazioni sulle impostazioni di pubblicazione, consulta la documentazione relativa al plug-in Maven Pubblica.
Remoto o virtuale
Aggiungi le impostazioni del repository al file
build.gradle
.L'esempio seguente mostra le impostazioni per un repository remoto. In questo esempio, il progetto ha una dipendenza da una versione del pacchetto Guava.
plugins { id 'java' id "maven-publish" id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.1" id 'maven' } repositories { maven { url "artifactregistry://LOCATION-maven.pkg.dev /PROJECT_ID/REMOTE-REPOSITORY-NAME" } } dependencies { compile "com.google.guava:guava:31.1-jre" }
La sezione
plugins
dichiara il plug-in Artifact Registry. Per informazioni sul plug-in, consulta la documentazione relativa agli strumenti Maven di Artifact Registry.La sezione
repositories
definisce il repository Artifact Registry.In questo esempio, la sezione
dependencies
imposta una dipendenza sulla versione del pacchetto Guava31.1-jre
.
Definisci le dipendenze per il pacchetto nella sezione
dependencies
.Se devi utilizzare repository nei file
init.gradle
osettings.gradle
, puoi aggiungere la configurazione del plug-in a questi file.Per
init.gradle
, aggiungi la seguente configurazione:initscript { repositories { maven { url "https://plugins.gradle.org/m2/" } } dependencies { classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.1" } } apply plugin: com.google.cloud.artifactregistry.gradle.plugin.ArtifactRegistryGradlePlugin
Per settings.gradle, aggiungi la seguente configurazione:
buildscript { repositories { maven { url "https://plugins.gradle.org/m2/" } } dependencies { classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.1" } } apply plugin: "com.google.cloud.artifactregistry.gradle-plugin"
La configurazione dell'autenticazione è stata completata.
Configurazione dell'autenticazione tramite password
Utilizza questo approccio quando la tua applicazione Java richiede l'autenticazione con un nome utente e una password specificati.
Configurare un account di servizio per l'autenticazione tramite password
Per creare un account di servizio:
Crea un account di servizio che agisca per conto della tua applicazione oppure scegli un account di servizio esistente che utilizzi per l'automazione.
Avrai bisogno della posizione del file della chiave dell'account di servizio per configurare l'autenticazione con Artifact Registry. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Account di servizio.
Se vuoi attivare l'account di servizio nella sessione corrente dell'interfaccia a riga di comando gcloud, esegui il comando:
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
Dove
- ACCOUNT è l'account utente o di servizio.
- KEY-FILE è il percorso del file di chiave JSON dell'account di servizio.
Configura Maven
Configura Maven per il tipo di repository in uso.
Standard
Esegui questo comando per stampare la configurazione del repository da aggiungere al tuo progetto Java.
gcloud artifacts print-settings mvn \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION \ --json-key=KEY-FILE
Dove
- PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto attuale o predefinito.
- REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
- LOCATION è la località a livello di una o più regioni per il repository.
- KEY-FILE è il percorso del file di chiave JSON dell'account di servizio.
Il comando restituisce le impostazioni da includere nel progetto Java, tra cui una versione con codifica Base64 della chiave privata.
- Aggiungi le impostazioni del repository restituite nell'elemento
<project>
alle sezioni appropriate del filepom.xml
per il tuo progetto Maven. Per informazioni dettagliate sulla struttura del file, consulta il riferimento POM di Maven.
<project> <distributionManagement> <snapshotRepository> <id>artifact-registry</id> <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url> </snapshotRepository> <repository> <id>artifact-registry</id> <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url> </repository> </distributionManagement> <repositories> <repository> <id>artifact-registry</id> <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories> </project>
Gli elementi
<release>
e<snapshot>
indicano se il repository archivia i pacchetti di release, di snapshot o entrambi. Queste impostazioni devono corrispondere al criterio di versione del repository.- Aggiungi le impostazioni di autenticazione restituite nell'elemento
<settings>
alla sezione<servers>
del file~/.m2/settings.xml
. Nell'esempio seguente,KEY
è la chiave con codifica Base64 del file della chiave.
Per ulteriori informazioni, consulta il riferimento alle impostazioni di Maven.
<settings> <servers> <server> <id>artifact-registry</id> <configuration> <httpConfiguration> <get> <usePreemptive>true</usePreemptive> </get> <head> <usePreemptive>true</usePreemptive> </head> <put> <params> <property> <name>http.protocol.expect-continue</name> <value>false</value> </property> </params> </put> </httpConfiguration> </configuration> <username>_json_key_base64</username> <password>KEY</password> </server> </servers> </settings>
Remoto o virtuale
Aggiungi le impostazioni del repository alle sezioni appropriate del file
pom.xml
per il tuo progetto Maven. Per i dettagli sulla struttura del file, consulta il riferimento POM di Maven.<repositories> <repository> <id>central</id> <name>Maven Central remote repository</name> <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME</url> <layout>default</layout> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories>
La sezione
<repositories>
definisce il repository Artifact Registry. Per un repository remoto, l'elemento<id>
deve essere impostato sucentral
. Questa impostazione sostituisce il valore predefinito per l'ID repositorycentral
ereditato dal Super POM.Utilizza il seguente comando per codificare il file di chiave in Base64. Sostituisci KEY-FILE con il nome del file della chiave.
base64 -w 0 KEY-FILE
Aggiungi impostazioni di autenticazione nell'elemento
<settings>
alla sezione<servers>
del file~/.m2/settings.xml
.
Per ulteriori informazioni, consulta il riferimento alle impostazioni di Maven.
<settings> <servers> <server> <id>artifact-registry</id> <configuration> <httpConfiguration> <get> <usePreemptive>true</usePreemptive> </get> <head> <usePreemptive>true</usePreemptive> </head> <put> <params> <property> <name>http.protocol.expect-continue</name> <value>false</value> </property> </params> </put> </httpConfiguration> </configuration> <username>_json_key_base64</username> <password>KEY</password> </server> </servers> </settings>
La configurazione dell'autenticazione è stata completata.
Configura Gradle
Configura Gradle per il tipo di repository che stai utilizzando.
Standard
Esegui questo comando per stampare la configurazione del repository da aggiungere al tuo progetto Java.
gcloud artifacts print-settings gradle \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION \ --json-key=KEY-FILE
Dove
- PROJECT è l'ID progetto.
- REPOSITORY è l'ID o l'identificatore completo del repository. Se hai configurato un repository predefinito di Artifact Registry, viene utilizzato quando questo flag viene omesso dal comando.
- KEY-FILE è il percorso del file di chiave JSON dell'account di servizio. Se hai eseguito il comando per attivare l'account di servizio, puoi omettere questo flag.
Il comando restituisce le impostazioni da includere nel progetto Java, tra cui una versione con codifica Base64 della chiave privata.
La seguente riga della configurazione restituita definisce una variabile denominata
artifactRegistryMavenSecret
per la chiave dell'account di servizio. Aggiungi questa riga al file~/.gradle/gradle.properties
in modo che la chiave non sia visibile nelle build o nel repository di controllo del codice sorgente.artifactRegistryMavenSecret = KEY
In questa riga, KEY è la chiave privata nel file di chiavi dell'account di servizio. Per
_json_key_base64
, il valoreartifactRegistryMavenSecret
viene impostato sulla chiave con codifica Base64 come password.In
build.gradle
, specifica le impostazioni del repository:plugins { id "maven-publish" } publishing { publications { mavenJava(MavenPublication) { groupId 'maven.example.id' from components.java } } repositories { maven { url "https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY" credentials { username = "_json_key_base64" password = "$artifactRegistryMavenSecret" } authentication { basic(BasicAuthentication) } } } } repositories { maven { url "https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY" credentials { username = "_json_key_base64" password = "$artifactRegistryMavenSecret" } authentication { basic(BasicAuthentication) } } }
- La sezione
repositories
imposta l'URL del repository e le credenziali per l'autenticazione. - La sezione
publishing
definisce i file da caricare e il repository Artifact Registry di destinazione. Puoi aggiornare l'elenco dei file nella sezionepublications
quando è tutto pronto per il caricamento. Per informazioni sulle impostazioni di pubblicazione, consulta la documentazione relativa al plug-in Maven Pubblica.
- La sezione
Remoto o virtuale
Utilizza il seguente comando per codificare il file di chiave in Base64. Sostituisci KEY-FILE con il nome del file della chiave.
base64 -w 0 KEY-FILE
Nel file
~/.gradle/gradle.properties
, aggiungi la riga seguente in modo che la chiave non sia visibile nelle build o nel repository di controllo del codice sorgente.artifactRegistryMavenSecret = KEY
In questa riga, KEY è il contenuto del file della chiave codificato in base64.
Aggiungi le impostazioni del repository al file
build.gradle
.
L'esempio seguente mostra la configurazione di un repository remoto.
plugins { id 'java' id "maven-publish" id 'maven' } repositories { maven { url "artifactregistry://LOCATION-maven.pkg.dev /PROJECT_ID/REMOTE-REPOSITORY-NAME" credentials { username = "_json_key_base64" password = "$artifactRegistryMavenSecret" } authentication { basic(BasicAuthentication) } dependencies { compile "com.google.guava:guava:31.1-jre" }
La sezione
repositories
definisce il repository Artifact Registry.In questo esempio, la sezione
dependencies
imposta una dipendenza sulla versione del pacchetto Guava31.1-jre
.
Definisci le dipendenze per il pacchetto nella sezione
dependencies
.
La configurazione dell'autenticazione è stata completata.