Debe autenticarse en Artifact Registry cuando utilice una aplicación de terceros para conectarse a un repositorio de Artifact Registry. Esta documentación se centra en la configuración de Maven y Gradle.
No es necesario configurar la autenticación para Cloud Build ni para los entornos de ejecución, como Google Kubernetes Engine y Cloud Run, pero debes verificar que se hayan configurado los permisos necesarios. Google CloudPara obtener más información, consulta la información sobre Cloud Build y el despliegue en entornos de Google Cloud tiempo de ejecución.
Antes de empezar
-
Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando:
gcloud init
Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.
- (Opcional) Configura los valores predeterminados de los comandos de gcloud.
Si vas a configurar la autenticación con un repositorio estándar, verifica la política de versiones para poder configurar tu proyecto de Maven correctamente en función de los tipos de paquetes Java que puedes subir.
Consola
Abre la página Repositorios en la consola de Google Cloud .
Haz clic en el repositorio en el que quieras autenticarte.
En la sección Detalles se muestra la política de versiones. Si el repositorio tiene una política de versiones de instantáneas, el campo Permitir sobrescrituras de instantáneas indica si las instantáneas pueden sobrescribir versiones de instantáneas coincidentes en el repositorio.
gcloud
Ejecuta el siguiente comando para ver una descripción de un repositorio.
gcloud artifacts repositories describe REPOSITORY \ --project=PROJECT \ --location=LOCATION
Dónde
- REPOSITORY es el ID del repositorio. Si has configurado un repositorio predeterminado de Artifact Registry, se usará cuando se omita esta marca en el comando.
- PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado actual.
- LOCATION es la ubicación regional o multirregional del repositorio.
El resultado del comando incluye información sobre la política de versiones en
mavenConfig
. En este ejemplo, el repositorio tiene una política de versiones de instantáneas y las instantáneas no pueden sobrescribir versiones idénticas en el repositorio.Encryption: Google-owned and Google-managed encryption key createTime: '2021-10-04T19:39:10.897404Z' format: MAVEN mavenConfig: allowSnapshotOverwrites: false versionPolicy: SNAPSHOT
Si un repositorio no tiene una política de versiones, el valor de
mavenConfig
es{}
.
Información general
Artifact Registry admite los siguientes métodos de autenticación.
- Usar un asistente de autenticación
- Esta opción es la más flexible. Cuando incluyes el asistente en tu configuración de Maven o Gradle, Artifact Registry busca credenciales de cuenta de servicio en el entorno.
- Especificar una clave de cuenta de servicio como credencial
- Usa esta opción cuando una aplicación no admita las credenciales predeterminadas de la aplicación, pero sí la autenticación con un nombre de usuario y una contraseña.
Las claves de cuenta de servicio son credenciales de larga duración. Sigue estas directrices para limitar el acceso a tus repositorios:
- Te recomendamos que uses una cuenta de servicio específica para interactuar con los repositorios.
- Asigna el rol de Artifact Registry mínimo que necesita la cuenta de servicio. Por ejemplo, asigna el rol Lector de Artifact Registry a una cuenta de servicio que solo descargue artefactos.
- Si los grupos de tu organización requieren diferentes niveles de acceso a repositorios específicos, concede acceso a nivel de repositorio en lugar de a nivel de proyecto.
- Sigue las prácticas recomendadas para gestionar las credenciales.
Autenticarse con un asistente de credenciales
Artifact Registry proporciona un wagon de Maven y un plugin de Gradle como asistentes de credenciales. Cuando usas el asistente de credenciales, tus credenciales no se almacenan en tu proyecto de Java. En su lugar, Artifact Registry busca credenciales en el siguiente orden:
Credenciales predeterminadas de la aplicación (ADC), una estrategia que busca credenciales en el siguiente orden:
Credenciales definidas en la variable de entorno
GOOGLE_APPLICATION_CREDENTIALS
.Credenciales que proporciona la cuenta de servicio predeterminada de Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o las funciones de Cloud Run.
Credenciales proporcionadas por la CLI de Google Cloud, incluidas las credenciales de usuario del comando
gcloud auth application-default login
.
La variable GOOGLE_APPLICATION_CREDENTIALS
hace que la cuenta de autenticación sea explícita, lo que facilita la solución de problemas. Si no usas la variable, comprueba que las cuentas que pueda usar ADC tengan los permisos necesarios. Por ejemplo, la cuenta de servicio predeterminada de las VMs de Compute Engine, los nodos de Google Kubernetes Engine y las revisiones de Cloud Run tiene acceso de solo lectura a los repositorios. Si tienes intención de subir contenido desde estos entornos con la cuenta de servicio predeterminada, debes modificar los permisos.
Configurar una cuenta de servicio para un asistente de credenciales
Para crear una cuenta de servicio y configurar la autenticación mediante la variable de entorno, sigue estos pasos:
Crea una cuenta de servicio para que actúe en nombre de tu aplicación o elige una que ya tengas y que uses para la automatización.
Necesitarás la ubicación del archivo de clave de cuenta de servicio para configurar la autenticación con Artifact Registry. En el caso de las cuentas que ya tengas, puedes ver las claves y crear otras en la página Cuentas de servicio.
Concede el rol de Artifact Registry específico a la cuenta de servicio para proporcionar acceso al repositorio.
Asigna la ubicación del archivo de clave de cuenta de servicio a la variable
GOOGLE_APPLICATION_CREDENTIALS
para que el asistente de credenciales de Artifact Registry pueda obtener tu clave al conectarse con los repositorios.export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
Donde KEY-FILE es la ruta al archivo de clave de la cuenta de servicio.
Configurar Maven
Configura Maven para el tipo de repositorio que estés usando.
Estándar
Ejecuta el siguiente comando para imprimir la configuración del repositorio que se va a añadir a tu proyecto de Java.
gcloud artifacts print-settings mvn \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION
Dónde
- PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado actual.
- REPOSITORY es el ID del repositorio. Si has configurado un repositorio predeterminado de Artifact Registry, se usará cuando se omita esta marca en el comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
Añade los ajustes devueltos a las secciones correspondientes del archivo
pom.xml
de tu proyecto Maven. Consulta la referencia del POM de Maven para obtener más información sobre la estructura del archivo.En el siguiente ejemplo se muestra la configuración de un repositorio que almacena versiones de lanzamiento y de instantánea.
<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.5</version> </extension> </extensions> </build>
Los elementos
<release>
y<snapshot>
indican si el repositorio almacena paquetes de lanzamiento, paquetes de instantánea o ambos. Estos ajustes deben corresponderse con la política de versiones del repositorio.El elemento
<build>
define el wagon de Artifact Registry como una extensión. Para obtener información sobre el wagon, consulta la documentación de las herramientas Maven de Artifact Registry.
Remoto o virtual
Edita el archivo
pom.xml
de tu proyecto. Consulta la referencia del POM de Maven para obtener más información sobre la estructura del archivo.En el siguiente ejemplo se muestra la configuración de un repositorio remoto que almacena versiones de lanzamiento y de instantánea. En este ejemplo, el proyecto tiene una dependencia de una versión del paquete 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.5</version> </extension> </extensions> </build> </project>
En la sección
<repositories>
se define el repositorio de Artifact Registry. En el caso de un repositorio remoto, el elemento<id>
debe tener el valorcentral
. Este ajuste anula el valor predeterminado delcentral
ID de repositorio que se hereda del Super POM.La sección
<build>
define el wagon de Artifact Registry como una extensión. Para obtener información sobre el wagon, consulta la documentación de las herramientas Maven de Artifact Registry.En este ejemplo, la sección
<dependencies>
establece una dependencia de la versión28.0-jre
del paquete Guava.
Maven resuelve algunas dependencias antes de aplicar un transporte definido en
pom.xml
, entre las que se incluyen las siguientes:- Referencias en un proyecto secundario de Maven a un proyecto principal mediante el elemento
<parent>
. - Dependencias de complementos almacenadas en Artifact Registry.
Si tu proyecto necesita resolver estas dependencias, debes usar el mecanismo de extensiones principales para asegurarte de que Maven pueda localizar los archivos POM principales y los complementos.
En tu proyecto, crea el archivo
${maven.projectBasedir}/.mvn/extensions.xml
con el siguiente contenido. El elemento<extension>
define el vagón.<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.5</version> </extension> </extensions>
Ahora Maven puede resolver dependencias de elementos principales o de complementos desde Artifact Registry.
- Referencias en un proyecto secundario de Maven a un proyecto principal mediante el elemento
Se ha completado la configuración de la autenticación.
Configurar Gradle
Configura Gradle para el tipo de repositorio que estés usando.
Estándar
Ejecuta el siguiente comando para imprimir la configuración del repositorio que se va a añadir a tu proyecto de Java.
gcloud artifacts print-settings gradle \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION
Dónde
- PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado actual.
- REPOSITORY es el ID del repositorio. Si has configurado un repositorio predeterminado de Artifact Registry, se usará cuando se omita esta marca en el comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
Añade los ajustes del repositorio al archivo
build.gradle
. En el siguiente ejemplo se muestra la ubicación relativa de las secciones impresas.plugins { id "maven-publish" id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5" } 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 sección
plugins
declara el complemento Artifact Registry. Para obtener información sobre el complemento, consulta la documentación de las herramientas de Maven de Artifact Registry.La sección
publishing
define los archivos que se van a subir y el repositorio de Artifact Registry de destino. Puedes actualizar la lista de archivos en la secciónpublications
cuando quieras subir los archivos. Para obtener información sobre los ajustes de publicación, consulta la documentación del plugin Maven Publish.
Remoto o virtual
Añade los ajustes del repositorio al archivo
build.gradle
.En el siguiente ejemplo se muestra la configuración de un repositorio remoto. En este ejemplo, el proyecto tiene una dependencia de una versión del paquete Guava.
plugins { id 'java' id "maven-publish" id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5" 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 sección
plugins
declara el complemento Artifact Registry. Para obtener información sobre el complemento, consulta la documentación de las herramientas de Maven de Artifact Registry.En la sección
repositories
se define el repositorio de Artifact Registry.En este ejemplo, la sección
dependencies
establece una dependencia de la versión31.1-jre
del paquete Guava.
Define las dependencias de tu paquete en la sección
dependencies
.Si necesitas usar repositorios en tu archivo
init.gradle
osettings.gradle
, puedes añadir la configuración del complemento a esos archivos.En
init.gradle
, añade la siguiente configuración:initscript { repositories { maven { url "https://plugins.gradle.org/m2/" } } dependencies { classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.5" } } apply plugin: com.google.cloud.artifactregistry.gradle.plugin.ArtifactRegistryGradlePlugin
En settings.gradle, añade la siguiente configuración:
buildscript { repositories { maven { url "https://plugins.gradle.org/m2/" } } dependencies { classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.5" } } apply plugin: "com.google.cloud.artifactregistry.gradle-plugin"
Se ha completado la configuración de la autenticación.
Configurar la autenticación con contraseña
Usa este método cuando tu aplicación Java requiera autenticación con un nombre de usuario y una contraseña específicos.
Configurar una cuenta de servicio para la autenticación con contraseña
Para crear una cuenta de servicio, efectúa este procedimiento:
Crea una cuenta de servicio para que actúe en nombre de tu aplicación o elige una que ya tengas y que uses para la automatización.
Necesitarás la ubicación del archivo de clave de cuenta de servicio para configurar la autenticación con Artifact Registry. En el caso de las cuentas que ya tengas, puedes ver las claves y crear otras en la página Cuentas de servicio.
Si quieres activar la cuenta de servicio en la sesión actual de la CLI de gcloud, ejecuta el siguiente comando:
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
Dónde
- ACCOUNT es la cuenta de usuario o de servicio.
- KEY-FILE es la ruta al archivo JSON de la cuenta de servicio key file.
Configurar Maven
Configura Maven para el tipo de repositorio que estés usando.
Estándar
Ejecuta el siguiente comando para imprimir la configuración del repositorio que se va a añadir a tu proyecto de Java.
gcloud artifacts print-settings mvn \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION \ --json-key=KEY-FILE
Dónde
- PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado actual.
- REPOSITORY es el ID del repositorio. Si has configurado un repositorio predeterminado de Artifact Registry, se usará cuando se omita esta marca en el comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
- KEY-FILE es la ruta al archivo JSON de la cuenta de servicio key file.
El comando devuelve la configuración que debes incluir en tu proyecto Java, incluida una versión codificada en base64 de tu clave privada.
- Añada los ajustes del repositorio devuelto en el elemento
<project>
a las secciones correspondientes del archivopom.xml
de su proyecto Maven. Consulta la referencia del POM de Maven para obtener información sobre la estructura del archivo.
<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>
Los elementos
<release>
y<snapshot>
indican si el repositorio almacena paquetes de lanzamiento, paquetes de instantánea o ambos. Estos ajustes deben corresponderse con la política de versiones del repositorio.- Añade los ajustes de autenticación devueltos en el elemento
<settings>
a la sección<servers>
del archivo~/.m2/settings.xml
. En el siguiente ejemplo,KEY
es la clave codificada en Base64 de tu archivo de claves.
Para obtener más información, consulta la referencia de configuración de 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 virtual
Añade los ajustes del repositorio a las secciones correspondientes del archivo
pom.xml
de tu proyecto Maven. Consulta la referencia del POM de Maven para obtener más información sobre la estructura del archivo.<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>
En la sección
<repositories>
se define el repositorio de Artifact Registry. En el caso de un repositorio remoto, el elemento<id>
debe tener el valorcentral
. Este ajuste anula el valor predeterminado delcentral
ID de repositorio que se hereda del Super POM.Codifica tu archivo de claves en base64 con el siguiente comando. Sustituye KEY-FILE por el nombre de tu archivo de claves.
base64 -w 0 KEY-FILE
Añada los ajustes de autenticación en el elemento
<settings>
a la sección<servers>
del archivo~/.m2/settings.xml
.
Para obtener más información, consulta la referencia de configuración de 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>
- Si utilizas endpoints HTTP y quieres usar la conectividad nativa de Maven para autenticarte, puedes enviar un encabezado de autenticación mediante un encabezado HTTP personalizado en
settings.xml
.
Ejemplo:
<settings> <servers> <server> <id>artifact-registry</id> <configuration> <httpHeaders> <property> <name>Authorization </name> <value>Bearer ${artifact.registry.token}</value> </property> </httpHeaders> <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> </server> </servers> </settings>
Se ha completado la configuración de la autenticación.
Configurar Gradle
Configura Gradle para el tipo de repositorio que estés usando.
Estándar
Ejecuta el siguiente comando para imprimir la configuración del repositorio que se va a añadir a tu proyecto de Java.
gcloud artifacts print-settings gradle \ --project=PROJECT \ --repository=REPOSITORY \ --location=LOCATION \ --json-key=KEY-FILE
Dónde
- PROJECT es el ID del proyecto.
- REPOSITORY es el ID o el identificador completo del repositorio. Si ha configurado un repositorio de Artifact Registry predeterminado, se usará cuando se omita esta marca del comando.
- KEY-FILE es la ruta al archivo JSON de la cuenta de servicio key file. Si has ejecutado el comando para activar tu cuenta de servicio, puedes omitir esta marca.
El comando devuelve la configuración que debes incluir en tu proyecto Java, incluida una versión codificada en base64 de tu clave privada.
La siguiente línea de la configuración devuelta define una variable llamada
artifactRegistryMavenSecret
para la clave de tu cuenta de servicio. Añade esta línea a tu archivo~/.gradle/gradle.properties
para que la clave no se vea en tus compilaciones ni en tu repositorio de control de código fuente.artifactRegistryMavenSecret = KEY
En esta línea, KEY es la clave privada del archivo de clave de la cuenta de servicio. En el caso de
_json_key_base64
,artifactRegistryMavenSecret
se define como la clave codificada en base64 como contraseña.En
build.gradle
, especifique la configuración del repositorio: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) } } }
- En la sección
repositories
se definen la URL del repositorio y las credenciales para la autenticación. - La sección
publishing
define los archivos que se van a subir y el repositorio de Artifact Registry de destino. Puedes actualizar la lista de archivos en la secciónpublications
cuando quieras subir los archivos. Para obtener información sobre los ajustes de publicación, consulta la documentación del plugin Maven Publish.
- En la sección
Remoto o virtual
Codifica tu archivo de claves en base64 con el siguiente comando. Sustituye KEY-FILE por el nombre de tu archivo de claves.
base64 -w 0 KEY-FILE
En el archivo
~/.gradle/gradle.properties
, añade la siguiente línea para que tu clave no se vea en tus compilaciones ni en tu repositorio de control de código fuente.artifactRegistryMavenSecret = KEY
En esta línea, KEY es el contenido de tu archivo de clave codificado en Base64.
Añade los ajustes del repositorio al archivo
build.gradle
.
En el ejemplo siguiente se muestra la configuración de un repositorio 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" }
En la sección
repositories
se define el repositorio de Artifact Registry.En este ejemplo, la sección
dependencies
establece una dependencia de la versión31.1-jre
del paquete Guava.
Define las dependencias de tu paquete en la sección
dependencies
.
Se ha completado la configuración de la autenticación.