Envía y extrae imágenes

Enviar (subir) y extraer (descargar) imágenes son dos de las tareas más comunes de Container Registry. Este documento se centra en el envío y la extracción de 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 de todo el proyecto para crear buckets de almacenamiento.

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

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

  1. Verifica que tengas los permisos necesarios. Debes tener la función de administrador de almacenamiento (roles/storage.admin), una función personalizada o una función predefinida con los mismos permisos.

    Si quieres obtener instrucciones para otorgar la función de administrador de almacenamiento a nivel de proyecto, consulta la documentación de IAM.

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

    • Extrae la imagen busybox de Docker Hub
    • Etiqueta la imagen con su ruta de destino en Container Registry, incluido 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 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 al registro a otros usuarios.

Envía una imagen a un registro

Para enviar cualquier imagen local a Container Registry mediante 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, el token vence después de 60 minutos. Si esperas que el tiempo de carga supere los 60 minutos, usa un método de autenticación diferente.
Tamaño de la imagen
Container Registry usa Cloud Storage para el almacenamiento subyacente de 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 una de las siguientes funciones de Cloud Storage o una función con los mismos permisos:

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

Función: Administrador de almacenamiento (roles/storage.admin) a 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 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 de tu proyecto

Función: escritor de buckets heredados de almacenamiento (roles/storage.legacyBucketWriter) en el bucket de almacenamiento de registros

Esta función 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 la función de escritor de buckets heredados 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 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 para la 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 deseas 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

      La combinación del nombre de host, el proyecto y el nombre de la imagen de destino te brinda la ruta de acceso de la imagen completa que se debe usar 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 deseas 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 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 agrega la etiqueta latest predeterminada. Dado que latest es una etiqueta predeterminada, representa la versión de la imagen que se etiquetó más recientemente con la etiqueta latest, y no necesariamente la versión más reciente de una imagen.

Docker etiqueta la imagen con la etiqueta y el nombre de la imagen 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 del registro.

Para ver la imagen que enviaste, sigue estos pasos:

  • 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 Visualizador de objetos de Storage del bucket de almacenamiento del registro o una función 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 del 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?