Enruta eventos de Cloud Firestore a GKE

Vista previa — Eventarc for GKE destinations

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Un activador de Eventarc declara tu interés en un evento o conjunto de eventos determinado. Si quieres configurar el enrutamiento de eventos, especifica filtros para el activador, incluida la fuente del evento, y el servicio de destino de Google Kubernetes Engine (GKE) que se ejecuta en un clúster de GKE. Ten en cuenta que los objetivos solo pueden incluir servicios que se ejecuten en clústeres de GKE (públicos o privados) con extremos públicos. Para orientar los servicios en clústeres de GKE con extremos privados, enruta los eventos a extremos HTTP internos.

Eventarc entrega eventos al receptor de eventos en formato de CloudEvents a través de una solicitud HTTP.

Cloud Firestore admite Auth Context como un atributo de extensión para el formato de CloudEvents. Cuando creas un activador, puedes aplicar este atributo de tipo de evento para filtrar eventos con información de autenticación.

En estas instrucciones, se muestra cómo configurar el enrutamiento de eventos en el servicio de GKE que activa un evento Cloud Firestore directo. Para obtener más detalles, consulta la lista de eventos directos compatibles.

Nota: Si un proveedor de Google admite eventos directos y de registro de auditoría, te recomendamos que crees un activador que filtre el evento directo. Los eventos directos ofrecen una serie de ventajas sobre los eventos de registro de auditoría. Para obtener más información, consulta Rutas de eventos.

Antes de comenzar

Debes habilitar Workload Identity Federation for GKE en el clúster de GKE en el que se ejecuta el servicio de destino. Se requiere Workload Identity Federation for GKE para configurar el servidor de reenvío de eventos de forma correcta y es la forma recomendada de acceder a los servicios de Google Cloud desde aplicaciones que se ejecutan dentro de GKE debido a sus propiedades de seguridad y capacidad de administración mejoradas.

Federación de identidades para cargas de trabajo para GKE

Es posible que las aplicaciones que se ejecutan en GKE necesiten acceso a las APIs de Google Cloud. Workload Identity Federation for GKE permite que una cuenta de servicio de Kubernetes en el clúster de GKE actúe como una cuenta de servicio de IAM. Los Pods que usan la cuenta de servicio de Kubernetes configurada se autentican de forma automática como la cuenta de servicio de IAM cuando accedes a las APIs de Google Cloud. El uso de Workload Identity Federation for GKE te permite asignar identidades y autorizaciones distintas y detalladas para cada aplicación en el clúster. Ten en cuenta que se deben otorgar permisos específicos a la cuenta de servicio del activador de Eventarc. En este documento, consulta los pasos para crear una cuenta de servicio.

Para obtener más información sobre cómo habilitar y configurar Workload Identity Federation for GKE en los clústeres de GKE, consulta Usa Workload Identity Federation for GKE.

Reenvío de eventos

El servidor de reenvío de eventos de Eventarc extrae eventos nuevos de Eventarc y los reenvía al destino de GKE. Este componente actúa como un mediador entre la capa de transporte de Pub/Sub y el servicio de GKE. Funciona en servicios existentes y también admite servicios de señalización (incluidos los que no se exponen fuera del clúster completamente administrado) y simplifica la configuración y el mantenimiento. A nivel de la red, para recibir eventos en un servicio de GKE, no necesitas abrir el servicio al tráfico externo, ya que todos los eventos se entregan desde un origen que reside dentro del mismo clúster de GKE.

Ten en cuenta que Eventarc administra el ciclo de vida del servidor de reenvío de eventos y, si borras el servidor de reenvío de eventos por accidente, Eventarc restablecerá este componente.

Para cada activador que apunta a un destino de GKE, el servidor de reenvío de eventos (un Pod gke-forwarder configurado de forma específica) hace lo siguiente:

1. Usa la API de Pub/Sub para abrir una conexión StreamingPull al transportador del activador (un tema y una suscripción de Pub/Sub) y recibe eventos a medida que están disponibles.

2. Transforma los eventos en el formato de CloudEvents correcto y los codifica y los entrega como una solicitud HTTP POST al servicio de GKE de destino.

El agente de servicio de Eventarc necesita el permiso para ejecutar y actualizar con regularidad la instancia de gke-forwarder. Este permiso se debe otorgar una vez por proyecto. Para obtener más información, en este documento, consulta Habilita los destinos de GKE.

