Configura notificaciones de Pub/Sub

Puedes recibir notificaciones de Pub/Sub por los cambios realizados en un repositorio de Docker. Las notificaciones se aplican a cualquier imagen de contenedor almacenada en el repositorio, incluidos los gráficos de Helm 3 empaquetadas en formato OCI.

Pub/Sub publica mensajes sobre tus repositorios en recursos con nombre llamados temas. Las aplicaciones que se suscriben a temas de Pub/Sub reciben estos mensajes y notificaciones cuando cambia el estado de un repositorio.

Artifact Registry publica mensajes por los siguientes cambios:

  • Cargas de imágenes
  • Etiquetas nuevas agregadas a imágenes
  • Eliminación de imágenes

Además, puedes configurar funciones y permisos para realizar publicaciones o suscribirte a notificaciones.

Si quieres obtener información sobre cómo configurar las notificaciones de Artifact Analysis para la actividad, como los resultados del análisis de vulnerabilidades nuevos, consulta la documentación de Artifact Analysis.

Descripción general

Artifact Registry publica mensajes sobre cambios para los repositorios en un tema llamado gcr.

Para recibir notificaciones, debes hacer lo siguiente:

  1. Crea un tema con el nombre gcr en el proyecto en el que se encuentra Artifact Registry.
  2. Crea una suscripción al tema.
  3. Configura tu aplicación de suscriptor para recibir mensajes sobre los cambios en el repositorio.
  4. Si es necesario, configura permisos para controlar el acceso al tema y la suscripción.

Crea el tema de Artifact Registry

Cuando activas la API de Artifact Registry en un proyecto de Google Cloud, Artifact Registry crea automáticamente un tema de Pub/Sub con el ID del tema gcr. Si Container Registry está habilitado en el mismo proyecto de Google Cloud, es posible que el tema ya exista, ya que ambos servicios de registro usan el mismo tema para publicar mensajes.

Si el tema gcr no se encuentra o se borró por accidente, puedes agregarlo tú mismo. Por ejemplo, es posible que el tema no esté presente si tu organización de Google Cloud tiene una restricción de la política de la organización que requiere encriptación con claves de encriptación administradas por el cliente (CMEK). Cuando la API de Pub/Sub está en la lista de denegación de esta restricción, los servicios no pueden crear temas de forma automática con claves de encriptación administradas por Google.

Para ver una lista de los temas existentes, puedes consultar la página de temas de Pub/Sub en la consola de Google Cloud o ejecutar el siguiente comando:

gcloud pubsub topics list

Para crear el tema gcr con claves de encriptación administradas por Google, haz lo siguiente:

Consola

  1. Ve a la página Temas de Pub/Sub en la consola de Google Cloud.

    Ir a la página Temas de Pub/Sub

  2. Haz clic en Crear tema.

  3. Ingresa el ID del tema gcr.

  4. Haga clic en Create Topic.

gcloud

Ejecuta el siguiente comando:

gcloud pubsub topics create gcr --project=PROJECT-ID

Reemplaza PROJECT-ID por el ID del proyecto de Google Cloud. Si omites la marca --project, el comando usará el proyecto actual.

Para obtener más información sobre el comando gcloud pubsub topics, consulta la documentación de topics.

Si deseas crear el tema gcr con la encriptación con CMEK, consulta las instrucciones de Pub/Sub para encriptar temas.

Después de crear el tema gcr o verificar que existe, puedes crear una suscripción al tema.

Cómo crear una suscripción

Después de crear un tema para los cambios en el repositorio, puedes configurar una suscripción que use la entrega de envío o la entrega de extracción. Recomendamos usar la entrega de extracción, ya que los sistemas de CI/CD pueden generar muchos cambios en los artefactos almacenados, y la entrega de extracción es más efectiva para usar en un gran volumen de mensajes.

Para crear una suscripción con entrega de extracción, haz lo siguiente:

