Cambios para Docker

En este documento se explican las diferencias entre Container Registry y Artifact Registry para autenticar, insertar y extraer imágenes de contenedor con Docker.

En esta guía, las comparaciones se centran en los repositorios de pkg.devArtifact Registry, que son repositorios normales de Artifact Registry independientes de Container Registry y que admiten todas las funciones de Artifact Registry.

Si tu administrador ha configurado repositorios compatibles con el dominio gcr.io, las solicitudes a nombres de host gcr.io se redirigen automáticamente al repositorio de Artifact Registry correspondiente. Para usar un repositorio gcr.io alojado en Artifact Registry, debes tener un rol de Artifact Registry adecuado o un rol con permisos equivalentes.

Para obtener información sobre las diferencias entre Container Registry y Artifact Registry al compilar con Cloud Build y desplegar en Cloud Run o Google Kubernetes Engine, consulta Cambios en Cloud Build, Cloud Run y GKE.

Utiliza esta información para adaptar los comandos, la configuración o la documentación que ya tengas y que estén centrados en Container Registry con Docker.

Antes de empezar

En este documento se presupone que tienes lo siguiente:

1. Habilitar Artifact Registry en tu proyecto.
2. Docker instalado. Docker está incluido en Cloud Shell.

Información general

A grandes rasgos, el flujo de trabajo para usar Docker con Container Registry o Artifact Registry es el mismo.

Container Registry	Artifact Registry
Administrador Habilitar la API de Container Registry Añade un host de registro, como `gcr.io`, insertando una imagen inicial en el host. Concede roles de Cloud Storage en el segmento de almacenamiento del host del registro para proporcionar acceso a las imágenes.	Administrador Habilitar la API de Artifact Registry Añade un repositorio de Docker. Asigna roles de Artifact Registry para proporcionar acceso a las imágenes.
Usuarios del registro Define la imagen como un archivo Dockerfile. Crea la imagen. Autentícate en el registro. Etiqueta la imagen y envíala al registro. Extrae la imagen del registro o despliégala en un Google Cloud tiempo de ejecución.	Usuarios del registro Define la imagen como un archivo Dockerfile. Crea la imagen. Autentícate en el registro. Etiqueta la imagen y envíala al registro. Extrae la imagen del registro o despliégala en un Google Cloud tiempo de ejecución.

Sin embargo, un método abreviado para Container Registry consiste en combinar los roles de administrador y de usuario en un solo flujo de trabajo. Este atajo es habitual en:

• Guías de inicio rápido y tutoriales en los que se realizan pruebas en un entorno en el que tienes permisos amplios.
• Workflows que usan Cloud Build, ya que la cuenta de servicio de Cloud Build tiene permisos para añadir un host de registro en el mismo proyecto. Google Cloud

El flujo de trabajo de los accesos directos es el siguiente:

1. Habilita la API Container Registry.
2. Concede permisos a la cuenta que accederá a Container Registry.

3. Autentícate en el registro. La opción de autenticación más sencilla es usar el asistente de credenciales de Docker en la CLI de Google Cloud. Este paso de configuración solo se realiza una vez.

   gcloud auth configure-docker
   

4. Crea 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
   

5. 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 añade el host antes de subir la imagen.

6. Extrae la imagen del registro o despliégala en un Google Cloud tiempo de ejecución. Por ejemplo:

   docker pull gcr.io/my-project/my-image:tag1
   

Este flujo de trabajo se basa en las siguientes combinaciones de teclas:

• La cuenta que envía las imágenes tiene el rol Administrador de almacenamiento o un rol con los mismos permisos, como Propietario. Los amplios permisos de este rol permiten el acceso de lectura y escritura a todos los segmentos de almacenamiento de un proyecto, incluidos los segmentos que no utiliza Container Registry.
• Cuando habilitas algunas Google Cloud APIs, la API 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 añadir hosts de registro de forma predeterminada.

En Artifact Registry, los roles de administrador y de usuario del repositorio están claramente separados, lo que cambia los pasos del flujo de trabajo de compilación e implementación. Para adaptar el flujo de trabajo de Container Registry a Artifact Registry, haz los siguientes cambios. Cada paso incluye un enlace a información adicional sobre cómo modificar el flujo de trabajo.

1. Nuevo: habilite 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 la API automáticamente.

2. Nuevo: crea el repositorio de Docker de destino si aún no existe. Debes crear un repositorio para poder insertar imágenes en él. Al enviar una imagen no se puede activar la creación de un repositorio y la cuenta de servicio de Cloud Build no tiene permisos para crear repositorios.