Prepárate para crear un activador

Para cada activador que se orienta a un servicio de GKE, Eventarc crea un componente de reenvío de eventos. Eventarc requiere permisos para instalar el componente y administrar recursos en el clúster de GKE. Antes de crear un activador de Eventarc para destinos de GKE, asegúrate de completar las siguientes tareas.

Console

1. En la página del selector de proyectos de la consola de Google Cloud, elige o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos creados durante este procedimiento, crea un proyecto en lugar de elegir un proyecto existente. Cuando termines, puedes borrar el proyecto si quitas todos los recursos asociados con él.

   Ir al selector de proyectos

2. Habilita las APIs de Eventarc, Eventarc Publising, Google Kubernetes Engine y Resource Manager.

   Habilita las API

3. Si corresponde, habilita la API relacionada con los eventos directos. Por ejemplo, para eventos Cloud Firestore , habilita la APICloud Firestore .

4. Si aún no tienes una, crea una cuenta de servicio administrada por el usuario y, luego, otórgale los roles y los permisos necesarios para que Eventarc pueda administrar los eventos para el servicio de destino.

   1. En la consola de Google Cloud, ve a la página Crear cuenta de servicio.

      Ve a Crear cuenta de servicio

   2. Elige tu proyecto.

   3. Escribe un nombre en el campo Nombre de cuenta de servicio. La consola de Google Cloud completa el campo ID de la cuenta de servicio en función de este nombre.

      Opcional: en el campo Descripción de la cuenta de servicio, escribe una descripción. Por ejemplo, Service account for event trigger.

   4. Haz clic en Crear y continuar.

   5. Para proporcionar el acceso adecuado, en la lista Seleccionar un rol, selecciona los roles de Identity and Access Management (IAM) necesarios para otorgar a tu cuenta de servicio. Si deseas obtener más información, consulta Roles y permisos para destinos de GKE.

      Para obtener roles adicionales, haz clic en Agregar otro rol y agrega cada rol adicional.

   6. Haz clic en Continuar.

   7. Para terminar de crear la cuenta, haz clic en Listo.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Habilita las APIs de Eventarc, Eventarc Publising, Google Kubernetes Engine y Resource Manager.

   gcloud services enable eventarc.googleapis.com \
       eventarcpublishing.googleapis.com \
       container.googleapis.com \
       cloudresourcemanager.googleapis.com

3. Si corresponde, habilita la API relacionada con los eventos directos. Por ejemplo, para los eventos Cloud Firestore , habilita firestore.googleapis.com.

4. Si aún no tienes una, crea una cuenta de servicio administrada por el usuario y, luego, otórgale los roles y los permisos necesarios para que Eventarc pueda administrar los eventos de tu destino de GKE.

   1. Cree la cuenta de servicio:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Reemplaza SERVICE_ACCOUNT_NAME por el nombre de la cuenta de servicio. Debe tener entre 6 y 30 caracteres y puede contener guiones y caracteres alfanuméricos en minúscula. Después de crear una cuenta de servicio, no podrás cambiar su nombre.

   2. Otorga los roles o los permisos de Identity and Access Management (IAM) necesarios. Si deseas obtener más información, consulta Roles y permisos para destinos de GKE.

Habilita los destinos de GKE

Para permitir que Eventarc administre recursos en el clúster de GKE, habilita los destinos de GKE y vincula la cuenta de servicio de Eventarc con los roles necesarios.

1. Habilita los destinos de GKE para Eventarc:

   gcloud eventarc gke-destinations init

2. Cuando se te solicite vincular los roles necesarios, ingresa y.

   Los siguientes roles están vinculados:

   • roles/compute.viewer
   • roles/container.developer
   • roles/iam.serviceAccountAdmin

Crear un activador

Puedes crear un activador de Eventarc con Google Cloud CLI o a través de la consola de Google Cloud.

Nota: El filtrado se hace a través de una concordancia exacta y no admite comodines ni expresiones regulares. Sin embargo, puedes usar la marca --event-filters-path-pattern en el siguiente comando de gcloud CLI o definir un patrón de ruta de acceso a través de la consola. Para obtener más información, consulta Información sobre los patrones de ruta de acceso.

Console

1. En la consola de Google Cloud, ve a la página Activadores de Eventarc.

   Ir a Activadores

2. Haz clic en Crear activador.
3. Escribe un nombre de activador.

   Este es el ID del activador y debe empezar con una letra. Puede contener hasta 63 letras en minúscula, números o guiones.

