Crear activadores con Eventarc

En esta página, se muestra cómo crear un activador de Eventarc para que un servicio de Cloud Run pueda recibir eventos de otro servicio de Google Cloud .

Eventarc es un servicio de Google Cloud que te permite compilar arquitecturas controladas por eventos sin tener que implementar, personalizar ni mantener la infraestructura subyacente.

Puedes crear un activador de Eventarc especificando filtros para el activador y configurando el enrutamiento del evento, incluidos el origen del evento y el servicio de Cloud Run de destino. Cuando el evento o conjunto de eventos especificados coinciden con los filtros, se invoca automáticamente tu servicio de Cloud Run en respuesta a los eventos. Un servicio que usa activadores de Eventarc se denomina servicio controlado por eventos. Los eventos enviados a tu servicio de Cloud Run se reciben en forma de solicitudes HTTP.

Los siguientes tipos de eventos pueden activar solicitudes a tu servicio:

Ubicación del activador

Cuando creas un activador de Eventarc, especificas una ubicación para él. Esta debe coincidir con la ubicación del recurso de Google Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu servicio de Cloud Run controlado por eventos en la misma región. Para conocer más, consulta Información sobre las ubicaciones de Eventarc.

Identidad del activador

Cuando creas un activador de Eventarc, especificas una cuenta de servicio de Identity and Access Management (IAM) para este. El activador usa esta cuenta de servicio como su identidad predeterminada. Te recomendamos que especifiques una cuenta de servicio administrada por el usuario y le otorgues los permisos mínimos necesarios.

Antes de comenzar

  1. Configura tu entorno de Cloud Run.

  2. Habilita las APIs de Artifact Registry, Cloud Build, Cloud Run Admin y Eventarc:

    Habilita las APIs

  3. Otorga los roles y permisos de IAM necesarios.

Crea un activador para los servicios

Después de implementar un servicio, puedes configurar un activador con la consola de Google Cloud , Google Cloud CLI o Terraform.

Console

  1. Implementa tu servicio de Cloud Run con contenedores o desde la fuente.

  2. En la consola de Google Cloud , ve a Cloud Run:

    Ir a Cloud Run

  3. En la lista de servicios, haz clic en un servicio existente.

  4. En la página de detalles del servicio, navega a la pestaña Activadores.

  5. Haz clic en Agregar activador y selecciona una opción.

  6. En el panel Activador de Eventarc, modifica los detalles del activador de la siguiente manera:

    1. En el campo Nombre del activador, ingresa un nombre para el activador o usa el nombre predeterminado.

    2. Selecciona un tipo de activador de la lista para especificar uno de los siguientes tipos de activadores:

      • Fuentes de Google para especificar activadores para Pub/Sub, Cloud Storage, Firestore y otros proveedores de eventos de Google.

      • Terceros para integrarte a proveedores externos a Google que ofrecen una fuente de Eventarc. Para obtener más información, consulta Eventos de terceros en Eventarc.

    3. Selecciona un proveedor de eventos de la lista Proveedor de eventos para elegir un producto que proporcione el tipo de evento que activará tu servicio. Para obtener la lista de proveedores de eventos, consulta Proveedores y destinos de eventos.

    4. Selecciona un tipo de evento de la lista Tipo de evento. La configuración del activador varía según el tipo de evento compatible. Para obtener más información, consulta Tipos de eventos.

    5. Si el campo Región está habilitado, selecciona una ubicación para el activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso de Google Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu servicio en la misma región. Consulta Información sobre las ubicaciones de Eventarc para obtener más detalles sobre las ubicaciones de activadores de Eventarc.

    6. En el campo Cuenta de servicio, selecciona una cuenta de servicio. Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca el servicio. La cuenta de servicio del activador de Eventarc debe tener el permiso para invocar tu servicio. De forma predeterminada, Cloud Run usa la cuenta de servicio predeterminada de Compute Engine.

    7. De manera opcional, especifica la ruta de URL del servicio a la que se enviará la solicitud entrante. Esta es la ruta de acceso relativa en el servicio de destino al que se deben enviar los eventos del activador. Por ejemplo: /, /route, route y route/subroute.

    8. De manera opcional, para habilitar los reintentos si falla el intento de entrega, selecciona la casilla de verificación Habilitar reintento en caso de error. De lo contrario, el comportamiento predeterminado es un solo intento de entrega sin reintentos. Para obtener más información, consulta Reintenta eventos.

    9. Una vez que hayas completado los campos obligatorios, haz clic en Guardar activador.

  7. Después de crear el activador, verifica su estado. Para esto, asegúrate de que haya una marca de verificación en la pestaña Activadores.