3. Conceda permisos a la cuenta que interactuará con Artifact Registry.

4. Cambio: Autenticar en el repositorio. Si usas el asistente de credenciales en la CLI de gcloud, debes especificar los hosts que quieras añadir a la configuración de tu cliente de Docker. Por ejemplo, este comando añade el host us-central1-docker.pkg.dev:

   gcloud auth configure-docker us-central1-docker.pkg.dev
   

5. Cambiado: compila y etiqueta la imagen.

   El siguiente comando de ejemplo es el mismo que el del ejemplo de Container Registry, pero usa una ruta de repositorio de Artifact Registry para la imagen.

   docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

6. Cambiado: envía la imagen al repositorio mediante la ruta de Artifact Registry. Por ejemplo:

   docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

7. Cambiado: extrae la imagen del repositorio mediante la ruta de Artifact Registry. Por ejemplo:

   docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

Habilitar la API

Puntos clave:

• Además de la API de otros servicios de Google Cloud , como Cloud Build, Cloud Run y GKE, debes habilitar la API de Artifact Registry.

En la siguiente comparación se describe cómo habilitar la API de cada servicio:

Container Registry

Debes habilitar la API Container Registry antes de usar Docker u otros clientes de terceros con Container Registry.

Cuando habilitas las siguientes APIs Google Cloud , la API Container Registry también se habilita automáticamente:

• Entorno flexible de App Engine
• Cloud Build
• Cloud Run Functions
• Cloud Run
• Análisis de contenedores o análisis bajo demanda en Artifact Analysis
• Google Kubernetes Engine

Con los permisos predeterminados, los usuarios que pueden ejecutar compilaciones en Cloud Build, analizar contenedores con Artifact Analysis o desplegar contenedores enGoogle Cloud runtimes tienen acceso implícito a las imágenes de 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 u otros servicios de Google Cloud con Artifact Registry.

Servicios como Cloud Build, Cloud Run y GKE no habilitan automáticamente la API Artifact Registry.

Puedes habilitar varias APIs en el mismo proyecto con gcloud. Por ejemplo, para habilitar la API Cloud Build y la API Artifact Registry, ejecuta el siguiente comando:

gcloud services enable
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

Añadir registros y repositorios

Puntos clave:

• Debes crear un repositorio de Docker de Artifact Registry antes de enviar una imagen a él.

  A menudo, en la documentación que describe cómo enviar imágenes a Container Registry no se incluye el paso de creación del registro, ya que una cuenta con permisos de administrador de almacenamiento puede añadir 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 segmento de almacenamiento. En Artifact Registry, puede 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, puede añadir hasta cuatro hosts de registro a su proyecto. Para añadir un host de registro, envía la primera imagen.

1. Para añadir un registro como gcr.io a tu proyecto, una cuenta con el rol Administrador de Storage a nivel de proyecto envía una imagen inicial.

   Por ejemplo, si el host gcr.io no existe en el proyecto my-project, al enviar la imagen gcr.io/my-project/my-image:1.0 se activarán los siguientes pasos:

   1. Añade el gcr.io host al proyecto
   2. Crea un segmento de almacenamiento para gcr.io en el proyecto.
   3. Guarda la imagen como gcr.io/my-project/my-image:1.0

2. Después de esta primera inserción, puedes conceder permisos a otros usuarios para el contenedor de almacenamiento.

En un proyecto, un host de registro almacena todas las imágenes en el mismo segmento de almacenamiento. En el ejemplo siguiente, el proyecto my-project tiene dos imágenes llamadas web-app en el registro gcr.io. Una de ellas se encuentra 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 Administrador de repositorios de Artifact Registry debe crear el repositorio antes de que puedas insertar imágenes en él. Después, puedes conceder permisos al repositorio a otros usuarios.

En Artifact Registry, cada repositorio es un recurso independiente. Por lo tanto, todas las rutas de las imágenes deben incluir un repositorio.

Rutas 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 no se puede enviar una imagen a un repositorio que no existe.

• Envía una imagen a us-central1-docker.pkg.dev/my-project/team1 si us-central1-docker.pkg.dev/my-project/team1 no existe.
• Envía una imagen a us-central1-docker.pkg.dev/my-project/team2 cuando us-central1-docker.pkg.dev/my-project/team1 existe, pero us-central1-docker.pkg.dev/my-project/team2 no.

Concediendo permisos

Puntos clave:

