Migración manual a repositorios de "gcr.io" en Artifact Registry

En este documento, se explica cómo configurar manualmente repositorios de gcr.io en Artifact Registry.

Si deseas crear repositorios de gcr.io en Artifact Registry con claves de encriptación administradas por el cliente (CMEK), completa los pasos que se indican en Antes de comenzar y, luego, sigue las instrucciones que se indican en Creación manual de repositorios.

Antes de comenzar

  1. Instala la CLI de Google Cloud 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

  2. Habilita las APIs de Artifact Registry y Resource Manager. La gcloud CLI usa la API de Resource Manager para verificar uno de los permisos requeridos.

    Ejecuta el siguiente comando:

    gcloud services enable \
    cloudresourcemanager.googleapis.com \
    artifactregistry.googleapis.com

  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:

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.

Limitaciones

Se aplican las siguientes limitaciones a los repositorios de Artifact Registry gcr.io:

  • Cuando migras de Container Registry, no puedes asignar un host de Container Registry a un repositorio de Artifact Registry en un proyecto diferente.

  • Cada nombre de host de Container Registry se asigna a un solo repositorio de gcr.io de Artifact Registry correspondiente en la misma multirregión.

  • Los nombres de los repositorios de gcr.io están predefinidos y no se pueden modificar.

Si necesitas más control sobre la ubicación de tus repositorios, puedes hacer la transición a los repositorios pkg.dev en Artifact Registry. Dado que los repositorios de pkg.dev no admiten el dominio gcr.io, este enfoque de transición requiere más cambios en tus flujos de trabajo y automatización existentes. Consulta Elige una opción de transición para obtener información sobre las diferencias entre las funciones.

Crea repositorios

Crea repositorios de gcr.io para que puedas configurar el acceso de tus usuarios y copiar imágenes existentes de Container Registry a Artifact Registry antes de habilitar el redireccionamiento.

Creación manual de repositorios

Crea repositorios de gcr.io de forma manual si deseas usar claves de encriptación administradas por el cliente (CMEK) para encriptar el contenido del repositorio o si hay una restricción de ubicación en tu organización deGoogle Cloud que bloquea la creación de recursos nuevos en ubicaciones específicas.

Para crear manualmente un repositorio gcr.io, haz lo siguiente:

  1. Si usas CMEK, crea la clave que usarás con este repositorio y otórgale permisos para usarla. Consulta Cómo habilitar claves de encriptación administradas por el cliente.

  2. Agrega el repositorio.

    Console

    1. Abre la página Repositorios en la consola de Google Cloud .

      Abrir la página repositorios

    2. Haz clic en Crear repositorio.

    3. Especifica el nombre del repositorio.

      Nombre de host de Container Registry Nombre del repositorio de Artifact Registry
      gcr.io gcr.io
      asia.gcr.io asia.gcr.io
      eu.gcr.io eu.gcr.io
      us.gcr.io us.gcr.io

    4. Especifica Docker como el formato del repositorio.

    5. En Tipo de ubicación, especifica la multirregión para el repositorio:

      Nombre de host de Container Registry Ubicación del repositorio de Artifact Registry Nombre del repositorio de Artifact Registry
      gcr.io us gcr.io
      asia.gcr.io asia asia.gcr.io
      eu.gcr.io europa eu.gcr.io
      us.gcr.io us us.gcr.io

    6. Agrega una descripción para el repositorio. No incluyas datos sensibles, ya que las descripciones de los repositorios no están encriptadas.

    7. En la sección Encryption, elige el mecanismo de encriptación para el repositorio.

      • Google-managed encryption key: Encripta el contenido del repositorio con un Google-owned and Google-managed encryption key.
      • Clave administrada por el cliente: Encripta el contenido de un repositorio mediante una clave que controlas a través de Cloud Key Management Service. Si deseas obtener instrucciones para la configuración de claves, consulta Configura CMEK para repositorios.

    8. Haga clic en Crear.

    gcloud

    Ejecuta el siguiente comando para crear un repositorio nuevo:

    gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION \
    --description=DESCRIPTION \
    --kms-key=KMS-KEY

    Reemplaza los siguientes valores:

    • REPOSITORY es el nombre del repositorio.

      Nombre de host de Container Registry Nombre del repositorio de Artifact Registry
      gcr.io gcr.io
      asia.gcr.io asia.gcr.io
      eu.gcr.io eu.gcr.io
      us.gcr.io us.gcr.io

    • LOCATION es la multirregión del repositorio:

      Nombre de host de Container Registry Ubicación del repositorio de Artifact Registry Nombre del repositorio de Artifact Registry
      gcr.io us gcr.io
      asia.gcr.io asia asia.gcr.io
      eu.gcr.io europa eu.gcr.io
      us.gcr.io us us.gcr.io

    • DESCRIPTION es una descripción del repositorio. No incluyas datos sensibles, ya que las descripciones de los repositorios no están encriptadas.

    • KMS-KEY es la ruta de acceso completa a la clave de encriptación de Cloud KMS si usas una clave de encriptación administrada por el cliente para encriptar el contenido del repositorio. La ruta de acceso tiene el siguiente formato:

      projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

      Reemplaza los siguientes valores:

      • KMS-PROJECT es el proyecto en el que se almacena tu clave.
      • KMS-LOCATION es la ubicación de la clave.
      • KEY-RING es el nombre del llavero de claves.
      • KEY es el nombre de la clave.

    Para confirmar que se creó el repositorio, enumera tus repositorios con el siguiente comando:

    gcloud artifacts repositories list