gcloud

  1. Implementa tu servicio de Cloud Run con contenedores o desde la fuente.

  2. Ejecuta el siguiente comando para crear un activador que filtre y enrute eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.

    Reemplaza lo siguiente:

    • TRIGGER_NAME: Es el ID del activador o un identificador completamente calificado.
    • LOCATION: la ubicación del activador de Eventarc. De forma alternativa, puedes establecer la propiedad eventarc/location; por ejemplo, gcloud config set eventarc/location us-central1.

      Para evitar problemas de rendimiento y residencia de datos, la ubicación debe coincidir con la ubicación del servicio de Google Cloud que genera eventos. Para obtener más información, consulta Ubicaciones de Eventarc.

    • DESTINATION_RUN_SERVICE: el nombre del servicio de Cloud Run que recibe los eventos para el activador. El servicio puede estar en cualquiera de las ubicaciones admitidas de Cloud Run y no es necesario que esté en la misma ubicación que el activador. Sin embargo, el servicio debe estar en el mismo proyecto que el activador y recibirá eventos como solicitudes POST HTTP enviadas a su ruta de URL raíz (/) cada vez que se genere el evento.
    • DESTINATION_RUN_REGION: (opcional) la ubicación de Cloud Run en la que se puede encontrar el servicio de Cloud Run de destino. Si no se especifica, se supone que el servicio se encuentra en la misma región que el activador.
    • EVENT_FILTER_TYPE: el identificador del evento. Se genera un evento cuando una llamada a la API para el método se hace de forma correcta. Para las operaciones de larga duración, el evento solo se genera al final de la operación, y únicamente si la acción se lleva a cabo correctamente. Para obtener una lista de los tipos de eventos compatibles, consulta Tipos de eventos de Google compatibles con Eventarc.
    • SERVICE_ACCOUNT_NAME: el nombre de la cuenta de servicio administrada por el usuario.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

    Notas:

    • La marca --event-filters="type=EVENT_FILTER_TYPE" es obligatoria. Si no se establece ningún otro filtro de eventos, se hace coincidir los eventos de todos los recursos.
    • EVENT_FILTER_TYPE no se puede cambiar después de su creación. Para cambiar EVENT_FILTER_TYPE, crea un activador nuevo y borra el anterior.
    • Cada activador tiene varios filtros de eventos, delimitados por comas en una marca --event-filters=[ATTRIBUTE=VALUE,…], o puedes repetir la marca para agregar más filtros. Solo los eventos que coinciden con todos los filtros se envían al destino. No se admiten comodines ni expresiones regulares. Sin embargo, cuando usas la marca --event-filters-path-pattern, puedes definir un patrón de ruta de acceso de recurso.
    • De manera opcional, para especificar un solo intento de entrega de eventos sin reintentos, usa la marca --max-retry-attempts. El único valor válido es 1. Si omites la marca, se aplica el comportamiento de reintento estándar. Para obtener más información, consulta Reintenta eventos.
    • Hay otras marcas disponibles. Para obtener más información, consulta gcloud eventarc triggers create

Terraform

Para crear un activador de Eventarc para un servicio de Cloud Run, consulta Crea un activador con Terraform.

Crea un activador para las funciones

Después de implementar una función, puedes configurar un activador con la consola de Google Cloud , Google Cloud CLI o Terraform.

Console

