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

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

Si quieres crear repositorios de gcr.io en Artifact Registry con claves de cifrado gestionadas por el cliente (CMEK), sigue los pasos de la sección Antes de empezar y, a continuación, las instrucciones de la sección Creación manual de repositorios.

Antes de empezar

1. Instala Google Cloud CLI si aún no lo has hecho. Si ya tienes una instalación, ejecuta el siguiente comando para actualizar los componentes a las versiones más recientes:

   gcloud components update
   

2. Habilita las APIs Artifact Registry y Resource Manager. La CLI de gcloud usa la API Resource Manager para comprobar si se tiene uno de los permisos necesarios.

   Ejecuta el siguiente comando:

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

3. Consulta los precios de Artifact Registry antes de empezar la transición.

Roles obligatorios

Para obtener los permisos que necesitas para configurar repositorios gcr.io, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

• Para crear repositorios de Artifact Registry y conceder acceso a repositorios concretos, haz lo siguiente: Administrador de Artifact Registry (roles/artifactregistry.admin) en el proyecto Google Cloud
• Para ver y gestionar la configuración de Container Registry aplicada a los segmentos de almacenamiento de Cloud Storage, sigue estos pasos: Administrador de Storage (roles/storage.admin) en el proyecto Google Cloud
• Para crear un repositorio de gcr.io la primera vez que envíes una imagen a un nombre de host de gcr.io, haz lo siguiente: Artifact Registry Create-on-push Writer (roles/artifactregistry.createOnPushWriter) en el proyecto Google Cloud
• Para conceder acceso al repositorio a nivel de proyecto, sigue estos pasos: Administrador de gestión de identidades y accesos de proyectos (roles/resourcemanager.projectIamAdmin) en el proyecto Google Cloud
• Para enumerar los servicios habilitados en una organización, haz lo siguiente: Lector de recursos de Cloud (roles/cloudasset.viewer) en la organización

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Limitaciones

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

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

• Cada nombre de host de Container Registry se asigna a un solo repositorio gcr.io de Artifact Registry 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 migrar a repositorios de pkg.dev en Artifact Registry. Como los repositorios de pkg.dev no admiten el dominio gcr.io, este enfoque de transición requiere más cambios en tu automatización y tus flujos de trabajo. Consulta Elegir una opción de transición para obtener información sobre las diferencias entre las funciones.

Crear repositorios

Crea repositorios de gcr.io para poder configurar el acceso de tus usuarios y copiar las imágenes de Container Registry en Artifact Registry antes de habilitar la redirección.

Creación manual de repositorios

Crea manualmente los gcr.iorepositorios si quieres usar claves de cifrado gestionadas por el cliente (CMEK) para cifrar el contenido del repositorio o si hay una restricción de ubicación en tuGoogle Cloud organización que impida crear recursos en ubicaciones específicas.

Para crear manualmente un repositorio gcr.io, sigue estos pasos:

1. Si usas CMEK, crea la clave que vas a usar con este repositorio y concede permisos para usarla. Consulta Habilitar claves de cifrado gestionadas por el cliente.

2. Añade el repositorio.

   Consola

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

      Abre 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 formato de repositorio.

   5. En Location Type (Tipo de ubicación), especifica 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

   6. Añade una descripción del repositorio. No incluyas datos sensibles, ya que las descripciones de los repositorios no están cifradas.

   7. En la sección Cifrado, elige el mecanismo de cifrado del repositorio.

      • Google-managed encryption key: cifra el contenido del repositorio con una Google-owned and Google-managed encryption key.
      • Clave gestionada por el cliente: encripta el contenido del repositorio con una clave que controlas a través de Cloud Key Management Service. Para obtener instrucciones sobre cómo configurar las claves, consulta el artículo Configurar claves de cifrado gestionadas por el cliente para repositorios.

   8. Haz clic en Crear.

   gcloud

   Ejecuta el siguiente comando para crear un repositorio:

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

   Sustituye 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 cifradas.

   • KMS-KEY es la ruta completa a la clave de cifrado de Cloud KMS si usas una clave de cifrado gestionada por el cliente para cifrar el contenido del repositorio. La ruta tiene el siguiente formato:

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

     Sustituye 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 conjunto de claves.
     • KEY es el nombre de la clave.

   Para confirmar que se ha creado el repositorio, puedes enumerar tus repositorios con el siguiente comando:

   gcloud artifacts repositories list
   

Antes de redirigir el tráfico a tus nuevos repositorios, debes asegurarte de que tu automatización actual pueda acceder al repositorio. El siguiente paso es configurar los permisos para conceder acceso a los repositorios.

Conceder permisos a repositorios