• Concede el rol de Artifact Registry adecuado a la cuenta que vayas a usar con Artifact Registry.
• Los servicios deGoogle Cloud tienen acceso de lectura o escritura equivalente a Container Registry y Artifact Registry. Sin embargo, la cuenta de servicio de Cloud Build predeterminada no puede crear repositorios.
• Container Registry admite el control de acceso a nivel de segmento de almacenamiento. Artifact Registry admite el control de acceso a nivel de 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.

Lector de objetos de Storage a nivel de segmento de almacenamiento

Extraer (leer) imágenes de los hosts de registro del proyecto.

Editor de segmentos heredados de Storage a nivel de segmento de almacenamiento

Enviar (escribir) y extraer (leer) imágenes de hosts de registro del proyecto.

Administrador de Storage a nivel de proyecto

Añade un host de registro a un proyecto enviando una imagen inicial al host.

Después de enviar la imagen inicial a un registro, asigna roles de Cloud Storage a otras cuentas que necesiten acceder al segmento de almacenamiento. Ten en cuenta que cualquier cuenta con todos los permisos del rol Administrador de Storage puede leer, escribir y eliminar segmentos y objetos de almacenamiento en todo el proyecto.

Los permisos de un segmento de almacenamiento se aplican a todos los repositorios del registro. Por ejemplo, cualquier usuario con permisos de lector de objetos de Storage en el cubo 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 propias funciones para controlar el acceso. Estos roles proporcionan una separación clara entre los roles de administrador y de usuario del repositorio.

Solo las cuentas que gestionan repositorios deben tener el rol Administrador del repositorio de Artifact Registry o Administrador de Artifact Registry.

Lector de Artifact Registry

Lista de artefactos y repositorios. Descargar artefactos.

Escritor de Artifact Registry

Lista de artefactos y repositorios. Descargar artefactos, subir nuevas versiones de artefactos y añadir o actualizar etiquetas.

Administrador del repositorio de Artifact Registry

Permisos de escritura de Artifact Registry y permisos para eliminar artefactos y etiquetas.

Administrador de Artifact Registry

Permisos de administrador del repositorio de Artifact Registry y permisos para crear, actualizar, eliminar y conceder permisos a repositorios.

Puedes aplicar estos permisos a nivel de repositorio. Por ejemplo:

• Concede acceso al equipo 1 a us-central1-docker.pkg.dev/my-project/team1
• Concede acceso al equipo 2 a us-central1-docker.pkg.dev/my-project/team2.

Para obtener información sobre cómo conceder permisos de Artifact Registry, consulta la documentación sobre control de acceso.

Autenticarse en el registro

Puntos clave:

• Artifact Registry admite los mismos métodos de autenticación que Container Registry.
• En el caso del asistente de credenciales de Docker, debes especificar los hosts que quieras añadir a la configuración del cliente de Docker.
• Para la autenticación con docker login, usa el host de Artifact Registry en lugar del host de Container Registry.

Usar el asistente de credenciales

El comando gcloud auth configure-docker y el asistente de credenciales independiente solo configuran Docker para los nombres de host *.gcr.io de forma predeterminada. En Artifact Registry, debe especificar una lista de los hosts de Artifact Registry que quiera añadir a la configuración del cliente de Docker.

Por ejemplo, para configurar la autenticación en los repositorios de Docker de la región us-central1, ejecuta el siguiente comando:

gcloud auth configure-docker us-central1-docker.pkg.dev

Si más adelante añades repositorios en us-east1 y asia-east1, debes volver a ejecutar el comando para añadir 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

Para obtener más información sobre los métodos de autenticación de Artifact Registry, consulta el artículo Configurar la autenticación de Docker.

Usar la autenticación con contraseña

Cuando inicies sesión en 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 en el host us-central1-docker.pkg.dev:

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

Crear y etiquetar imágenes

Puntos clave: - Artifact Registry usa un nombre de host diferente para los repositorios.

Cuando etiquetes una imagen, usa la ruta de Artifact Registry en lugar de la ruta de Container Registry. Por ejemplo:

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Insertar imágenes en el registro

Puntos clave: - En Artifact Registry, el repositorio de destino debe existir antes de que envíes una imagen a él. - En Container Registry, el repositorio de destino se crea automáticamente cuando envías una imagen a él. - Artifact Registry usa un nombre de host diferente para los repositorios.

Cuando envíes una imagen, usa la ruta de Artifact Registry en lugar de la ruta de Container Registry. Por ejemplo:

docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Extraer 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 Artifact Registry en lugar de la ruta de Container Registry. Por ejemplo:

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Para ver ejemplos de cómo desplegar imágenes en Google Cloud runtimes como Cloud Run y GKE, consulta Desplegar imágenes.