Insertar y extraer imágenes

Insertar (subir) y extraer (descargar) imágenes son dos de las tareas más habituales de Container Registry. Este documento se centra en la inserción y 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 listar, etiquetar y eliminar imágenes, consulta Gestionar imágenes.

Antes de empezar

Asegúrate de que tienes lo siguiente:

1. Habilitar Container Registry en tu proyecto.

2. Docker instalado y configurado.

Añadir un registro

Puede añadir los siguientes registros de Container Registry a un proyecto:

La primera vez que se envía una imagen a un nombre de host, se crea el registro en un proyecto y el segmento de almacenamiento de Cloud Storage correspondiente. Este envío inicial requiere permisos en todo el proyecto para crear segmentos de almacenamiento.

Una vez que haya 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 añadir un registro y configurar los permisos, sigue estos pasos:

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

   Para obtener instrucciones sobre cómo asignar el rol Administrador de Storage a nivel de proyecto, consulta la documentación de IAM.

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

   • Extrae la imagen 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 añade el registro a tu proyecto, crea un segmento de almacenamiento para el registro y almacena la imagen.

Ahora puedes configurar el control de acceso en el contenedor de almacenamiento del registro para conceder acceso al registro a otros usuarios.

Enviar una imagen a un registro

Para insertar cualquier imagen local en Container Registry con Docker u otra herramienta de terceros, primero debes etiquetarla con el nombre del registro y, a continuación, insertar la imagen.

Los siguientes factores pueden influir en las subidas de imágenes grandes:

Hora de subida

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 mediante un token de acceso, el token caduca al cabo de 60 minutos. Si prevé que el tiempo de subida será superior a 60 minutos, utilice otro método de autenticación.

Tamaño de la imagen

Container Registry utiliza 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 de un objeto en el almacenamiento.

Container Registry no admite subidas fragmentadas de Docker. Algunas herramientas permiten subir imágenes de gran tamaño mediante subidas en fragmentos o con una sola subida monolítica. Debes usar cargas monolíticas para enviar imágenes a Container Registry.

Permisos obligatorios

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

Enviar la primera imagen a un registro de tu proyecto

Rol: Administrador de Storage (roles/storage.admin) en el Google Cloud nivel de proyecto. El rol de propietario predefinido 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 segmento de almacenamiento para el registro. El rol Administrador de almacenamiento tiene los permisos necesarios para crear el segmento de almacenamiento.

Enviar imágenes a un registro de tu proyecto

Rol: editor de segmentos heredados de Storage (roles/storage.legacyBucketWriter) en el segmento de almacenamiento del registro.

Este rol tiene permisos para insertar y extraer imágenes de los hosts de registro que ya existen en tu proyecto. Por ejemplo, si tu proyecto solo contiene el gcr.ioregistro, un usuario con el rol Escritor de cubos de almacenamiento antiguos puede enviar imágenes a gcr.io, pero no a asia.gcr.io.

Para obtener información sobre cómo conceder permisos a un registro, consulta Configurar 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 especifica la ubicación en la que se almacenará la imagen.

      • gcr.io aloja imágenes en centros de datos de 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 segmento 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 imágenes en centros de datos de Asia

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

      En la consola, el nombre de host de las imágenes se mostrará 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 puede llamarse web-image, pero quieres almacenarla en Container Registry como web-site.

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

      HOSTNAME/PROJECT-ID/TARGET-IMAGE
      

      Veamos un ejemplo:

      • Nombre de host: gcr.io
      • Google Cloud proyecto: 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, obtendrás la ruta de imagen completa que debes usar para etiquetar:

      gcr.io/my-project/web-site

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

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

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

   Haz los cambios siguientes:

   • SOURCE_IMAGE es el nombre de la imagen local o el ID de la imagen.
   • HOSTNAME es el host del registro que has elegido en el paso 2.
   • PROJECT es el Google Cloud ID del proyecto.
   • TARGET-IMAGE es el nombre de la imagen cuando se almacena en Container Registry.
   • TAG es la etiqueta que quieres asociar a 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 especifica ninguna etiqueta, Docker añade la etiqueta latest predeterminada. Como 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 la imagen con el nombre y la etiqueta que has especificado en el comando.

Enviar 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 omite :TAG, Docker inserta 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 segmento de almacenamiento para el host de registro.

Para ver la imagen que has enviado, sigue estos pasos:

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

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

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

  El resultado del comando es parecido al siguiente:

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

Extraer imágenes de un registro

Para extraer una imagen, se necesita el rol Visualizador de objetos de almacenamiento en el segmento de almacenamiento del registro o un rol con los mismos permisos.

Para extraer contenido de Container Registry, usa el siguiente comando:

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

o

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

donde:

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

Para obtener el comando pull de una imagen específica, haz lo siguiente:

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

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

3. En la parte superior de la página, haz clic en MOSTRAR COMANDO PULL.

4. Copia el comando pull, que identifica la imagen mediante la etiqueta o el digest.

Siguientes pasos

• Consulta información sobre cómo gestionar tus imágenes, como añadir o quitar etiquetas y eliminar imágenes.
• Consulta información sobre cómo configurar el control de acceso.
• Consulta más información sobre los componentes y las funciones de Container Registry.
• Si quieres ejecutar contenedores en Compute Engine, consulta información sobre los contenedores en Compute Engine.