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. Este documento se enfoca en enviar y extraer imágenes con Docker.

Si usas Cloud Build, consulta la Documentación de Cloud Build para obtener información sobre la compilación y el envío de 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 imágenes 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 la ruta de destino en Container Registry, incluidas las siguientes: el host de 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 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 Un método de autenticación diferente
Tamaño de la imagen
Container Registry usa Cloud Storage para cada registro del almacenamiento subyacente. Cuotas y límites de Cloud Storage se aplican a cada registro, incluido el tamaño máximo de 5 TB para un objeto en y almacenamiento de los datos.
Container Registry no admite cargas fragmentadas de Docker. Algunas herramientas admiten la carga de imágenes grandes con cargas fragmentadas o una 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 una de las siguientes opciones: Roles de Cloud Storage o un rol con los mismos permisos:

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

Rol: Administrador de almacenamiento (roles/storage.admin) en Nivel de 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 de tu proyecto (como gcr.io), Container Registry crea un bucket de almacenamiento para la registro. El rol Administrador de almacenamiento tiene los permisos necesarios para crear en el bucket de almacenamiento.

Envía imágenes a un registro existente de 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 gcr.io de registro, un usuario con el rol Escritor de buckets heredados de almacenamiento puede enviar imágenes a gcr.io, pero no puede enviar imágenes 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 de 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 almacenarlo 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

      Combinar el nombre de host, el proyecto y el nombre de la imagen de destino proporciona la ruta de acceso a la imagen completa para el etiquetado:

      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 quieres etiquetar esta versión de la imagen con una etiqueta, 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 de la siguiente manera: 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 si configuraste la autenticación para 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 enviará la versión de la imagen. etiquetado 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 Container Registry crea un bucket de almacenamiento para el host del registro.

Para ver la imagen que enviaste, sigue estos pasos:

  • Ve a la consola de Google Cloud para ver registro e 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, necesitas Visualizador de objetos de Storage 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 tu consola de Google Cloud ID del proyecto: 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?