Container Registry usa roles de Cloud Storage para controlar el acceso. Artifact Registry tiene sus propios roles de gestión de identidades y accesos, que 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 concedidos en los contenedores de almacenamiento a los roles de Artifact Registry sugeridos, usa la herramienta de asignación de roles.

También puede ver una lista de las entidades que tienen acceso a los contenedores de almacenamiento mediante la Google Cloud consola.

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

   Ir a Contenedores

2. Haga clic en el segmento de almacenamiento del host del registro que quiera ver. En los nombres de los segmentos, PROJECT-ID es elGoogle 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

3. Haz clic en la pestaña Permisos.

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

5. Despliega un rol para ver las entidades que lo tienen.

La lista incluye los roles de gestión de identidades y accesos concedidos directamente en el segmento y los roles heredados del proyecto principal. En función del rol, puedes elegir el rol de Artifact Registry más adecuado para conceder.

Cloud Storage y roles básicos

Concede acceso a los repositorios de Artifact Registry a los usuarios y las cuentas de servicio que actualmente tienen acceso a Container Registry. En el caso de los roles de Cloud Storage heredados del proyecto principal, debes verificar que la entidad de seguridad use Container Registry. Es posible que algunos principales solo accedan a otros segmentos de Cloud Storage que no estén relacionados con Container Registry.

Los roles básicos Propietario, Editor y Lector que existían antes de IAM tienen acceso limitado a los segmentos de almacenamiento. No proporcionan intrínsecamente todo el acceso a los recursos de Cloud Storage que implican sus nombres y ofrecen permisos adicionales para otros servicios. Google Cloud Comprueba qué usuarios y cuentas de servicio necesitan acceso a Artifact Registry y usa la tabla de asignación de roles para conceder los roles adecuados si el acceso a Artifact Registry es apropiado.

En la siguiente tabla se asignan los roles de Artifact Registry en función de los permisos concedidos por los roles predefinidos de Cloud Storage para acceder a Container Registry.

Acceso necesario	Rol actual	Rol de Artifact Registry	Dónde conceder el rol
Extraer solo imágenes (solo lectura)	Lector de objetos de Storage (roles/storage.objectViewer)	Lector de Artifact Registry (roles/artifactregistry.reader)	Repositorio o Google Cloud proyecto de Artifact Registry
Insertar y extraer imágenes (lectura y escritura) Eliminar imágenes	Editor de segmentos heredados de Storage (roles/storage.legacyBucketWriter)	Administrador del repositorio de Artifact Registry (roles/artifactregistry.repoAdmin)	Repositorio o Google Cloud proyecto de Artifact Registry
Crea un repositorio gcr.io en Artifact Registry la primera vez que se envía una imagen a un nombre de host gcr.io en un proyecto.	Administrador de almacenamiento (roles/storage.admin)	Administrador del repositorio de Artifact Registry Create-on-push (roles/artifactregistry.createOnPushRepoAdmin)	Google Cloud proyecto
Crear, gestionar y eliminar repositorios	Administrador de almacenamiento (roles/storage.admin)	Administrador de Artifact Registry (roles/artifactregistry.admin)	Google Cloud proyecto

Roles de agente de servicio heredados del proyecto

Las cuentas de servicio predeterminadas de los Google Cloud servicios tienen sus propios roles concedidos a nivel de proyecto. Por ejemplo, el agente de servicio de Cloud Run tiene el rol 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, por lo que no es necesario que hagas ningún cambio adicional si ejecutas Artifact Registry en el mismo proyecto que tu servicio de Container Registry.

Consulta la referencia de roles de agente de servicio para obtener más información sobre los permisos de los roles de agente de servicio.

Roles personalizados

Usa la tabla de asignación de roles para decidir qué rol asignar a los usuarios o las cuentas de servicio en función del nivel de acceso que necesiten.

Para obtener instrucciones sobre cómo asignar roles de Artifact Registry, consulta Configurar roles y permisos.

Copiar contenedores de Container Registry

Te recomendamos que utilices 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 el artículo Copiar imágenes de Container Registry.

Configurar otras funciones

En esta sección se describe la configuración de otras funciones que puede 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 los metadatos de las imágenes y el análisis de vulnerabilidades, así como los mismos temas de Pub/Sub para las notificaciones de Artifact Analysis.

Sin embargo, las siguientes acciones solo se producen cuando la redirección está habilitada:

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

Puedes seguir usando los comandos de imágenes de contenedor de gcloud para enumerar las notas y las incidencias asociadas a las rutas de imágenes de gcr.io.

Notificaciones de Pub/Sub

Artifact Registry publica los cambios en el mismo tema gcr que Container Registry. No es necesario realizar ninguna configuración adicional si ya utiliza Pub/Sub con Container Registry en el mismo proyecto que Artifact Registry. Sin embargo, Artifact Registry no publica mensajes para los repositorios gcr.io hasta que habilites la redirección.