Antes de redireccionar el tráfico a tus repositorios nuevos, debes asegurarte de que la automatización existente pueda acceder al repositorio. El siguiente paso es configurar los permisos para otorgar acceso a los repositorios.

Otorga permisos a los repositorios

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.

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)
  • Borrar 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 un repositorio de gcr.io en Artifact Registry la primera vez que se envía una imagen a un nombre de host de gcr.io en un proyecto. Administrador de almacenamiento
(roles/storage.admin)		 Administrador del repositorio de Artifact Registry para envíos con creaciones
(roles/artifactregistry.createOnPushRepoAdmin)		 Google Cloud proyecto
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.

Copia contenedores desde Container Registry

Te recomendamos que uses nuestra herramienta de migración automática para copiar tus imágenes de Container Registry a Artifact Registry.

Si quieres usar otras herramientas para copiar tus imágenes, consulta Copia imágenes de Container Registry.

Configura 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. Ambos productos usan las mismas APIs de Artifact Analysis para el análisis de vulnerabilidades y los metadatos de imágenes, y los mismos temas de Pub/Sub para las notificaciones de Artifact Analysis.

Sin embargo, las siguientes acciones solo ocurren cuando el redireccionamiento está habilitado:

  • Análisis automático de repositorios gcr.io en Artifact Registry
  • Se incluye la actividad del repositorio gcr.io en las notificaciones de Pub/Sub.

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.

Container Registry Artifact Registry
Analiza en busca de vulnerabilidades del SO y de paquetes de lenguajes con el análisis a pedido en imágenes con un SO compatible. El análisis automático solo devuelve información sobre vulnerabilidades del SO. Obtén más información sobre los tipos de análisis.
Análisis a pedido
Búsqueda automática
  • El comando de Google Cloud CLI gcloud container images incluye marcas para ver los resultados del análisis, incluidas las vulnerabilidades y otros metadatos.
  • Los análisis solo devuelven información sobre las vulnerabilidades del SO para las imágenes en Container Registry con sistemas operativos compatibles.
Analiza las vulnerabilidades del SO y de los paquetes de lenguajes con análisis automáticos y a pedido. Obtén más información sobre los tipos de análisis.
Análisis a pedido
Búsqueda automática
  • El comando de Google Cloud CLI gcloud artifacts docker images incluye marcas para ver los resultados del análisis, incluidas las vulnerabilidades y otros metadatos.
  • Los análisis devuelven información sobre las vulnerabilidades del SO para las imágenes en Artifact Registry con sistemas operativos compatibles y también información sobre las vulnerabilidades de los paquetes de lenguajes para los sistemas operativos compatibles y no compatibles.

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. Sin embargo, Artifact Registry no publica mensajes para los repositorios de gcr.io hasta que habilites el redireccionamiento.

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.

Habilita el redireccionamiento del tráfico de gcr.io

Después de crear tus repositorios gcr.io y configurar los permisos y la autenticación para los clientes de terceros, puedes habilitar el redireccionamiento del tráfico de gcr.io.

Si tienes un problema después de habilitar el redireccionamiento, puedes volver a enrutar el tráfico a Container Registry ejecutando el comando gcloud artifacts settings disable-upgrade-redirection y, luego, volver a activar el redireccionamiento cuando hayas resuelto el problema.

Verifica los permisos para habilitar el redireccionamiento

Para habilitar el redireccionamiento, debes tener estos permisos a nivel del proyecto:

  • artifactregistry.projectsettings.update: Permisos para actualizar la configuración del proyecto de Artifact Registry. Este permiso se encuentra en el rol de administrador de Artifact Registry (roles/artifactregistry.admin).
  • storage.buckets.update: Permisos para actualizar buckets de almacenamiento en todo el proyecto. Este permiso se encuentra en el rol de administrador de almacenamiento (roles/storage.admin).

Si no tienes estos permisos, pídele a un administrador que te los otorgue a nivel del proyecto.

Los siguientes comandos otorgan los roles de administrador de Artifact Registry y administrador de almacenamiento en un proyecto.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/artifactregistry.admin'

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/storage.admin'

Reemplaza los siguientes valores:

  • PROJECT_ID es el Google Cloud ID del proyecto.
  • PRINCIPAL es la dirección de correo electrónico de la cuenta que estás actualizando. Por ejemplo, my-user@example.com

