Transición a repositorios estándar

Si usas Container Registry para administrar tus imágenes de contenedor, en esta página se explica cómo configurar un repositorio de pkg.dev Artifact Registry y cómo se diferencia el uso de repositorios del uso de Container Registry.

Estas instrucciones son principalmente para los administradores de repositorios. Para obtener información sobre cómo cambió 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 la transferencia de imágenes con Docker

Antes de comenzar

1. Habilita la API de Artifact Registry desde la consola deGoogle Cloud o con el siguiente comando:

   gcloud services enable artifactregistry.googleapis.com
   

2. Instala la CLI de gcloud 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 update
   

3. Obté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 proyecto Google Cloud :

• 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, haz lo siguiente: Administrador de Storage (roles/storage.admin)
• Para otorgar acceso al repositorio a nivel del proyecto, se requiere el rol de administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin) o un rol que incluya permisos equivalentes, como el de 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 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 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 seguir los mismos pasos generales.

Artifact Registry también ofrece repositorios de gcr.io. Estos repositorios pueden redireccionar el tráfico de gcr.io desde tus registros existentes a los repositorios correspondientes de Artifact Registry. 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 a gcr.io, es posible que necesites 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:

1. Crea un repositorio de Docker para tus contenedores. Debes crear un repositorio para poder enviar imágenes a este.
2. Otorga permisos al repositorio.
3. Configura la autenticación para que puedas conectarte con tu repositorio nuevo.
4. Si es necesario, copia imágenes de Container Registry que desees usar en tu repositorio nuevo.
5. Intenta enviar y extraer tus contenedores.
6. Intenta implementar tus imágenes en un entorno de ejecución.
7. Configura las funciones adicionales.
8. Borra 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, configura el bucket de almacenamiento de Container Registry para usar CMEK. En Artifact Registry, configuras los repositorios para usar 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 lectura, escritura y administración de repositorios 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 las entidades principales con acceso a los buckets de almacenamiento en la consola de Google Cloud .

1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.
   

   Ir a Buckets

2. Haz clic en el bucket de almacenamiento del host del registro que quieres ver. En los nombres de bucket, PROJECT-ID es tu ID del proyecto deGoogle 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

3. Haz clic en la pestaña Permisos.

4. En la pestaña Permisos, haz clic en la subpestaña Ver por rol.

5. 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 principal. 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 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 heredados del proyecto principal, debes verificar que la principal use Container Registry actualmente. 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 de 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 servicios de Google Cloud . 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 que otorgan 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 requerido	Rol actual	Rol de Artifact Registry	Dónde otorgar el rol
Solo extraer imágenes (solo lectura)	Visualizador de objetos de Storage (roles/storage.objectViewer)	Lector de Artifact Registry (roles/artifactregistry.reader)	Repositorio de Artifact Registry o proyecto de Google Cloud
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 de Artifact Registry o proyecto de Google Cloud
Envía, extrae y borra imágenes	Escritor de buckets heredados de almacenamiento (roles/storage.legacyBucketWriter)	Administrador del repositorio de Artifact Registry (roles/artifactregistry.repoAdmin)	Repositorio de Artifact Registry o proyecto de Google Cloud
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 predeterminados equivalentes para Container Registry y Artifact 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 del rol de agente de servicio para obtener detalles sobre los permisos en los roles de agente de servicio.

Funciones personalizadas

Usa la tabla de asignación de roles para decidir qué rol otorgar a los usuarios o 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.

Copia 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 incluyen australia-southeast1-docker.pkg.dev, europe-north1-docker.pkg.dev y europe-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 Google Cloud integraciones comunes se configuran con permisos predeterminados para los repositorios en el 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 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 de gcloud container images para enumerar las notas y las ocurrencias asociadas con las rutas de acceso a imágenes de gcr.io.

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 termines de usar Container Registry, borra las imágenes restantes borrando los buckets de almacenamiento de Container Registry.

Para borrar cada bucket de almacenamiento de Container Registry, haz lo siguiente:

gcloud storage rm gs://BUCKET-NAME --recursive

Removing gs://artifacts.my-project.appspot.com/...

Si otros Google Cloud servicios se ejecutan en el mismo Google Cloudproyecto, deja habilitada la API de Container Registry. Si intentas inhabilitar la API de Container Registry Container Registry muestra una advertencia si hay otros servicios con una dependencia configurada habilitados en el proyecto. Inhabilitar la API de Container Registry inhabilita automáticamente cualquier servicio en el mismo proyecto con una dependencia configurada, incluso si no estás usando Container Registry con esos servicios en este momento.

¿Qué sigue?

• Prueba la Guía de inicio rápido de Docker.