Si configuras Artifact Registry en un proyecto independiente, es posible que el tema gcr no exista. Para obtener instrucciones de configuración, consulta Configurar notificaciones de Pub/Sub.

Habilitar la redirección del tráfico de gcr.io

Una vez que hayas creado tus repositorios de gcr.io y hayas configurado los permisos y la autenticación de tus clientes de terceros, podrás habilitar la redirección del tráfico de gcr.io.

Si tienes algún problema después de habilitar la redirección, puedes volver a enrutar el tráfico a Container Registry ejecutando el comando gcloud artifacts settings disable-upgrade-redirection y, a continuación, volver a activar la redirección cuando hayas resuelto el problema.

Verificar los permisos para habilitar la redirección

Para habilitar la redirección, debe tener estos permisos a nivel de proyecto:

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

Si no tienes estos permisos, pide a un administrador que te los conceda a nivel de proyecto.

Los siguientes comandos asignan los roles 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'

Sustituye los siguientes valores:

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

Validar 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

Sustituye PROJECT_ID por el Google Cloud ID de tu proyecto.

Artifact Registry busca repositorios que se correspondan con nombres de host de Container Registry.

Aunque Artifact Registry puede crear los repositorios gcr.io que faltan cuando habilitas la redirección, te recomendamos que los crees primero para que puedas realizar estas acciones antes de activar la redirección:

• Configurar permisos a nivel de repositorio.
• Copia las imágenes de Container Registry que quieras seguir usando.
• Realiza cualquier configuración adicional.

Activar la redirección

Para activar la redirección del tráfico de gcr.io, sigue estos pasos:

Para habilitar la redirección, ejecuta el siguiente comando:

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

Sustituye PROJECT_ID por el Google Cloud ID de tu proyecto.

Artifact Registry empieza a activar la redirección.

Para comprobar el estado actual de la redirección, ejecuta el siguiente comando:

gcloud artifacts settings describe

Si la redirección está habilitada, 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 redirige, aunque no hayas creado repositorios gcr.io para todos los nombres de host de Container Registry. Si insertas una imagen en 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 Escritor de creación en push (artifactregistry.createOnPushWriter) y Administrador de repositorio de creación en push (artifactregistry.createOnPushRepoAdmin) tienen este permiso.

Si la redirección está habilitada, puedes probar tu automatización y verificar que puedes enviar y extraer imágenes con tus nuevos repositorios de gcr.io.

Verificar redirección

Verifica que las solicitudes de extracción e inserción a los nombres de host gcr.io funcionan.

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

   1. Etiqueta la imagen con la ruta 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 has etiquetado. 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. Lista las imágenes del repositorio para verificar que la imagen se ha subido correctamente. Por ejemplo, para enumerar las imágenes de us.gcr.io/my-project, ejecuta el comando:

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

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

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

Después de esta prueba inicial, comprueba que la automatización que ya tienes para compilar y desplegar imágenes funciona correctamente. Para ello, verifica lo siguiente:

• Los usuarios y las cuentas de servicio que usen Container Registry podrán seguir insertando, extrayendo e implementando imágenes cuando la redirección esté habilitada.
• La automatización solo envía imágenes a repositorios que ya existen.
• Si el análisis de vulnerabilidades de Artifact Analysis está habilitado, el análisis identifica las imágenes con vulnerabilidades en los repositorios gcr.io.
• Si usas la autorización binaria, tus políticas actuales funcionarán correctamente con las imágenes desplegadas desde repositorios de gcr.io.
• Las suscripciones de Pub/Sub configuradas incluyen notificaciones sobre los cambios en tus repositorios gcr.io.

Limpiar imágenes de Container Registry

Cuando la redirección está habilitada, los comandos para eliminar imágenes en rutas gcr.io eliminan imágenes en el repositorio gcr.io de Artifact Registry correspondiente. Los comandos para eliminar imágenes en rutas de gcr.io no eliminan las imágenes almacenadas en hosts de Container Registry.

Para eliminar de forma segura todas las imágenes de Container Registry, elimina los segmentos de Cloud Storage de cada nombre de host de Container Registry.

Para eliminar cada segmento de almacenamiento de Container Registry, haz lo siguiente:

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

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

Si hay otros Google Cloud servicios en el mismo Google Cloud proyecto, deja habilitada la API de Container Registry. Si intentas inhabilitar la API Container Registry. Container Registry muestra una advertencia si hay otros servicios con una dependencia configurada habilitados en el proyecto. Si inhabilitas la API Container Registry, se inhabilitarán automáticamente todos los servicios del mismo proyecto que tengan una dependencia configurada, aunque no estés usando Container Registry con esos servicios.

Siguientes pasos

• Consulta la guía de inicio rápido de Docker.
• Consulta información sobre los repositorios de gcr.io.