Valida la configuración del proyecto

Para validar la configuración del proyecto, ejecuta el siguiente comando:

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID --dry-run

Reemplaza PROJECT_ID por tu Google Cloud ID del proyecto.

Artifact Registry verifica si hay repositorios que se asignen a nombres de host de Container Registry.

Si bien Artifact Registry puede crear los repositorios gcr.io faltantes por ti cuando habilitas el redireccionamiento, te recomendamos que los crees primero para que puedas realizar estas acciones antes de activar el redireccionamiento:

Activa el redireccionamiento

Sigue estos pasos para activar el redireccionamiento del tráfico de gcr.io:

Para habilitar el redireccionamiento, ejecuta el siguiente comando:

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

Reemplaza PROJECT_ID por tu Google Cloud ID del proyecto.

Artifact Registry comienza a activar el redireccionamiento.

Para verificar el estado actual del redireccionamiento, ejecuta el siguiente comando:

gcloud artifacts settings describe

Cuando el redireccionamiento está habilitado, el resultado es el siguiente:

legacyRedirectionState: REDIRECTION_FROM_GCR_IO_ENABLED

Todo el tráfico a gcr.io, asia.gcr.io, eu.gcr.io y us.gcr.io se redirecciona, incluso si no creaste repositorios de gcr.io para todos los nombres de host de Container Registry. Si envías una imagen a un nombre de host que no tiene un repositorio de Artifact Registry correspondiente, Artifact Registry crea el repositorio si tienes un rol con el permiso artifactregistry.repositories.createOnPush. Los roles predefinidos Create-on-push Writer (artifactregistry.createOnPushWriter) y Create-on-push Repository Administrator (artifactregistry.createOnPushRepoAdmin) tienen este permiso.

Con el redireccionamiento habilitado, puedes probar tu automatización y verificar que puedes enviar y extraer imágenes con tus nuevos repositorios de gcr.io.

Verifica el redireccionamiento

Verifica que las solicitudes de extracción y envío a los nombres de host de gcr.io funcionen correctamente.

  1. Envía una imagen de prueba a uno de tus repositorios de gcr.io con su ruta de acceso de gcr.io.

    1. Etiqueta la imagen con la ruta de acceso gcr.io. Por ejemplo, este comando etiqueta la imagen local-image como us.gcr.io/my-project/test-image:

      docker tag local-image us.gcr.io/my-project/test-image

    2. Envía la imagen que etiquetaste. Por ejemplo, este comando envía la imagen us.gcr.io/my-project/test-image:

      docker push us.gcr.io/my-project/test-image

  2. Enumera las imágenes en el repositorio para verificar que se hayan subido correctamente. Por ejemplo, para enumerar las imágenes en us.gcr.io/my-project, ejecuta el siguiente comando:

    gcloud container images list --repository=us.gcr.io/my-project

  3. Extrae la imagen del repositorio mediante la ruta de acceso de Container Registry. Por ejemplo, este comando extrae la imagen us.gcr.io/my-project/test-image.

    docker pull us.gcr.io/my-project/test-image

Después de esta prueba inicial, verifica que tu automatización existente para compilar e implementar imágenes funcione según lo esperado, lo que incluye lo siguiente:

  • Los usuarios y las cuentas de servicio que usan Container Registry aún pueden enviar, extraer e implementar imágenes cuando el redireccionamiento está habilitado.
  • Tu automatización solo envía imágenes a repositorios existentes.
  • Si está habilitado el análisis de vulnerabilidades de Artifact Analysis, el análisis identifica las imágenes con vulnerabilidades en los repositorios de gcr.io.
  • Si usas Autorización Binaria, tus políticas existentes funcionan correctamente para las imágenes implementadas desde repositorios de gcr.io.
  • Las suscripciones a Pub/Sub configuradas incluyen notificaciones sobre los cambios en tus repositorios de gcr.io.

Limpia las imágenes de Container Registry

Cuando el redireccionamiento está habilitado, los comandos para borrar imágenes en rutas de acceso gcr.io borran imágenes en el repositorio de Artifact Registry gcr.io correspondiente. Los comandos para borrar imágenes en rutas de acceso gcr.io no borran las imágenes almacenadas en hosts de Container Registry.

Para quitar de forma segura todas las imágenes de Container Registry, borra los buckets de Cloud Storage para cada nombre de host de Container Registry.

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

Console

  1. Ve a la página de Cloud Storage en la Google Cloud consola.

  2. Selecciona el bucket de almacenamiento que deseas borrar. En los nombres de bucket, PROJECT-ID es tu Google Cloud ID del 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

  3. Haz clic en Borrar. Aparecerá un cuadro de diálogo de confirmación.

  4. 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 gcloud CLI, 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 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

La respuesta se ve como el siguiente ejemplo:

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?