Si usas Container Registry para administrar tus imágenes de contenedor, en esta página se explica cómo configurar un repositorio de Artifact Registry de pkg.dev y cómo se diferencia el uso de repositorios del uso de Container Registry.
Estas instrucciones son principalmente para administradores de repositorios. Para obtener información sobre cómo cambiaron la compilación, el envío, la extracción y la implementación de imágenes, consulta la siguiente información:
- Cambios en la compilación y la implementación en Google Cloud
- Cambios en el envío y la extracción con Docker
Antes de comenzar
Habilita la API de Artifact Registry desde la consola de Google Cloud o con el siguiente comando:
gcloud services enable artifactregistry.googleapis.comInstala gcloud CLI si aún no lo hiciste. Para una instalación existente, ejecuta el siguiente comando para actualizar los componentes a las versiones más recientes:
gcloud components updateObtén información sobre los precios de Artifact Registry antes de comenzar la transición.
Roles obligatorios
Para obtener los permisos que necesitas para configurar repositorios de gcr.io, pídele a tu administrador que te otorgue los siguientes roles de IAM en el Google Cloud proyecto:
-
Para crear repositorios de Artifact Registry y otorgar acceso a repositorios individuales, haz lo siguiente:
Administrador de Artifact Registry (
roles/artifactregistry.admin) -
Para ver y administrar la configuración existente de Container Registry aplicada a los buckets de almacenamiento de Cloud Storage, sigue estos pasos:
Administrador de almacenamiento (
roles/storage.admin) -
Para otorgar acceso al repositorio a nivel del proyecto, debes tener el rol de administrador de IAM del proyecto (
roles/resourcemanager.projectIamAdmin) o un rol que incluya permisos equivalentes, como administrador de carpetas (roles/resourcemanager.folderAdmin) o administrador de organización (roles/resourcemanager.organizationAdmin).
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.
Descripción general
Los repositorios de pkg.dev son repositorios normales de Artifact Registry que admiten todas las funciones.
Para mayor simplicidad, en las instrucciones de esta página, se supone que Container Registry y Artifact Registry están en el mismo proyecto de Google Cloud . Puedes seguir usando ambos servicios mientras te trasladas a Artifact Registry, de forma que puedas realizar los pasos de configuración de forma gradual y actualizar tu automatización. Si es necesario, puedes configurar Artifact Registry en un proyecto independiente y realizar los mismos pasos generales.
Artifact Registry también ofrece repositorios de gcr.io.
Estos repositorios pueden redireccionar el tráfico de gcr.io de tus registros existentes
a los repositorios de Artifact Registry correspondientes. Proporcionan cierta compatibilidad con versiones anteriores de Container Registry, pero también tienen algunas limitaciones de funciones. Sin embargo, si tienes mucha configuración de herramientas, secuencias de comandos o código con referencias de gcr.io, es posible que se requiera un enfoque más táctico para realizar la transición a Artifact Registry. Revisa la documentación de transición para los repositorios con compatibilidad con dominios gcr.io para tomar una decisión adecuada.
Pasos para la transición
En esta guía, se muestra cómo completar los siguientes pasos:
- Crea un repositorio de Docker para tus contenedores. Debes crear un repositorio para poder enviar imágenes a este.
- Otorga permisos al repositorio.
- Configura la autenticación para que puedas conectarte con tu repositorio nuevo.
- Si es necesario, copia las imágenes de Container Registry que desees usar en tu repositorio nuevo.
- Intenta enviar y extraer tus contenedores.
- Intenta implementar tus imágenes en un entorno de ejecución.
- Configura las funciones adicionales.
- Limpia las imágenes en Container Registry cuando se complete la transición.
Crea repositorios
Container Registry crea automáticamente un bucket de almacenamiento en una multirregión si no enviaste una imagen allí antes.
En Artifact Registry, debes crear un repositorio antes de poder subir imágenes. Cuando creas un repositorio, debes especificar lo siguiente:
- El formato del repositorio. Artifact Registry almacena contenedores en repositorios de Docker.
Una ubicación regional o multirregional para el repositorio.
Cuando elijas una ubicación para tus repositorios de Artifact Registry, ten en cuenta la proximidad de los repositorios con tu otra infraestructura y tus usuarios. Si planeas copiar imágenes de Container Registry a Artifact Registry, las diferencias en la ubicación pueden afectar el costo de copia.
Una clave de Cloud Key Management Service, si usas claves de encriptación administradas por el cliente (CMEK) para la encriptación.
En Container Registry, configuras el bucket de almacenamiento de Container Registry para usar CMEK. En Artifact Registry, configuras los repositorios para que usen CMEK cuando los creas. Para obtener más información sobre el uso de CMEK con Artifact Registry, consulta Cómo habilitar claves de encriptación administradas por el cliente.
Container Registry aloja contenedores en el dominio gcr.io.
Artifact Registry aloja contenedores en el dominio pkg.dev.
Si deseas obtener más información sobre cómo crear repositorios, incluidos los que usan CMEK para la encriptación, consulta Crea repositorios.
Otorgar permisos
Container Registry usa roles de Cloud Storage para controlar el acceso. Artifact Registry tiene sus propios roles de IAM, y estos roles separan los roles de administración de lectura, escritura y repositorio de forma más clara que Container Registry.
Para asignar rápidamente los permisos existentes otorgados en los buckets de almacenamiento a los roles sugeridos de Artifact Registry, usa la herramienta de asignación de roles.
Como alternativa, puedes ver una lista de principales con acceso a los buckets de almacenamiento con la consola de Google Cloud.
- En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.
Haz clic en el bucket de almacenamiento del host de registro que deseas ver. En los nombres de los buckets,
PROJECT-IDes tu Google Cloud ID de proyecto.- gcr.io:
artifacts.PROJECT-ID.appspot.com - asia.gcr.io:
asia.artifacts.PROJECT-ID.appspot.com - eu.gcr.io:
eu.artifacts.PROJECT-ID.appspot.com - us.gcr.io:
us.artifacts.PROJECT-ID.appspot.com
- gcr.io:
Haz clic en la pestaña Permisos.
En la pestaña Permisos, haz clic en la subpestaña Ver por rol.
Expande un rol para ver los principales que tienen ese rol.
La lista incluye los roles de IAM otorgados directamente en el bucket y los roles heredados del proyecto superior. Según el rol, puedes elegir el rol de Artifact Registry más adecuado para otorgar.
- Cloud Storage y roles básicos
Otorga a los usuarios y a las cuentas de servicio que actualmente acceden a Container Registry acceso a los repositorios de Artifact Registry. En el caso de los roles de Cloud Storage que se heredan del proyecto superior, debes verificar que el principal use actualmente Container Registry. Es posible que algunos principales solo accedan a otros buckets de Cloud Storage que no estén relacionados con Container Registry.
Los roles básicos Propietario, Editor y Visualizador que existían antes de IAM tienen acceso limitado a los buckets de almacenamiento. No otorgan de forma intrínseca todo el acceso a los recursos de Cloud Storage que implican sus nombres y proporcionan permisos adicionales para otros Google Cloud servicios. Verifica qué usuarios y cuentas de servicio requieren acceso a Artifact Registry y usa la tabla de asignación de roles para otorgar los roles correctos si el acceso a Artifact Registry es adecuado.
En la siguiente tabla, se asignan los roles de Artifact Registry según los permisos otorgados por los roles predefinidos de Cloud Storage para el acceso a Container Registry. Los roles de Artifact Registry proporcionan una separación adicional de permisos que no está disponible en los roles predefinidos de Cloud Storage.
Acceso obligatorio Rol actual Rol de Artifact Registry Dónde otorgar el rol Extraer solo imágenes (solo lectura) Visualizador de objetos de almacenamiento
(roles/storage.objectViewer)Lector de Artifact Registry
(roles/artifactregistry.reader)Repositorio o Google Cloud proyecto de Artifact Registry Envía y extrae imágenes (lectura y escritura) Escritor de buckets heredados de almacenamiento
(roles/storage.legacyBucketWriter)Escritor de Artifact Registry
(roles/artifactregistry.writer)Repositorio o Google Cloud proyecto de Artifact Registry Envía, extrae y borra imágenes Escritor de buckets heredados de almacenamiento
(roles/storage.legacyBucketWriter)Administrador de repositorio de Artifact Registry
(roles/artifactregistry.repoAdmin)Repositorio o Google Cloud proyecto de Artifact Registry Crea, administra y borra repositorios Administrador de almacenamiento
(roles/storage.admin)Administrador de Artifact Registry
(roles/artifactregistry.Admin)Google Cloud proyecto - Roles del agente de servicio heredados del proyecto
Las cuentas de servicio predeterminadas para los servicios de Google Cloud tienen sus propios roles otorgados a nivel del proyecto. Por ejemplo, el agente de servicio de Cloud Run tiene el rol de agente de servicio de Cloud Run.
En la mayoría de los casos, estos roles de agente de servicio contienen permisos predeterminadas equivalentes para Artifact Registry y Container Registry, y no es necesario que realices ningún cambio adicional si ejecutas Artifact Registry en el mismo proyecto que tu servicio existente de Container Registry.
Consulta la referencia de roles de agente de servicio para obtener detalles sobre los permisos de los roles de agente de servicio.
- Funciones personalizadas
Usa la tabla de asignación de roles para decidir el rol que otorgarás a los usuarios o a las cuentas de servicio según el nivel de acceso que requieran.
Si deseas obtener instrucciones para otorgar roles de Artifact Registry, consulta Configura roles y permisos.
Realiza la autenticación en el repositorio
Artifact Registry admite los mismos métodos de autenticación que Container Registry.
Si usas el auxiliar de credenciales de Docker, haz lo siguiente:
- Debes usar la versión 2.0 o una posterior para interactuar con los repositorios de Artifact Registry. La versión independiente está disponible en GitHub.
- Debes configurar el auxiliar de credenciales con las ubicaciones de Artifact Registry que deseas usar. De forma predeterminada, el auxiliar de credenciales solo configura el acceso a los hosts de Container Registry.
Si quieres obtener detalles sobre cómo configurar la autenticación, consulta Configura la autenticación para Docker.
Cómo copiar contenedores desde Container Registry
Si hay contenedores en Container Registry que desees seguir usando en Artifact Registry, existen varias opciones para copiarlos. Para obtener instrucciones detalladas, consulta Copia imágenes de Container Registry.
Envía y extrae imágenes
Los comandos de Docker que usas para etiquetar, enviar y extraer imágenes en Artifact Registry son similares a los que usas en Container Registry. Existen dos diferencias clave:
- El nombre de host de los repositorios de Docker de Artifact Registry incluye un prefijo de ubicación, seguido de
-docker.pkg.dev. Entre los ejemplos, se incluyenaustralia-southeast1-docker.pkg.dev,europe-north1-docker.pkg.devyeurope-docker.pkg.dev. - Como Artifact Registry admite varios repositorios de Docker en un solo proyecto, debes especificar el nombre del repositorio en los comandos.
Por ejemplo, en Container Registry, este comando envía la imagen my-image al registro eu.gcr.io en el proyecto my-project.
docker push eu.gcr.io/my-project/my-image
En Artifact Registry, este comando envía la imagen my-image al repositorio regional europe-north1-docker.pkg.dev en el repositorio my-repo y el proyecto my-project.
docker push europe-north1-docker.pkg.dev/my-project/my-repo/my-image
Para obtener más información sobre cómo enviar y extraer imágenes en Artifact Registry, consulta Cómo enviar y extraer imágenes.
Implementa imágenes
Las cuentas de servicio para las integraciones Google Cloud comunes se configuran con permisos predeterminados para los repositorios del mismo proyecto.
La compilación de imágenes y su envío a un repositorio con Cloud Build en general funciona de la misma manera que en Container Registry. La diferencia clave en Artifact Registry es que debe existir un repositorio de destino antes de enviar imágenes a este, incluida la primera imagen que envías.
Asegúrate de crear los repositorios que necesitas antes de ejecutar los comandos que envían imágenes, incluidos el comando de Docker docker push y el comando de Cloud Build gcloud builds submit.
Los compiladores de Cloud Build aún se alojan en gcr.io. Para obtener más información, consulta Integración en Cloud Build.
Otras funciones
En esta sección, se describe la configuración de otras funciones que puedes haber configurado en Container Registry.
Artifact Analysis
Artifact Analysis admite Container Registry y Artifact Registry. La documentación de Artifact Analysis incluye ambos productos.
- Ambos productos usan las mismas APIs de Artifact Analysis. Cuando habilitas las APIs de Artifact Analysis en Container Registry o en Artifact Registry, estas se activan para ambos productos.
- Ambos productos usan los mismos temas de Pub/Sub para las notificaciones de Artifact Analysis.
- Puedes seguir usando los comandos gcloud container images para enumerar las notas y los casos asociados con las rutas de acceso de las imágenes de
gcr.io.
| Container Registry | Artifact Registry |
|---|---|
Busca vulnerabilidades de paquetes de lenguaje y SO con el análisis a pedido
en imágenes con un SO compatible. El análisis automático solo muestra información sobre vulnerabilidades del
SO.
Obtén más información sobre los tipos de
escaneo.
|
Realiza análisis de vulnerabilidades del SO y de los paquetes de lenguaje con análisis automáticos y a pedido.
Obtén más información sobre los tipos de
escaneo.
|
Notificaciones de Pub/Sub
Artifact Registry publica cambios en el mismo tema gcr que Container Registry. No se requiere ninguna configuración adicional si ya usas Pub/Sub con Container Registry en el mismo proyecto que Artifact Registry.
Si configuras Artifact Registry en un proyecto diferente, es posible que el tema gcr no exista. Para obtener instrucciones de configuración, consulta Configura notificaciones de Pub/Sub.
Perímetros de servicio
Con los Controles del servicio de VPC, puedes configurar perímetros de seguridad en torno a los recursos de tus servicios administrados por Google y controlar el movimiento de datos en los límites perimetrales.
Consulta Asegura repositorios en un perímetro de servicio para obtener instrucciones.
Limpia las imágenes de Container Registry
Cuando tengas todo listo para dejar de usar Container Registry, borra los buckets de almacenamiento de Container Registry para borrar las imágenes restantes.
Para borrar cada bucket de almacenamiento de Container Registry, sigue estos pasos:
Console
- Ve a la página de Cloud Storage en la consola de Google Cloud.
Selecciona el bucket de almacenamiento que quieres borrar. En los nombres de los buckets,
PROJECT-IDes el ID de tu proyecto Google Cloud.- gcr.io:
artifacts.PROJECT-ID.appspot.com - asia.gcr.io:
asia.artifacts.PROJECT-ID.appspot.com - eu.gcr.io:
eu.artifacts.PROJECT-ID.appspot.com - us.gcr.io:
us.artifacts.PROJECT-ID.appspot.com
- gcr.io:
Haz clic en Borrar. Aparecerá un cuadro de diálogo de confirmación.
Para confirmar la eliminación, ingresa el nombre del bucket y, luego, haz clic en Borrar.
gcloud
Si deseas borrar de forma masiva cien mil imágenes o más en un bucket, evita usar la CLI de gcloud, ya que el proceso de eliminación tarda mucho tiempo en completarse. En su lugar, usa la consola de Google Cloud para realizar la operación. Para obtener más información, consulta cómo borrar objetos de Cloud Storage de forma masiva.
Para borrar un bucket, usa el comando gcloud storage rm con la marca --recursive.
gcloud storage rm gs://BUCKET-NAME --recursive
Reemplaza BUCKET-NAME por el nombre del bucket de almacenamiento de
Container Registry. En los nombres de los buckets, PROJECT-ID es tu
Google Cloud
ID de proyecto.
- gcr.io:
artifacts.PROJECT-ID.appspot.com - asia.gcr.io:
asia.artifacts.PROJECT-ID.appspot.com - eu.gcr.io:
eu.artifacts.PROJECT-ID.appspot.com - us.gcr.io:
us.artifacts.PROJECT-ID.appspot.com
La respuesta se ve como el siguiente ejemplo:
Removing gs://artifacts.my-project.appspot.com/...
Si se ejecutan otros Google Cloud servicios en el mismo Google Cloud proyecto, deja habilitada la API de Container Registry. Si intentas inhabilitar la API de Container Registry. Container Registry muestra una advertencia si se habilitan otros servicios con una dependencia configurada en el proyecto. Si inhabilitas la API de Container Registry, se inhabilitarán automáticamente todos los servicios del mismo proyecto con una dependencia configurada, incluso si no estás usando Container Registry con esos servicios.
¿Qué sigue?
- Prueba la Guía de inicio rápido de Docker.