Envía y extrae imágenes

Enviar (subir) y extraer (descargar) las imágenes son dos de las tareas más comunes de Container Registry. En este documento, se centra en enviar y extraer imágenes con Docker.

Si usas Cloud Build, consulta la documentación de Cloud Build para obtener información sobre cómo compilar y enviar contenedores a Container Registry.

Para obtener instrucciones sobre cómo generar listas, etiquetar y borrar imágenes, consulta Gestionar imágenes.

Antes de comenzar

Asegúrate de que se cumpla lo siguiente:

  1. Habilitaste Container Registry en tu proyecto.

  2. Instalaste y configuraste Docker.

Agrega un registro

Puedes agregar los siguientes registros de Container Registry a un proyecto:

Nombre de host Ubicación del almacenamiento
gcr.io Almacena imágenes en centros de datos en Estados Unidos
asia.gcr.io Almacena imágenes en centros de datos en Asia
eu.gcr.io Almacena imágenes en centros de datos dentro de los Estados miembros de la Unión Europea
us.gcr.io Almacena imágenes en centros de datos en Estados Unidos

El primer envío de imagen a un nombre de host activa la creación del registro en un proyecto y el bucket de almacenamiento de Cloud Storage correspondiente. Este envío inicial requiere permisos en todo el proyecto para crear buckets de almacenamiento.

Una vez que exista un host de registro en tu proyecto, podrás configurar permisos en el bucket de almacenamiento para controlar el acceso a las imágenes del registro.

Para agregar un registro y configurar los permisos, sigue estos pasos:

  1. Verifica que tengas los permisos necesarios. Debes tener el rol de administrador de almacenamiento (roles/storage.admin), un rol personalizado o un rol predefinido con los mismos permisos.

    Si deseas obtener instrucciones para otorgar el rol de administrador de almacenamiento a nivel del proyecto, consulta la documentación de IAM.

  2. Envía una imagen inicial al host. Por ejemplo, los siguientes comandos:

    • Extrae la imagen de busybox de Docker Hub
    • Etiqueta la imagen con su ruta de destino en Container Registry, incluido el host del registro gcr.io y el ID del proyecto.my-project
    • Envía la imagen al registro
    docker pull busybox
docker tag busybox gcr.io/my-project/busybox
docker push gcr.io/my-project/busybox

Container Registry agrega el registro a tu proyecto, crea un bucket de almacenamiento para el registro y almacena la imagen.

Ahora puedes configurar el control de acceso en el bucket de almacenamiento del registro para otorgar acceso a otros usuarios.

Envía una imagen a un registro

Para enviar cualquier imagen local a Container Registry con Docker o con otra herramienta de terceros, primero debes etiquetarla con el nombre del registro y, luego, enviarla.

Los siguientes factores pueden afectar las cargas de imágenes grandes:

Hora de carga
Todas las solicitudes que se envían a Container Registry tienen un límite de tiempo de espera de 2 horas. Si te autenticas en Container Registry con un token de acceso, este vence después de 60 minutos. Si crees que el tiempo de carga excederá los 60 minutos, usa otro método de autenticación.
Tamaño de la imagen
Container Registry usa Cloud Storage como almacenamiento subyacente para cada registro. Las cuotas y los límites de Cloud Storage se aplican a cada registro, incluido el tamaño máximo de 5 TB para un objeto en almacenamiento.
Container Registry no es compatible con las cargas fragmentadas de Docker. Algunas herramientas admiten la carga de imágenes grandes con cargas fragmentadas o una sola carga monolítica. Debes usar cargas monolíticas para enviar imágenes a Container Registry.

Permisos necesarios

Para enviar una imagen, se requiere uno de los siguientes roles de Cloud Storage o un rol con los mismos permisos:

Envía la primera imagen a un registro en tu proyecto

Rol: Administrador de almacenamiento (roles/storage.admin) a nivel del proyecto de Google Cloud El rol predefinido de propietario incluye estos permisos.

La primera vez que envías una imagen a un host de registro en tu proyecto (como gcr.io), Container Registry crea un bucket de almacenamiento para el registro. El rol de administrador de almacenamiento tiene los permisos necesarios para crear el bucket de almacenamiento.

Envía imágenes a un registro existente en tu proyecto.

Rol: Escritor de depósitos heredados de almacenamiento (roles/storage.legacyBucketWriter) en el bucket de almacenamiento del registro

Este rol tiene permisos para enviar y extraer imágenes de los hosts de registro existentes en tu proyecto. Por ejemplo, si tu proyecto solo contiene el registro gcr.io, un usuario con el rol de escritor de bucket heredado de almacenamiento puede enviar imágenes a gcr.io, pero no a asia.gcr.io.

Para obtener información sobre cómo otorgar permisos a un registro, consulta Configura el control de acceso.

Etiqueta la imagen local con el nombre del registro

