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:
Habilitaste Container Registry en tu proyecto.
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:
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.
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 proyectomy-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
- Extrae la imagen
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 agcr.io
, pero no aasia.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:
- Verifica que hayas configurado la autenticación en Container Registry.
Determina el nombre de la imagen en Container Registry:
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 porgcr.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.
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 comoweb-site
.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.- Nombre de host:
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
comogcr.io/my-project/web-site
en Container Registry con la etiquetav1.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 quelatest
es una etiqueta predeterminada, representa la versión de la imagen que se etiquetó más recientemente con la etiquetalatest
, 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
Verifica que hayas configurado la autenticación en Container Registry.
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 conlatest
.Por ejemplo, este comando envía la imagen
gcr.io/my-project/web-site
con la etiquetav1.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
oasia.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:
Haz clic en el nombre de una imagen para ir al registro específico.
En el registro, marca la casilla junto a la versión de la imagen que deseas extraer.
Haz clic en MOSTRAR COMANDO DE EXTRACCIÓN en la parte superior de la página.
Copia el comando de extracción, que identifica la imagen mediante la etiqueta o el resumen.
¿Qué sigue?
- Obtén información sobre cómo administrar tus imágenes, incluido como agregar o quitar etiquetas y borrar imágenes.
- Obtén más información sobre cómo configurar el control de acceso.
- Obtén más información acerca de los componentes y las funciones de Container Registry.
- Si deseas ejecutar contenedores en Compute Engine, obtén más información sobre contenedores en Compute Engine.