Cuando usas la consola de Google Cloud para crear una función, también puedes agregarle un activador. Sigue estos pasos para crear un activador para tu función:

  1. En la consola Google Cloud , ve a Cloud Run:

    Ir a Cloud Run

  2. Haz clic en Escribe una función y, luego, ingresa los detalles de la función. Para obtener más información sobre cómo configurar funciones durante la implementación, consulta Implementa funciones.

  3. En la sección Activador, haz clic en Agregar activador.

  4. Selecciona una opción.

  5. En el panel Activador de Eventarc, modifica los detalles del activador de la siguiente manera:

    1. Ingresa un nombre para el activador en el campo Nombre del activador o usa el nombre predeterminado.

    2. Selecciona un tipo de activador de la lista:

      • Fuentes de Google para especificar activadores para Pub/Sub, Cloud Storage, Firestore y otros proveedores de eventos de Google.

      • Terceros para integrarte a proveedores externos a Google que ofrecen una fuente de Eventarc. Para obtener más información, consulta Eventos de terceros en Eventarc.

    3. Selecciona un proveedor de eventos de la lista Proveedor de eventos para elegir un producto que proporcione el tipo de evento que activará tu función. Para obtener la lista de proveedores de eventos, consulta Proveedores y destinos de eventos.

    4. Selecciona un tipo de evento de la lista Tipo de evento. La configuración del activador varía según el tipo de evento compatible. Para obtener más información, consulta Tipos de eventos.

    5. Si el campo Región está habilitado, selecciona una ubicación para el activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso deGoogle Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu función en la misma región. Consulta Información sobre las ubicaciones de Eventarc para obtener más detalles sobre las ubicaciones de activadores de Eventarc.

    6. En el campo Cuenta de servicio, selecciona una cuenta de servicio. Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca la función. La cuenta de servicio del activador de Eventarc debe tener el permiso para invocar tu función. De forma predeterminada, Cloud Run usa la cuenta de servicio predeterminada de Compute Engine.

    7. De manera opcional, especifica la ruta de URL del servicio a la que se enviará la solicitud entrante. Esta es la ruta de acceso relativa en el servicio de destino al que se deben enviar los eventos del activador. Por ejemplo: /, /route, route y route/subroute.

    8. De manera opcional, para habilitar los reintentos si falla el intento de entrega, selecciona la casilla de verificación Habilitar reintento en caso de error. De lo contrario, el comportamiento predeterminado es un solo intento de entrega sin reintentos. Para obtener más información, consulta Reintenta eventos.

  6. Una vez que hayas completado los campos obligatorios, haz clic en Guardar activador.

  7. Haz clic en Crear.

  8. En la pestaña Fuente, edita el código fuente si es necesario y, luego, selecciona Guardar y volver a implementar.

gcloud

Cuando creas una función con gcloud CLI, primero debes implementarla y, luego, crear un activador. Sigue estos pasos para crear un activador para tu función:

  1. Ejecuta el siguiente comando en el directorio que contiene el código de muestra para implementar tu función:

    gcloud run deploy FUNCTION \
    --source . \
    --function FUNCTION_ENTRYPOINT \
    --base-image BASE_IMAGE_ID \
    --region REGION

    Reemplaza lo siguiente:

    • FUNCTION: Es el nombre de la función que implementas. Puedes omitir este parámetro por completo, pero se te solicitará el nombre si lo haces.

    • FUNCTION_ENTRYPOINT: Es el punto de entrada a tu función en tu código fuente. Este es el código que Cloud Run ejecuta cuando se ejecuta tu función. El valor de esta marca debe ser el nombre de una función o el nombre completamente calificado de la clase que esté en el código fuente.

    • BASE_IMAGE_ID: Es el entorno de la imagen base para tu función. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base de entornos de ejecución.

    • REGION: la región de Google Cloud en la que deseas implementar tu función. Por ejemplo, europe-west1.

  2. Ejecuta el siguiente comando para crear un activador que filtre y enrute eventos:

    gcloud eventarc triggers create TRIGGER_NAME \
    --location=LOCATION \
    --destination-run-service=FUNCTION \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --max-retry-attempts=1 \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.

    Reemplaza lo siguiente:

    • TRIGGER_NAME: Es el ID del activador o un identificador completamente calificado.
    • LOCATION: la ubicación del activador de Eventarc. De forma alternativa, puedes establecer la propiedad eventarc/location; por ejemplo, gcloud config set eventarc/location us-central1.

      Para evitar problemas de rendimiento y residencia de datos, la ubicación debe coincidir con la ubicación del servicio de Google Cloud que genera eventos. Para obtener más información, consulta Ubicaciones de Eventarc.

    • FUNCTION: Es el nombre de la función de Cloud Run implementada que recibe los eventos para el activador.
    • DESTINATION_RUN_REGION: (opcional) la ubicación de Cloud Run en la que se puede encontrar la función de Cloud Run de destino. Si no se especifica, se supone que la función se encuentra en la misma región que el activador.
    • EVENT_FILTER_TYPE: el identificador del evento. Se genera un evento cuando una llamada a la API para el método se hace de forma correcta. Para las operaciones de larga duración, el evento solo se genera al final de la operación, y únicamente si la acción se lleva a cabo correctamente. Para obtener una lista de los tipos de eventos compatibles, consulta Tipos de eventos de Google compatibles con Eventarc.
    • SERVICE_ACCOUNT_NAME: el nombre de la cuenta de servicio administrada por el usuario.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

    Notas:

    • La marca --event-filters="type=EVENT_FILTER_TYPE" es obligatoria. Si no se establece ningún otro filtro de eventos, se hace coincidir los eventos de todos los recursos.
    • EVENT_FILTER_TYPE no se puede cambiar después de su creación. Para cambiar EVENT_FILTER_TYPE, crea un activador nuevo y borra el anterior.
    • Cada activador tiene varios filtros de eventos, delimitados por comas en una marca --event-filters=[ATTRIBUTE=VALUE,…], o puedes repetir la marca para agregar más filtros. Solo los eventos que coinciden con todos los filtros se envían al destino. No se admiten comodines ni expresiones regulares. Sin embargo, cuando usas la marca --event-filters-path-pattern, puedes definir un patrón de ruta de acceso de recurso.
    • De manera opcional, para especificar un solo intento de entrega de eventos sin reintentos, usa la marca --max-retry-attempts. El único valor válido es 1. Si omites la marca, se aplica el comportamiento de reintento estándar. Para obtener más información, consulta Reintenta eventos.
    • Hay otras marcas disponibles. Para obtener más información, consulta gcloud eventarc triggers create