Para etiquetar una imagen, sigue estos pasos:

  1. Verifica que hayas configurado la autenticación en Container Registry.

  2. Determina el nombre de la imagen en Container Registry:

    1. Elige un nombre de host que especifique la ubicación en la que almacenarás la imagen.

      • gcr.io aloja imágenes en centros de datos en los Estados Unidos, pero la ubicación puede cambiar en el futuro.
      • us.gcr.io aloja imágenes en centros de datos en los Estados Unidos, en un bucket de almacenamiento independiente de las imágenes alojadas por gcr.io.
      • eu.gcr.io aloja las imágenes en la Unión Europea.
      • asia.gcr.io aloja las imágenes en centros de datos en Asia.

      Estas ubicaciones corresponden a las multirregiones de los depósitos de almacenamiento de Cloud Storage. Cuando envías una imagen a un registro con un nombre de host nuevo, Container Registry crea un bucket de almacenamiento en la multirregión especificada. Este bucket es el almacenamiento subyacente del registro. Dentro de un proyecto, todos los registros con el mismo nombre de host comparten un bucket de almacenamiento.

      En la consola, el nombre de host de las imágenes aparecerá en Ubicación.

    2. Elige un nombre de imagen de destino, que puede ser diferente del nombre de la imagen en tu máquina local. Por ejemplo, la imagen local podría llamarse web-image, pero quieres almacenarla en Container Registry como web-site.

    3. Combina el nombre de host, el ID del proyecto de la consola de Google Cloud y el nombre de la imagen de destino:

      HOSTNAME/PROJECT-ID/TARGET-IMAGE

      Considera el siguiente ejemplo:

      • Nombre de host: gcr.io
      • Proyecto de Google Cloud: my-project
      • Nombre de la imagen de destino: web-site

      Si combinas el nombre de host, el proyecto y el nombre de la imagen de destino, obtienes la ruta de acceso completa de la imagen que se usará para etiquetar:

      gcr.io/my-project/web-site

      Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.

  3. Etiqueta la imagen local con el nombre del paso anterior. Si deseas etiquetar esta versión de la imagen, incluye el nombre de la etiqueta.

    docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG

    Reemplaza lo siguiente:

    • SOURCE_IMAGE es el nombre de la imagen local o el ID de la imagen.
    • HOSTNAME es el host de registro que elegiste en el paso 2.
    • PROJECT es el ID del proyecto de Google Cloud.
    • TARGET-IMAGE es el nombre de la imagen cuando se almacena en Container Registry.
    • TAG es la etiqueta que deseas asociar con esta versión de la imagen.

    Por ejemplo, este comando etiqueta la imagen local web-image como gcr.io/my-project/web-site en Container Registry con la etiqueta v1.5.

    docker tag web-image gcr.io/my-project/web-site:v1.5

    Si no especificas una etiqueta, Docker agregará la etiqueta predeterminada latest. Dado que latest es una etiqueta predeterminada, representa la versión de la imagen etiquetada más recientemente con la etiqueta latest y no necesariamente la versión más reciente de una imagen.

Docker etiqueta tu imagen con el nombre y la etiqueta que especificaste en el comando.

Envía la imagen etiquetada a Container Registry

  1. Verifica que hayas configurado la autenticación en Container Registry.

  2. Envía la imagen etiquetada a Container Registry:

    Ejecuta el siguiente comando para enviar una imagen con una etiqueta específica:

    docker push HOSTNAME/PROJECT-ID/IMAGE:TAG

    Si omites :TAG, Docker envía la versión de la imagen etiquetada con latest.

    Por ejemplo, este comando envía la imagen gcr.io/my-project/web-site con la etiqueta v1.5:

    docker push gcr.io/my-project/web-site:v1.5

Cuando envías una imagen a un host de registro que aún no existe en tu proyecto, Container Registry crea un bucket de almacenamiento para el host de registro.

Para ver la imagen que enviaste, haz lo siguiente:

  • Ve a la consola de Google Cloud para ver el registro y la imagen.

  • Ejecuta gcloud container images list-tags para ver la etiqueta de la imagen y el resumen generado automáticamente:

    gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE

    El resultado del comando es similar al siguiente:

    DIGEST        TAGS        TIMESTAMP
44bde...      test        2017-..-..

Extrae las imágenes de un registro

Para extraer una imagen, se requiere el rol de visualizador de objetos de almacenamiento para el bucket de almacenamiento de registro o un rol con los mismos permisos.

Para extraer imágenes desde Container Registry, usa el siguiente comando:

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

o

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

donde:

  • HOSTNAME aparece en Ubicación en la consola. Es una de estas cuatro opciones: gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.
  • PROJECT-ID es el ID de tu proyecto de la consola de Google Cloud. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
  • IMAGE es el nombre de la imagen en Container Registry.
  • TAG es la etiqueta que se aplica a la imagen. En un registro, las etiquetas son exclusivas de una imagen.
  • IMAGE_DIGEST es el valor de hash sha256 del contenido de la imagen. En la consola de Google Cloud, haz clic en la imagen específica para ver sus metadatos. El resumen se muestra como el resumen de la imagen.

Haz lo siguiente para obtener el comando de extracción de una imagen específica:

  1. Haz clic en el nombre de una imagen para ir al registro específico.

  2. En el registro, marca la casilla junto a la versión de la imagen que deseas extraer.

  3. Haz clic en MOSTRAR COMANDO DE EXTRACCIÓN en la parte superior de la página.

  4. Copia el comando de extracción, que identifica la imagen mediante la etiqueta o el resumen.

¿Qué sigue?