Consola

  1. Ve a la página Temas de Pub/Sub en la consola de Google Cloud.

    Ir a la página Temas de Pub/Sub

  2. Haz clic en el tema de tu proyecto.

  3. Haz clic en Crear suscripción.

  4. Ingresa un nombre de suscripción.

    projects/PROJECT/subscriptions/[SUBSCRIPTION-NAME]

    Configura el Tipo de entrega como Extracción.

  5. Haz clic en Crear.

gcloud

Ejecuta el siguiente comando:

gcloud pubsub subscriptions create SUBSCRIPTION-NAME --topic=gcr

Reemplaza SUBSCRIPTION-NAME por un nombre para la suscripción.

Para obtener más información sobre el comando gcloud pubsub subscriptions, consulta la documentación de subscriptions.

Ahora tienes una suscripción al tema gcr. El siguiente paso es configurar permisos para las identidades que activan cambios en los repositorios.

Cómo configurar tu aplicación de suscriptor

Después de crear un tema y una suscripción a ese tema, puedes configurar tu aplicación de suscriptor, que es la aplicación que recibe mensajes sobre los cambios en los repositorios. Las aplicaciones de suscriptor completan tareas como el envío de notificaciones de eventos, la creación de registros del sistema y la comunicación entre aplicaciones.

Cuando un usuario del repositorio envía o borra una imagen, se producen los siguientes pasos:

  1. La cuenta de servicio de Artifact Registry publica el cambio en tu tema gcr. La cuenta de servicio es service-PROJECT-NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com, en el que PROJECT-NUMBER es el número de proyecto de Google Cloud. La cuenta de servicio de Artifact Registry tiene el permiso pubsub.topics.publish de forma predeterminada para que pueda publicar cambios en tu tema.

    Si un administrador revocó los permisos pubsub.topics.publish de la cuenta de servicio de Artifact Registry, este intentará publicar el mensaje como el usuario del repositorio. En esta situación, la cuenta del usuario del repositorio debe tener el permiso pubsub.topics.publish para publicar el mensaje de forma correcta.

  2. Pub/Sub reenvía el mensaje del tema a tu suscripción.

  3. Cuando tu aplicación de suscriptor realiza una solicitud de mensajes, extrae el mensaje nuevo de la suscripción.

    La identidad que extrae los mensajes en nombre del suscriptor debe tener permisos para acceder a la suscripción. Puedes usar la función de suscriptor de Pub/Sub para otorgar este permiso.

Si quieres obtener información sobre cómo configurar un suscriptor para recibir mensajes de una suscripción con entrega de extracción, consulta Recibe mensajes mediante la extracción.

Configurar permisos

Puedes usar permisos de Pub/Sub para controlar el acceso a los temas y las suscripciones.

Para obtener más información sobre los permisos de Pub/Sub y sobre cómo otorgar acceso a temas y suscripciones, consulta la documentación del control de acceso de Pub/Sub.

Ejemplos de notificaciones

Pub/Sub envía notificaciones como strings con formato JSON. Revisa los siguientes ejemplos para saber qué esperar cuando recibas notificaciones de Artifact Registry de Pub/Sub.

Cuando se envía una imagen a Artifact Registry, la carga útil de la notificación podría verse así:

{
  "action":"INSERT",
  "digest":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world@sha256:6ec128e26cd5..."
}

Cuando se envía una etiqueta de imagen nueva a Artifact Registry, la carga útil de las notificaciones se ve de la siguiente manera:

{
  "action":"INSERT",
  "digest":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world@sha256:6ec128e26cd5...",
  "tag":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world:1.1"
}

El mensaje identifica la imagen relevante mediante una tecla digest o tag.

Cuando se borra una etiqueta de imagen de Artifact Registry, la carga útil de la notificación puede tener el siguiente aspecto:

{
  "action":"DELETE",
  "tag":"us-east1-docker.pkg.dev/my-project/my-repo/hello-world:1.1"
}

El mensaje podría contener DELETE o INSERT como valores para la clave action.

¿Qué sigue?