En este documento, se explican las diferencias entre Container Registry y Artifact Registry para autenticar, enviar y extraer imágenes de contenedores con Docker.
En esta guía, las comparaciones se centran en los repositorios de pkg.dev
Artifact Registry, los repositorios normales de Artifact Registry que son independientes de Container Registry y admiten todas las funciones de Artifact Registry.
Si tu administrador configuró repositorios con compatibilidad con dominios gcr.io, las solicitudes a los nombres de host gcr.io
se redireccionan automáticamente a un repositorio de Artifact Registry correspondiente. Para usar un repositorio de gcr.io alojado en
Artifact Registry, debes tener un
rol de Artifact Registry apropiado o un rol con
permisos equivalentes.
Para obtener información sobre las diferencias entre Container Registry y Artifact Registry cuando se compila con Cloud Build y se implementa en Cloud Run o Google Kubernetes Engine, consulta Cambios en Cloud Build, Cloud Run y GKE.
Usa esta información para adaptar los comandos, la configuración o la documentación existentes que se centren en Container Registry con Docker.
Antes de comenzar
En este documento, se supone que ya tienes lo siguiente:
- Habilitaste Artifact Registry en tu proyecto.
- Docker está instalado. Docker está incluido en Cloud Shell.
Descripción general
En términos generales, el flujo de trabajo para usar Docker con Container Registry o Artifact Registry es el mismo.
Container Registry | Artifact Registry |
---|---|
Administrador
|
Administrador
|
Usuarios del registro
|
Usuarios del registro
|
Sin embargo, un atajo para Container Registry es combinar los roles de administrador y usuario en un solo flujo de trabajo. Este atajo es común en los siguientes casos:
- Instructivos y guías de inicio rápido en los que realizas pruebas en un entorno en el que tienes permisos amplios
- Flujos de trabajo que usan Cloud Build, ya que la cuenta de servicio de Cloud Build tiene permisos para agregar un host de registro en el mismo Google Cloud proyecto.
El flujo de trabajo del atajo se ve de la siguiente manera:
- Habilita la API de Container Registry.
- Otorga permisos a la cuenta que accederá a Container Registry.
Realiza la autenticación en el registro. La opción de autenticación más sencilla es usar el auxiliar de credenciales de Docker en Google Cloud CLI. Este es un paso de configuración que solo deberás realizar una vez.
gcloud auth configure-docker
Compila y etiqueta la imagen. Por ejemplo, este comando compila y etiqueta la imagen
gcr.io/my-project/my-image:tag1
:docker build -t gcr.io/my-project/my-image:tag1
Envía la imagen al registro. Por ejemplo:
docker push gcr.io/my-project/my-image:tag1
Si el host de registro
gcr.io
no existe en el proyecto, Container Registry lo agrega antes de subir la imagen.Extrae la imagen del registro o impleméntala en un entorno de ejecución Google Cloud . Por ejemplo:
docker pull gcr.io/my-project/my-image:tag1
Este flujo de trabajo se basa en los siguientes atajos:
- La cuenta que envía imágenes tiene el rol de Administrador de almacenamiento o un rol con los mismos permisos, como Propietario. Los permisos amplios de este rol permiten el acceso de lectura y escritura a todos los buckets de almacenamiento de un proyecto, incluidos los que no usa Container Registry.
- Cuando habilitas algunas APIs Google Cloud, la API de Container Registry se habilita automáticamente. Esto significa que los usuarios de estos servicios tienen acceso implícito a Container Registry en el mismo proyecto. Por ejemplo, los usuarios que pueden ejecutar compilaciones en Cloud Build pueden enviar imágenes a registros y agregar hosts de registro de forma predeterminada.
En Artifact Registry, hay una clara separación de los roles de usuario de administrador y del repositorio que cambia los pasos del flujo de trabajo de compilación y, luego, de implementación. Para adaptar el flujo de trabajo de Container Registry a Artifact Registry, realiza los siguientes cambios. Cada paso incluye vínculos a información adicional para modificar el flujo de trabajo.
Nuevo: Habilita la API de Artifact Registry.
Debes habilitar la API de Artifact Registry. Cloud Build y los entornos de ejecución, como Cloud Run y GKE, no habilitan automáticamente la API por ti.
Nuevo: Crea el repositorio de Docker de destino si aún no existe. Debes crear un repositorio para poder enviarle imágenes. El envío de una imagen no activa la creación de un repositorio y la cuenta de servicio de Cloud Build no tiene permisos para crear repositorios.
Otorga permisos a la cuenta que interactuará con Artifact Registry.
Cambio: Realiza la autenticación en el repositorio. Si usas el ayudante de credenciales en gcloud CLI, debes especificar los hosts que deseas agregar a la configuración de tu cliente de Docker. Por ejemplo, este comando agrega el host
us-central1-docker.pkg.dev
:gcloud auth configure-docker us-central1-docker.pkg.dev
Cambió: Compila y etiqueta la imagen.
El siguiente comando de ejemplo es el mismo que el de Container Registry, pero usa una ruta de acceso del repositorio de Artifact Registry para la imagen.
docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Cambió: Envía la imagen al repositorio con la ruta de acceso de Artifact Registry. Por ejemplo:
docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Cambio: Extrae la imagen del repositorio con la ruta de acceso de Artifact Registry. Por ejemplo:
docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Habilitar la API
Puntos clave:
- Debes habilitar la API de Artifact Registry además de la API de otros Google Cloud servicios, como Cloud Build, Cloud Run y GKE.
En la siguiente comparación, se describe cómo habilitar la API para cada servicio:
Container Registry
Debes habilitar la API de Container Registry antes de usar Docker o cualquier otro cliente de terceros con Container Registry.
Cuando habilitas las siguientes APIs de Google Cloud , la API de Container Registry también se habilita automáticamente:
- Entorno flexible de App Engine
- Cloud Build
- Funciones de Cloud Run
- Cloud Run
- Análisis de contenedores o análisis a pedido en Artifact Analysis
- Google Kubernetes Engine
Con los permisos predeterminados, los usuarios que pueden ejecutar compilaciones en Cloud Build, scanear contenedores con Artifact Analysis o implementar contenedores en entornos de ejecución deGoogle Cloud tienen acceso implícito a las imágenes en Container Registry cuando el registro está en el mismo proyecto.
Artifact Registry
Debes habilitar la API de Artifact Registry antes de usar clientes de Docker o otros Google Cloud servicios con Artifact Registry.
Servicios como Cloud Build, Cloud Run y GKE no habilitan automáticamente la API de Artifact Registry.
Puedes habilitar varias APIs en el mismo proyecto con gcloud. Por ejemplo, para habilitar la API de Cloud Build y la API de Artifact Registry, ejecuta el siguiente comando:
gcloud services enable
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Cómo agregar registros y repositorios
Puntos clave:
Debes crear un repositorio de Docker de Artifact Registry antes de enviarle una imagen.
A menudo, se excluye un paso de creación de registro en la documentación que describe el envío de imágenes a Container Registry, ya que una cuenta con permisos de administrador de almacenamiento puede agregar un registro a un proyecto con el envío inicial al host del registro.
Container Registry almacena todas las imágenes en una sola multirregión en el mismo bucket de almacenamiento. En Artifact Registry, puedes crear varios repositorios en la misma región o en varias regiones con políticas de acceso independientes.
En la siguiente comparación, se describe la configuración del repositorio en cada servicio:
Container Registry
En Container Registry, puedes agregar hasta cuatro hosts de registro a tu proyecto. Para agregar un host de registro, envía la primera imagen.
Para agregar un registro como
gcr.io
a tu proyecto, una cuenta con el rol de administrador de almacenamiento a nivel del proyecto envía una imagen inicial.Por ejemplo, si el host
gcr.io
no existe en el proyectomy-project
, enviar la imagengcr.io/my-project/my-image:1.0
activa los siguientes pasos:- Agrega el host
gcr.io
al proyecto - Crea un bucket de almacenamiento para
gcr.io
en el proyecto. - Almacena la imagen como
gcr.io/my-project/my-image:1.0
- Agrega el host
Después de esta publicación inicial, puedes otorgar permisos al bucket de almacenamiento para otros usuarios.
Dentro de un proyecto, un host de registro almacena todas las imágenes en el mismo bucket de almacenamiento. En el siguiente ejemplo, el proyecto my-project
tiene dos imágenes llamadas web-app
en el registro gcr.io
. Uno está directamente debajo del ID del proyecto my-project
. La otra imagen está en el repositorio team1
.
gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app
Artifact Registry
Una cuenta con el rol de administrador del repositorio de Artifact Registry debe crear el repositorio antes de enviarle imágenes. Luego, puedes otorgar permisos al repositorio para otros usuarios.
En Artifact Registry, cada repositorio es un recurso independiente. Por lo tanto, todas las rutas de acceso a las imágenes deben incluir un repositorio.
Rutas de acceso de imágenes válidas:
us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0
Ruta de imagen no válida (no incluye un repositorio) :
us-central1-docker.pkg.dev/my-project/web-app:1.0
En los siguientes ejemplos, se muestran situaciones en las que falla el envío de una imagen a un repositorio que no está disponible.
- Envía una imagen a
us-central1-docker.pkg.dev/my-project/team1
sius-central1-docker.pkg.dev/my-project/team1
no existe. - Envía una imagen a
us-central1-docker.pkg.dev/my-project/team2
cuando existeus-central1-docker.pkg.dev/my-project/team1
, pero no existeus-central1-docker.pkg.dev/my-project/team2
.
Otorgando permisos
Puntos clave:
- Otorga el rol de Artifact Registry adecuado a la cuenta que usas con Artifact Registry.
- Los servicios deGoogle Cloud tienen acceso de lectura o escritura equivalente a Artifact Registry y Container Registry. Sin embargo, la cuenta de servicio predeterminada de Cloud Build no puede crear repositorios.
- Container Registry admite el control de acceso a nivel del bucket de almacenamiento. Artifact Registry admite el control de acceso a nivel del repositorio.
En la siguiente comparación, se describe la configuración de permisos en cada servicio:
Container Registry
Container Registry usa los roles de Cloud Storage para controlar el acceso.
- Visualizador de objetos de almacenamiento a nivel del bucket de almacenamiento
- Extrae (lee) imágenes de los hosts de registro existentes en el proyecto.
- Escritor de depósitos heredados de Storage a nivel del bucket de almacenamiento
- Envía (escribe) y extrae (lee) imágenes para los hosts de registro existentes en el proyecto.
- Administrador de almacenamiento a nivel del proyecto
- Envía una imagen inicial al host para agregar un host de registro a un proyecto.
Después del envío inicial de la imagen a un registro, otorgas roles de Cloud Storage a otras cuentas que requieren acceso al bucket de almacenamiento. Ten en cuenta que cualquier cuenta con todos los permisos del rol de administrador de almacenamiento puede leer, escribir y borrar buckets y objetos de almacenamiento en todo el proyecto.
Los permisos de un bucket de almacenamiento se aplican a todos los repositorios del registro.
Por ejemplo, cualquier usuario con permisos de Visualizador de objetos de almacenamiento en el bucket de gcr.io/my-project
puede leer imágenes en todos estos repositorios:
gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production
Artifact Registry
Artifact Registry tiene sus propios roles para controlar el acceso. Estos roles proporcionan una separación clara entre los roles de usuario del administrador y del repositorio.
Solo las cuentas que administran repositorios deben tener el rol de Administrador del repositorio de Artifact Registry o de Administrador de Artifact Registry.
- Lector de Artifact Registry
- Enumera artefactos y repositorios. Descarga artefactos.
- Escritor de Artifact Registry
- Enumera artefactos y repositorios. Descarga artefactos, sube versiones de artefactos nuevas y agrega o actualiza etiquetas.
- Administrador del repositorio de Artifact Registry
- Permisos de escritor de Artifact Registry y permisos para borrar artefactos y etiquetas.
- Administrador de Artifact Registry
- Permisos del administrador del repositorio de Artifact Registry y permisos para crear, actualizar, borrar y otorgar permisos a los repositorios.
Puedes aplicar estos permisos a nivel del repositorio. Por ejemplo:
- Otorga acceso al equipo 1 para
us-central1-docker.pkg.dev/my-project/team1
- Otorgar acceso a
us-central1-docker.pkg.dev/my-project/team2
al equipo 2
Para obtener detalles sobre cómo otorgar permisos de Artifact Registry, consulta la documentación sobre control de acceso.
Realiza la autenticación en el registro
Puntos clave:
- Artifact Registry admite los mismos métodos de autenticación que Container Registry.
- Para el auxiliar de credenciales de Docker, debes especificar los hosts que deseas agregar a la configuración del cliente de Docker.
- Para la autenticación con
docker login
, usa el host de Artifact Registry en lugar de un host de Container Registry.
Usa el auxiliar de credenciales
El comando gcloud auth configure-docker
y el auxiliar de credenciales independiente solo configuran Docker para nombres de host *.gcr.io
de forma predeterminada. Para Artifact Registry, debes especificar una lista de los hosts de Artifact Registry que deseas agregar a la configuración del cliente de Docker.
Por ejemplo, para configurar la autenticación en los repositorios de Docker en la región us-central1
, ejecuta el siguiente comando:
gcloud auth configure-docker us-central1-docker.pkg.dev
Si más adelante agregas repositorios en us-east1
y asia-east1
, debes volver a ejecutar
el comando para agregar los nombres de host regionales correspondientes a tu
configuración de Docker.
gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev
Si quieres obtener detalles sobre los métodos de autenticación de Artifact Registry, consulta Configura la autenticación para Docker.
Cómo usar la autenticación con contraseña
Cuando accedas a Docker, usa el nombre de host de Artifact Registry en lugar de un nombre de host *.gcr.io
. En el siguiente ejemplo, se muestra la autenticación con una clave de cuenta de servicio codificada en Base64 al host us-central1-docker.pkg.dev
:
cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev
Compila y etiqueta imágenes
Puntos clave: - Artifact Registry usa un nombre de host diferente para los repositorios.
Cuando etiquetes una imagen, usa la ruta de acceso de Artifact Registry en lugar de la ruta de acceso de Container Registry. Por ejemplo:
docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Envía imágenes al registro
Puntos clave: - En Artifact Registry, el repositorio de destino debe existir antes de enviarle una imagen. - Artifact Registry usa un nombre de host diferente para los repositorios.
Cuando envíes una imagen, usa la ruta de acceso de Artifact Registry en lugar de la ruta de acceso de Container Registry. Por ejemplo:
docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Extrae imágenes del registro
Punto clave:
- Los nombres de host de Artifact Registry son diferentes de los de Container Registry.
Cuando extraigas una imagen, usa la ruta de acceso de Artifact Registry en lugar de la ruta de acceso de Container Registry. Por ejemplo:
docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Para ver ejemplos de la implementación de imágenes en Google Cloud entorno de ejecución, como Cloud Run y GKE, consulta Implementa imágenes.