Terraform

Para crear un activador de Eventarc para una función de Cloud Run, consulta Crea un activador con Terraform.

Establece el plazo de confirmación de Pub/Sub

Las funciones de Cloud Run controladas por eventos se implementan con Eventarc en combinación con una suscripción a Pub/Sub. De forma predeterminada, el plazo de confirmación (ack) de esta suscripción a Pub/Sub es de 10 segundos. Este parámetro de configuración no es suficiente para muchas funciones y puede provocar ejecuciones duplicadas no deseadas.

Si activas tu servicio o función directamente con una suscripción de envío de Pub/Sub sin Eventarc, las suscripciones de envío directo comparten el mismo plazo de confirmación predeterminado de 10 segundos y el máximo de 600 segundos (10 minutos), lo que limita el tiempo de espera de la solicitud efectivo.

Te recomendamos que establezcas la fecha límite de ack para tu servicio o función en el valor máximo de 600 segundos de la siguiente manera:

Console

Después de implementar la función, sigue estos pasos para modificar el plazo de ack de la función:

  1. En la consola de Google Cloud , ve a Cloud Run:

    Ir a Cloud Run

  2. Busca la función que deseas actualizar en la lista Servicios y haz clic en ella para abrir sus detalles.

  3. Abre la pestaña Activadores.

  4. Haz clic en el nombre del activador para abrir Detalles del activador.

  5. Haz clic en el vínculo Tema para abrir el panel de edición de temas.

  6. Haz clic en el nombre del ID de suscripción para ir al panel de suscripción y, luego, en Editar en la parte superior de la página.

  7. Establece el valor de Acknowledgement Deadline en 600 y haz clic en Actualizar para guardar el cambio.

gcloud

Actualiza el plazo de ack por activador al valor máximo de 600 segundos. Ten en cuenta que los siguientes comandos hacen referencia a variables (TRIGGER_NAME y LOCATION) cuyos valores estableciste en los pasos anteriores.

## Per Cloud Run function:

# Update Ack Deadline to max (600s)
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$TRIGGER_NAME" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600

Realiza una actualización masiva en todos los activadores de servicios y funciones para establecer sus plazos de ack en 600 segundos:

### Match all Cloud Run service triggers and update all deadlines to 600s (max timeout)
### This will change ALL Cloud Run services and Cloud Run functions
TRIGGER_NAMES=($(gcloud eventarc triggers list | awk '/Cloud Run service/ {print $1}'))

if [ ${#TRIGGER_NAMES[@]} -eq 0 ]; then
  echo "No matching triggers found"
fi

for trigger in "${TRIGGER_NAMES[@]}"; do
echo "Updating ack deadline for trigger: $trigger"
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$trigger" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')

if [ -z "$SUBSCRIPTION_ID" ]; then
    echo "Error: Could not retrieve subscription ID for trigger: $trigger"
    continue # Skip to the next trigger
fi
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600
echo "Ack deadline updated for subscription: $SUBSCRIPTION_ID"
done

Visualiza el ID y la fuente del CloudEvent

Para ver el ID y la fuente de CloudEvent que activaron tu servicio, consulta los siguientes recursos en los registros del servicio de Cloud Run:

  • LogEntry.labels.run.googleapis.com/cloud_event_id
  • LogEntry.labels.run.googleapis.com/cloud_event_source

¿Qué sigue?