4. Para el Tipo de activador, elige Fuentes de Google.
5. En la lista Proveedor del evento, elige Cloud Firestore.

   Ten en cuenta que el nombre del proveedor de eventos que se usa en la documentación de Google Cloud asociada podría no tener el prefijo Cloud o Google Cloud. Por ejemplo, en la consola, Memorystore for Redis se denomina Google Cloud Memorystore para Redis.

6. En la lista Tipo de evento, en los eventos Directos, selecciona un tipo de evento.
7. En la lista Tipo de contenido de datos de eventos, elige la codificación de la carga útil del evento.

   Para los eventos directos de Cloud Firestore, debe ser application/protobuf y los datos de eventos son un array de bytes. Si deseas obtener más información sobre los mensajes protobuf para los eventos de Cloud Firestore, consulta Eventos comunes.

8. En la lista Región, elige la misma región que el servicio de Google Cloud que genera los eventos.

   Para obtener más información, consulta Ubicaciones de Eventarc.

9. Si corresponde al proveedor de eventos, haz clic en Agregar filtro y especifica lo siguiente:
   1. En el campo Atributo 1, según el evento directo que elijas, elige un ID de recurso que pueda funcionar como un filtro de evento.
   2. Elige un operador:
      • Igual
      • Patrón de ruta de acceso: aplicable a los recursos document (modo nativo) y entity (modo Datastore). Usa comodines para responder a los cambios que coinciden con un patrón. Un comodín * coincide con un solo segmento y un comodín de varios segmentos ** coincide con cero o más segmentos del patrón. Por ejemplo:

        /users/* o /users/{userId}	Coincide con todos los documentos de la colección /users. No coincide con documentos de subcolecciones como /users/marie/messages/33e2IxYBD9enzS50SJ68
        /users/**	Coincide con todos los documentos de la colección /users y los documentos de subcolecciones como /users/marie/messages/33e2IxYBD9enzS50SJ68

        Para obtener más información, consulta Información sobre los patrones de ruta de acceso.

   3. En el campo Valor del atributo 1, según el operador que elegiste, escribe el valor exacto o aplica un patrón de ruta de acceso.
   4. Si se aplican más filtros de atributos, haz clic en Agregar filtro y especifica los valores adecuados.
10. Elige la cuenta de servicio que invocará el servicio o el flujo de trabajo.

    O bien, puedes crear una cuenta de servicio nueva.

    Esto especifica el correo electrónico de la cuenta de servicio de Identity and Access Management (IAM) asociado con el activador y al que otorgaste antes roles específicos que requiere Eventarc.

11. En la lista Destino del evento, elige Kubernetes Engine.
12. Elige un servicio.
    

    Este es el nombre del servicio que recibe los eventos del activador. 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.

13. De manera opcional, puedes especificar la ruta de URL de servicio a la que 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, route/subroute.

14. Haz clic en Crear.

Después de que se crea un activador, los filtros de fuente del evento no se pueden cambiar. En su lugar, crea un activador nuevo y borra el anterior. Para obtener más información, consulta Administra activadores.

gcloud

Para crear un activador, ejecuta un comando gcloud eventarc triggers create junto con las marcas obligatorias y opcionales.

Las marcas difieren según si ejecutas Firestore en modo nativo o en modo Datastore. Para obtener más información, consulta Elige entre el modo nativo y el modo Datastore.

Modo nativo

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-gke-cluster=DESTINATION_GKE_CLUSTER \
    --destination-gke-location=DESTINATION_GKE_LOCATION \
    --destination-gke-namespace=DESTINATION_GKE_NAMESPACE \
    --destination-gke-service=DESTINATION_GKE_SERVICE \
    --destination-gke-path=DESTINATION_GKE_PATH \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="document=DOCUMENT" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Modo Datastore

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-gke-cluster=DESTINATION_GKE_CLUSTER \
    --destination-gke-location=DESTINATION_GKE_LOCATION \
    --destination-gke-namespace=DESTINATION_GKE_NAMESPACE \
    --destination-gke-service=DESTINATION_GKE_SERVICE \
    --destination-gke-path=DESTINATION_GKE_PATH \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="entity=ENTITY" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Reemplaza lo siguiente:

• TRIGGER: 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.

  Los activadores de Cloud Firestore para Eventarc solo están disponibles en ciertas ubicaciones y el activador debe estar en la misma ubicación que la base de datos de Cloud Firestore. Para obtener más información, consulta Ubicaciones de Eventarc y Ubicaciones de Cloud Firestore.

• DESTINATION_GKE_CLUSTER: el nombre del clúster de GKE en el que se ejecuta un servicio de GKE de destino que recibe eventos.
• DESTINATION_GKE_LOCATION: (opcional) la región de Compute Engine del clúster de GKE en el que se ejecuta el servicio de GKE de destino. Si no se especifica, se supone que el clúster es un clúster regional y se encuentra en la misma región que el activador.
• DESTINATION_GKE_NAMESPACE: el espacio de nombres en el que se ejecuta el servicio de GKE de destino (opcional). Si no se especifica, se usa el espacio de nombres default.
• DESTINATION_GKE_SERVICE: el nombre del servicio de GKE que recibe los eventos del activador. El servicio puede estar en cualquiera de las ubicaciones admitidas de GKE 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_GKE_PATH: la ruta de acceso relativa que especificas en el servicio de GKE de destino al que deben enviarse los eventos para el activador (opcional). Por ejemplo: /, /route, route, route/subroute.
• 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 solo si la acción se hace correctamente. Para obtener una lista de los tipos de eventos compatibles, consulta Tipos de eventos compatibles con Eventarc.
Cloud Firestore admite los siguientes tipos de eventos en solo modo nativo.
• google.cloud.firestore.document.v1.created: el evento se envía cuando se escribe en un documento por primera vez
• google.cloud.firestore.document.v1.created.withAuthContext: el evento con atributos de información de autenticación se envía cuando se escribe en un documento por primera vez
• google.cloud.firestore.document.v1.updated: el evento se envía cuando ya existe un documento y se cambia algún valor
• google.cloud.firestore.document.v1.updated.withAuthContext: el evento con atributos de información de autenticación se envía cuando ya existe un documento y se cambia algún valor
• google.cloud.firestore.document.v1.deleted: el evento se envía cuando se borra un documento
• google.cloud.firestore.document.v1.deleted.withAuthContext: el evento con atributos de información de autenticación se envía cuando se borra un documento
• google.cloud.firestore.document.v1.written: el evento se envía cuando se crea, actualiza o borra un documento
• google.cloud.firestore.document.v1.written.withAuthContext: el evento con atributos de información de autenticación se envía cuando se crea, actualiza o borra un documento.

Cloud Firestore admite los siguientes tipos de eventos en solo modo Datastore. Los objetos de datos de Firestore en modo Datastore se conocen como entidades.

• google.cloud.datastore.entity.v1.created: el evento se envía cuando se escribe una entidad en la primera vez
• google.cloud.datastore.entity.v1.created.withAuthContext: el evento con atributos de información de autenticación se envía cuando se escribe en una entidad por primera vez
• google.cloud.datastore.entity.v1.updated: el evento se envía cuando ya existe una entidad y se cambia algún valor
• google.cloud.datastore.entity.v1.updated.withAuthContext: el evento con atributos de información de autenticación se envía cuando ya existe una entidad y se cambia algún valor
• google.cloud.datastore.entity.v1.deleted: el evento se envía cuando se borra una entidad
• google.cloud.datastore.entity.v1.deleted.withAuthContext: el evento con atributos de información de autenticación se envía cuando se borra una entidad
• google.cloud.datastore.entity.v1.written: el evento se envía cuando se crea, actualiza o borra una entidad
• google.cloud.datastore.entity.v1.written.withAuthContext: el evento con atributos de información de autenticación se envía cuando se crea, actualiza o borra una entidad

• DATABASE: la base de datos de Firestore. Para ver el nombre de la base de datos predeterminada, usa (default).
• NAMESPACE (opcional): el espacio de nombres de la base de datos de Firestore. Para el espacio de nombres predeterminado en el modo Datastore, usa (default). Si no se especifica, se realiza una coincidencia de comodines (*) con cualquier caso.
• DOCUMENT (opcional): se aplica a instancias de bases de datos que se ejecutan solo en modo nativo. La ruta de la base de datos desde la que deseas recibir eventos desde la creación, actualización o eliminación de datos en esa ruta. El operador puede ser uno de los siguientes:
  • Iguales; por ejemplo, --event-filters="document=DOCUMENT"
  • Patrón de ruta de acceso; por ejemplo, --event-filters-path-pattern="document=DOCUMENT".

    Usa comodines para responder a los cambios en los documentos que coinciden con un patrón. Un comodín * coincide con un solo segmento y un comodín de varios segmentos ** coincide con cero o más segmentos del patrón. Por ejemplo:

    /users/* o /users/{userId}	Coincide con todos los documentos de la colección /users. No coincide con documentos de subcolecciones como /users/marie/messages/33e2IxYBD9enzS50SJ68
    /users/**	Coincide con todos los documentos de la colección /users y los documentos de subcolecciones como /users/marie/messages/33e2IxYBD9enzS50SJ68

    Para obtener más información, consulta Información sobre los patrones de ruta de acceso.
• ENTITY (opcional): se aplica a instancias de bases de datos que se ejecutan solo en el modo Datastore. La ruta de la base de datos desde la que deseas recibir eventos desde la creación, actualización o eliminación de datos en esa ruta. El operador puede ser uno de los siguientes:
  • Iguales; por ejemplo, --event-filters="document=ENTITY"
  • Patrón de ruta de acceso; por ejemplo, --event-filters-path-pattern="ENTITY=ENTITY"

    Para obtener más información, consulta Información sobre los patrones de ruta de acceso.

    Ten en cuenta que es posible que debas descartar los caracteres de IDs de tipo y de IDs de la entidad. Descartar un carácter permite que el filtro de eventos interprete el ID de forma correcta. Para obtener más información, consulta Escape de caracteres.

• EVENT_DATA_CONTENT_TYPE: la codificación de la carga útil del evento. Para los eventos directos de Firestore, debe ser application/protobuf y los datos de eventos son un array de bytes. Si deseas obtener más información sobre los mensajes protobuf para los eventos de Cloud Firestore, consulta Eventos comunes.
• SERVICE_ACCOUNT_NAME: el nombre de la cuenta de servicio administrada por el usuario.
• PROJECT_ID: Es el ID de tu proyecto de Google Cloud.

Notas:

• Para los eventos directos de Cloud Firestore, la codificación de la carga útil del evento es application/protobuf.
• 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.
• La marca --service-account se usa para especificar el correo electrónico de la cuenta de servicio de Identity and Access Management (IAM) asociado con el activador.

Ejemplo:

gcloud eventarc triggers create helloworld-trigger \
  --location=us-east1 \
  --destination-gke-cluster=gke-events-cluster \
  --destination-gke-location=us-east1-b \
  --destination-gke-namespace=default \
  --destination-gke-service=helloworld-events \
  --destination-gke-path=/ \
  --event-filters="type=google.cloud.firestore.document.v1.updated" \
  --event-filters="database=my-database" \
  --event-filters-path-pattern="document=users/my-document-*" \
  --event-data-content-type="application/protobuf" \
  --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

Con este comando, se crea un activador llamado helloworld-trigger para el evento identificado como google.cloud.firestore.document.v1.updated en la instancia de base de datos my-database que se ejecuta en modo nativo y se filtran los eventos de rutas de acceso document que coincidan con users/my-document-.

Nota: Aunque tu activador se crea de inmediato, puede tardar hasta dos minutos en propagarse y filtrar los eventos.

Enumera un activador

Para confirmar la creación de un activador, enumera los activadores de Eventarc con Google Cloud CLI o a través de la consola de Google Cloud.

Console

1. En la consola de Google Cloud, ve a la página Activadores de Eventarc.

   Ir a Activadores

   En esta página, se enumeran tus activadores en todas las ubicaciones y se incluyen detalles, como nombres, regiones, proveedores de eventos, destinos y mucho más.

2. Para filtrar tus activadores, haz lo siguiente:

   1. Haz clic en Filtrar o en el campo Filtrar activadores.
   2. En la lista Propiedades, elige una opción para filtrar los activadores.

   Puedes elegir una sola propiedad o usar el operador lógico OR para agregar más propiedades.

3. Para ordenar los activadores, junto con el encabezado de la columna compatible, haz clic en Ordenar.

gcloud

Ejecuta el siguiente comando para enumerar los activadores:

gcloud eventarc triggers list --location=-

Este comando enumera tus activadores en todas las ubicaciones y, además, incluye detalles como nombres, tipos, destinos y estados.

¿Qué sigue?

• Obtén más información acerca del uso de Eventarc y Cloud Firestore.
• Obtén más información sobre Eventarc.
• Aprende a administrar activadores.