Qué significa la compatibilidad con versiones anteriores para la API de Dashboards de Kibana

Durante la vista previa técnica, la forma de la API podría cambiar entre versiones.[1] Eso ya no es así. Disponibilidad general (GA) significa:

• Compatibilidad total con versiones anteriores. Con el tiempo, se agregarán nuevos campos y tipos de panel, pero los campos y el comportamiento actuales se mantendrán sin cambios. Cualquier cambio futuro que rompa la compatibilidad será considerado con mucho cuidado y solo se introducirá en una nueva versión principal del stack.

• Listo para producción con soporte completo. La API ofrece las garantías completas de soporte de Elastic. Puedes usarla de manera segura en entornos de producción para despliegues automatizados, promoción del entorno y administración programática del dashboard.

Nuevos endpoints de la API Kibana para los paneles de etiquetas, markdown y enlaces

Elastic 9.5 también introduce un nuevo endpoint independiente para etiquetas, que permite categorizar y filtrar paneles. Ahora puedes administrarlos mediante programación a través de endpoints CRUD dedicados, lo que facilita organizar paneles a gran escala en todos los entornos.

Los nuevos endpoints de paneles Markdown y Enlaces ya están disponibles en Serverless y llegarán en la próxima versión de la pila (9.6).

¿Qué tipos de paneles soporta la API de Kibana Dashboards?

La API de dashboards admite todos los paneles por valor en la versión 9.5 (los definidos directamente en un dashboard, a diferencia de los paneles de biblioteca guardados para su reutilización). Cada tipo de panel admitido tiene un esquema tipificado y validado.

Tipo de panel

Estado

Gráficos XY

Con soporte

Métricas

Con soporte

Circular

Con soporte

Calibre

Con soporte

Mapa de calor

Con soporte

Tablas de datos

Con soporte

Mapa de árbol

Con soporte

Sesiones de Discover

Con soporte

Controles

Con soporte

Markdown

Con soporte

Enlaces

Con soporte

Paneles de ML

Con soporte

Paneles de Observability

Con soporte

Mapas

Próximamente

Vega

Próximamente

Cómo gestionar los dashboards de Kibana como código

La API de dashboards permite un flujo de trabajo completo de dashboards como código: exportar un dashboard como JSON limpio y diferenciable, hacer commit en Git como fuente de verdad, revisar los cambios en pull requests, y desplegar la misma definición en desarrollo, staging y producción. Una vez que un dashboard se administra como código, trata a Git como la única fuente de verdad: los cambios efectuados directamente en la UI se sobrescriben la próxima vez que despliegues.

El principal desafío al mover un dashboard entre espacios, clústeres o etapas es que los dashboards hacen referencia a objetos como Data view y visualizaciones de biblioteca mediante un ID. Debido a que estos ID se generan automáticamente y difieren de un entorno a otro, un dashboard exportado desde un entorno puede apuntar a objetos que no existen en otro. Hay tres formas de manejarlo, enumeradas aquí de la más a la menos automatizada:

• Usa Terraform. El proveedor Elastic Stack Terraform rastrea cada recurso y mapea automáticamente los ID por entorno, por lo que las referencias se mantienen estables mientras promocionas un dashboard desde el desarrollo hasta la producción.

• Definir por valor Paneles de lenguaje de búsqueda de Elasticsearch (ES|QL). La forma más portátil de construir un panel es definir su visualización con ES|QL directamente en el dashboard. Una consulta ES|QL lee los índices que se especifican en ella, por lo que el panel no contiene referencias externas a vistas de datos ni a objetos de biblioteca. El resultado es un dashboard totalmente autónomo y portátil.

• Asigna ID coincidentes. Si haces referencia a objetos guardados, como Data view o visualizaciones de biblioteca, créalos con un ID elegido usando PUT (upsert) en lugar de POST (que genera automáticamente un ID). Emplea ID legibles por humanos, como logs-prod, para que sean fáciles de reutilizar y reconocer en diferentes entornos.

Para un recorrido detallado de estos patrones de portabilidad y del flujo de trabajo completo de dashboards como código, consulta la documentación de Gestionar dashboards como código.

Crea un dashboard de Kibana con la API de dashboards usando PUT

Aquí hay un ejemplo rápido de crear un dashboard con un panel métrico usando PUT en lugar de POST para asignar un ID personalizado usando el nombre del dashboard (service-health-overview). La misma lógica funciona para crear visualizaciones independientes guardadas en la biblioteca.

Roadmap de la API de paneles de Kibana: Maps, Vega y endpoints independientes

Estamos ampliando activamente el alcance de la API. El siguiente paso es agregar compatibilidad con mapas y paneles Vega, incluyendo esquemas tipados para ellos. También estamos creando endpoints CRUD independientes para las sesiones de Discover (más allá de su compatibilidad actual como paneles del dashboard), Vega, Maps y Anotaciones, desacoplados del ciclo de vida del dashboard.

Para las definiciones completas de esquemas, visita la documentación de la API de Dashboards. Para los usuarios de Terraform, el proveedor Terraform de Elastic Stack es compatible con la API GA Dashboards.

Nota

1. Los endpoints de núcleo no han cambiado desde la vista previa técnica. Si construiste integraciones contra 9.4, funcionan en 9.5. Los únicos cambios incompatibles son dos menores que afectan al listado del dashboard y a los formatos de unidades de duración, documentados aquí.

Hoy, esa historia se vuelve mucho más sencilla. Ahora puedes usar las claves de API de Elastic Cloud para autenticarte directamente contra las API de Elasticsearch y Kibana en Elastic Cloud Serverless. Ahora puedes usar una sola credencial para gestionar los recursos de tu organización y ejecutar operaciones de datos, como consultas de ES|QL (lenguaje de búsqueda de Elasticsearch), ingesta de datos y generación de alertas.

Veamos por qué lo creamos, cómo diseñamos una capa de identidad distribuida en todo el mundo para hacerlo posible y cómo sienta las bases para la búsqueda entre proyectos.

La carga secreta de la gestión

Construir pipelines fiables de CI/CD, flujos de trabajo de GitOps o automatización de Terraform alrededor de plataformas de datos conlleva un costo oculto: la proliferación de secretos.

En el modelo anterior, los desarrolladores se enfrentaban a un proceso de autenticación fragmentado:

• Plano de control (claves de la API de Elastic Cloud): Claves con ámbito de organización que se emplean para crear proyectos, invitar a usuarios y gestionar la facturación a través de la API de Elastic Cloud.

• Plano de datos (claves de la API de Elasticsearch): Claves con alcance de proyecto creadas dentro de un proyecto Serverless específico para interactuar con las API de Elasticsearch y Kibana.

Esto significaba que tu script de despliegue tenía que autenticarse en Elastic Cloud, aprovisionar un proyecto Serverless, extraer una clave de API de Elasticsearch recién creada de ese proyecto específico y luego inyectar esa segunda clave en la aplicación o herramienta de automatización downstream, lo que resultaba en pipelines complejos, logs de auditoría fragmentados y un mayor riesgo de fugas de credenciales.

Autenticación unificada en Elastic Cloud Serverless

Con este lanzamiento, la división ha desaparecido para los proyectos Serverless. Ahora puedes crear una clave de la API de Elastic Cloud que esté explícitamente autorizada para las API de Cloud, Elasticsearch y Kibana.

• Antes: Una clave de API de Elastic Cloud era estrictamente un token del plano de control. Podía crear proyectos, gestionar la facturación e invitar a usuarios, pero tenía una limitación importante: no se podía usar para llamar a las API de Elasticsearch o Kibana dentro de esos proyectos. Siempre necesitabas una segunda clave específica del proyecto para las operaciones con datos.

• Ahora: Al optar por el acceso a la API de Cloud, Elasticsearch y Kibana cuando creas una clave de la API de Elastic Cloud, se elimina el límite rígido para Serverless. Esa clave de la API se convierte en una credencial verdaderamente unificada. Mantiene su capacidad para gestionar la infraestructura de tu organización, mientras obtiene acceso nativo para consultar, ingerir y analizar datos en cualquier proyecto Serverless autorizado.

Al unificarlo bajo una única clave de API de Elastic Cloud, obtienes una única identidad que puede ser delimitada, sometida a auditoría, rotada y revocada como una sola unidad. Cada llamada a la API, ya sea que aprovisione un nuevo proyecto o ejecute un ES|QL, aparece bajo la misma credencial en tus logs de auditoría, dándote un único rastro a seguir durante investigaciones de incidentes o revisiones de cumplimiento. La rotación de credenciales se convierte en una operación de un solo paso en lugar de una actualización coordinada a través de secretos separados del plano de control y del plano de datos. Y dado que las asignaciones de roles son por proyecto, una única clave puede abarcar varios proyectos, gestionando la ingesta en tu proyecto de observabilidad y ejecutando consultas en tu proyecto de seguridad, sin tener que gestionar credenciales separadas para cada uno.

Es importante destacar que unificado no significa todopoderoso. Al usar la carga útil role_assignments, puedes asignar una clave unificada estrictamente a un solo proyecto y a un rol específico (como solo lectura), cerciorando que el radio de alcance permanezca completamente contenido si alguna vez se expone una credencial. Si un desarrollador se marcha o una aplicación es desactivada, puedes revocar una sola clave de la Consola de Elastic Cloud, terminando inmediatamente el acceso tanto en el plano de control como en todos los proyectos asociados de Elasticsearch.

(Nota: Para despliegues gestionados/alojados en Elastic Cloud Hosted, las claves de API de la cloud siguen gestionando solo el plano de control. La función para extenderlo a las API de pila alojadas está previsto para una versión futura).

Automatiza tus flujos de trabajo

Los primeros pasos son simples. Puedes configurarlo completamente a través de la consola de Elastic Cloud o automatizarlo empleando la API de Elastic Cloud.

El proceso de la UI sigue igual, pero ahora puedes seleccionar acceso a la API de Cloud, Elasticsearch y Kibana bajo la asignación de rol del proyecto.

Aquí te mostramos cómo crear una clave unificada mediante programación empleando la API de Elastic Cloud. Fíjate en el array application_roles, ya que es el que otorga acceso nativo al plano de datos de Elasticsearch:

Una vez creada, simplemente pasas esta misma clave en el encabezado Authorization: ApiKey tanto a api.elastic-cloud.com como a tus puntos finales específicos de Serverless Elasticsearch.

Bajo el capó: construyendo una capa de identidad distribuida

Hacer que una clave API de Cloud funcione tanto en el plano de control como en el plano de datos no es tan simple como pasar un token. Implica resolver un reto fundamental de los sistemas distribuidos.

Históricamente, las claves de API de Cloud residían en un clúster de seguridad global centralizado. Esto funciona bien para las operaciones del plano de control donde una latencia más alta es aceptable. Sin embargo, las solicitudes de datos de Elasticsearch requieren una latencia ultrabaja. No podemos permitirnos un viaje de ida y vuelta alrededor del mundo hasta un plano de control central para validar cada consulta de búsqueda o solicitud de ingesta.

Para resolverlo, implementamos una nueva arquitectura de autenticación respaldada por un almacén de datos distribuido a nivel mundial. El siguiente diagrama de secuencia muestra a un cliente enviando una consulta a Elasticsearch con una clave de API de Elastic Cloud, lo que ilustra cómo la autenticación se lleva a cabo íntegramente dentro de la región local, sin necesidad de un viaje de ida y vuelta al plano de control global. Elasticsearch delega la autenticación al servicio regional de IAM, que valida la clave y comprueba las asignaciones de roles en una réplica local de la base de datos distribuida en todo el mundo. Una vez autorizado, Elasticsearch ejecuta la consulta y devuelve los resultados al cliente.

Persistencia distribuida a nivel global

En lugar de depender únicamente de un clúster de seguridad centralizado, las claves de la API de Elastic Cloud y las definiciones de roles asociadas ahora se almacenan permanentemente en una base de datos distribuida en todo el mundo y de alta disponibilidad. Esta base de datos sincroniza los datos de administración de identidad y acceso (IAM) a través del plano de control global y los planos de datos regionales donde realmente se ejecutan tus proyectos sin servidor.

Validación local con IAM regional

Cuando tu cliente envía una solicitud a Elasticsearch usando una clave de API de Elastic Cloud, la solicitud no se remite al plano de control mundial. En su lugar, es redirigido al nuevo servicio regional de IAM. Valida la clave contra la réplica de la base de datos local, asegurando que la autenticación ocurra con una latencia cercana a cero y esté completamente aislada de las interrupciones del plano de control mundial.

Mapping dinámico de roles

La autenticación es solo la mitad del camino; el sistema también tiene que autorizar la solicitud. El servicio regional de IAM traduce instantáneamente tus asignaciones de rol a nivel de cloud (por ejemplo, application_roles) en privilegios nativos de Elasticsearch. Elasticsearch puede entonces autorizar y ejecutar la solicitud localmente, sin necesidad de un índice .security local.

La base para la búsqueda entre proyectos

Esta arquitectura de identidad distribuida es un pilar fundamental para el futuro de la plataforma Elastic.

Como la identidad y el acceso ahora están unificados y sincronizados globalmente, contamos con el marco de trabajo necesario para transferir tu identidad de forma segura entre diferentes proyectos. Esto permite las próximas funcionalidades de búsqueda entre proyectos (CPS) para Serverless.

Con CPS, podrás consultar datos que abarcan varios proyectos serverless remotos, como combinar cargas de trabajo de seguridad y observabilidad, tan fácilmente como si fueran un solo set de datos. Al utilizar claves API unificadas, el sistema puede evaluar automáticamente tus permisos en todos los proyectos a la vez, sin que tengas que configurar relaciones de confianza complejas, certificados ni duplicar credenciales en cada proyecto de destino.

Más información

¿Listo para simplificar tu stack?

• Lee la documentación sobre las claves de la API de Elastic Cloud para saber cómo asignar acceso a la pila.

• Consulta la referencia Crear clave de la API (Elastic Cloud API) para automatizar la generación de claves.

• Consulta las claves de API de Elastic para ver una comparación completa de los tipos de claves disponibles en toda la Platform de Elastic.

Empieza o continúa construyendo en Elastic Cloud hoy mismo.

Descargo de responsabilidad

El lanzamiento y el momento de cualquier característica o funcionalidad descrita en esta publicación quedan a exclusivo criterio de Elastic. Es posible que alguna característica o funcionalidad que no esté disponible en este momento no se lance a tiempo o no se lance en absoluto.

Los flujos de trabajo de Elastic son un motor de automatización integrado dentro de Kibana que te permite definir procesos multipaso usando una configuración sencilla de YAML. Cada flujo de trabajo puede activarse según una programación o un evento, o como una herramienta en Elastic Agent Builder, y cada paso puede llamar a las API de Kibana, consultar Elasticsearch o transformar datos.

Usaremos los recuentos de vistas del dashboard como ejemplo concreto, pero el mismo patrón aplica a cualquier métrica expuesta a través de la API de objetos guardados de Kibana.

Requisitos previos

• Elastic Cloud o un clúster autogestionado ejecutando la versión 9.3

• Flujos de trabajo activados (Configuración avanzada)

Paso 1: explora los datos sin procesar en Herramientas de desarrollo

Antes de crear cualquier cosa, entendamos qué datos tenemos. Kibana almacena la mayor parte de su configuración y metadatos como objetos guardados en un índice interno dedicado. Una de las cosas que Kibana rastrea de esta manera es el número de vistas del dashboard, mediante un tipo especial de objeto guardado llamado contadores de uso. Puedes consultarlas directamente desde las Herramientas de desarrollo:

La respuesta tiene el siguiente aspecto:

El campo counterName es el ID del dashboard y count es el recuento acumulado de vistas para ese dashboard en ese día específico. Kibana crea un objeto de contador por dashboard al día; puedes ver el sufijo de fecha en el ID del objeto (...viewed:server:20260310). El conteo aumenta a lo largo del día a medida que los usuarios abren el dashboard.

En lugar de replicar este modelo de documento diario en nuestro índice, crearemos un documento por cada ejecución del flujo de trabajo. Cada documento registra cuántas vistas había acumulado ese dashboard durante el día en el momento de la captura.

Paso 2: Crear el índice de destino

Necesitamos un índice para almacenar las snapshots de la vista del dashboard. El siguiente comando lo crea con mapeos explícitos para que podamos agregar y visualizar más tarde. Ejecuta esto en herramientas de desarrollo:

Usarkeyword mapeos para ID y nombres permite agregaciones. Usar integer para view_count es un valor predeterminado seguro, ya que Kibana restablece el contador diariamente, por lo que alcanzar el límite de 32 bits (más de 2 mil millones de vistas en un solo día) no es una preocupación realista. Todavía admite operaciones numéricas, como max, avg y min, entre otras.

Paso 3: Crear el flujo de trabajo

Ve a Stack Management > Flujos de trabajo > Nuevo flujo de trabajo, y pega la siguiente configuración YAML del flujo de trabajo:

En la próxima sección, hagamos un desglose del flujo de trabajo paso a paso.

Cómo funciona el flujo de trabajo

Desencadenantes

El flujo de trabajo se ejecuta mediante un desencadenante programado cada 30 minutos. Esto nos proporciona datos temporales sin saturar la API.

fetch_dashboard_views

Usakibana.request para llamar a la API de objetos guardados de Kibana. No hace falta configurar la autenticación: el motor de flujos de trabajo añade automáticamente los encabezados correctos según el contexto de ejecución.

index_each_dashboard (foreach)

Itera sobre la matrizsaved_objects devuelta por el paso anterior. El elemento actual en cada iteración está disponible como foreach.item. Dentro del bucle, ejecutamos dos pasos anidados para cada dashboard.

1. fetch_dashboard_name:

Resuelve el título legible para los humanos del dashboard al llamar a GET /api/saved_objects/dashboard/{id}. Agregamos on-failure: continue: true para que, si un dashboard se eliminó pero aún tiene contadores de vistas, el bucle continúe en lugar de fallar toda la ejecución.

2. index_doc:

Indexa cada documento usando POST /dashboard-views/_doc (sin un ID explícito), lo que permite que Elasticsearch genere automáticamente los ID. Esto crea un nuevo documento en cada ejecución, lo que crea un historial del número de vistas a lo largo del tiempo en lugar de sobreescribir el snapshot anterior.

Dos cosas que vale la pena destacar:

• El campo captured_at usa el filtro de fecha para formatear la marca de tiempo como ISO 8601. Sin ella, el valor sale como un texto de fechas en JavaScript, como Tue Mar 10 2026 05:03:47 GMT+0000, que Elasticsearch no asigna como fecha.

• El view_count usa la sintaxis ${{ }} con | plus: 0 para preservar el tipo numérico. Usar {{ }} lo mostraría como un texto, lo que impediría realizar operaciones matemáticas en el dashboard.

La UI te permite depurar fácilmente cada uno de los pasos del flujo de trabajo.

Paso 4: Crea el dashboard de estadísticas

Una vez que el flujo de trabajo se haya ejecutado varias veces y se hayan recopilado los datos, crea un nuevo dashboard en Kibana usando la Data view de vistas del dashboard.

Algunos paneles para empezar:

• Los dashboards más vistos: Usa un Gráfico de barras con dashboard_name en el eje X y last_value(view_count) en el eje Y. Aquí se muestra el número actual de vistas diarias por dashboard.

• Vistas a lo largo del tiempo: usa un gráfico de líneas con captured_at en el eje X y last_value(view_count) en el eje Y, desglosado por dashboard_name. Dado que cada ejecución agrega un nuevo documento, usa el último valor para obtener el recuento máximo por cubetas de tiempo en lugar de sumar duplicados.

• Snapshot actual: usa una tabla de datos con el captured_at más reciente para mostrar los recuentos de vistas más recientes en todos los dashboards.

Dado que cada flujo de trabajo crea un nuevo documento, puedes filtrar por intervalo de tiempo para analizar la actividad en períodos específicos, comparar semana a semana o configurar alertas cuando un dashboard caiga por debajo de un umbral de visitas.

Conclusión

Elastic Flujos de trabajo es una buena opción para este tipo de recopilación periódica de datos porque tanto el origen (API de Kibana) como el destino (Elasticsearch) son nativos, lo que significa cero gestión de credenciales. El motor de flujo de trabajo maneja la autenticación automáticamente para los pasos kibana.request y elasticsearch.request, por lo que lo único que escribes es la lógica.

Recursos

• Flujos de trabajo de Elastic

• API de Kibana

Gestión de dependencias en Elastic

En Elastic, tenemos que gestionar cientos o incluso miles de repositorios, tanto privados como públicos. Cuando se descubre una CVE crítica, necesitamos respuestas y acciones inmediatas: ¿qué repositorios son vulnerables? ¿Con qué rapidez podemos solucionarlos? Además de la seguridad, surgen cuestiones relacionadas con la productividad: ¿cómo podemos propagar rápidamente el lanzamiento de una nueva versión de un paquete a todos los repositorios que dependen de él, sin dedicar demasiado tiempo a tareas manuales?

El disparador inicial para buscar formas de hacer la gestión de dependencias fue la necesidad de establecer una base segura con actualizaciones automatizadas para reducir los CVEs. Después de considerar cuidadosamente las soluciones para la gestión de dependencias, empezamos a trabajar en una infraestructura autohospedada. Usábamos nuestro propio clúster de Kubernetes para ejecutar Mend Renovate Community Self-Hosted. La idea era poder ofrecer una plataforma de gestión de dependencias a la que nuestros usuarios pudieran acceder de forma autónoma.

El experimento inicial tuvo éxito, así que cada vez más equipos comenzaron a implementar nuestra plataforma y usarla en el ciclo de vida de sus repositorios diarios para actualizaciones y parches CVE. Esto sucedió tan rápido que pronto alcanzamos el límite de nuestra instalación autohospedada.

El reto: ¿Cómo podemos escalar una plataforma de gestión de dependencias en una gran organización con una cantidad significativa de repositorios?

Nuestra plataforma de gestión de dependencias procesaba un repositorio a la vez, entonces el modelo de procesamiento secuencial no podía seguir el ritmo debido a la gran cantidad de repositorios que tenemos. Ya habíamos identificado que el problema residía en el concepto de que una sola instancia de nuestra herramienta de gestión de dependencias podría procesar nuestra gran y siempre creciente lista de repositorios. Los repositorios esperaban en una cola, a veces durante muchas horas. Más del 50 % de nuestros repositorios ni siquiera se procesaban diariamente. Eso significa que más del 50 % de nuestros repositorios esperaron más de 24 horas entre los escaneos.

Los grandes repositorios creaban cuellos de botella mayores, debido a sus grandes bases de código y a sus múltiples PRs abiertas. Los eventos de webhook de GitHub interrumpieron la secuencia. Automerge se volvió poco confiable debido a que el tiempo de escaneo era impredecible. Habíamos hecho una promesa a nuestros usuarios sobre la frecuencia de los escaneos y no pudimos cumplirla.

La decisión de integrarnos internamente: satisfacer las necesidades únicas de escalabilidad y seguridad de Elastic

Aunque considerábamos opciones comerciales, como la edición Renovate autohospedada empresarial de Mend, internamente en Elastic teníamos algunas iniciativas clave en marcha.

Nuestra decisión de crear una plataforma interna se basó en el reconocimiento de que solo una solución altamente personalizada podría satisfacer los requisitos específicos e innegociables de Elastic:

1. Inversión en nuestra plataforma interna para desarrolladores: en ese momento, ya habíamos comenzado a invertir considerablemente en nuestra plataforma interna para desarrolladores. Estábamos discutiendo y diseñando formas en las que cada uno de nuestros servicios pudiera encajar. Esto significaba que queríamos probar nuestras propias reglas y prácticas para nuestra plataforma de gestión de dependencias. Además de eso, entraban en juego nuevas pautas y queríamos diseñar la plataforma antes de los eventos.

2. Integración nativa y personalización del flujo de trabajo: requeríamos una integración directa con nuestras herramientas y procesos internos. Por ejemplo, queríamos centralizar la configuración como código con nuestro Catálogo de servicios (Backstage). Tenemos necesidades específicas sobre el uso de Backstage con las que queríamos que nuestra plataforma fuera compatible. Así que, aunque fuera posible usar las API de Renovate autohospedadas junto con nuestra automatización de Backstage, esto no cubriría completamente nuestros procesos internos.

3. Seguridad en profundidad específica de Elastic: nuestro cumplimiento de seguridad estricto requería mecanismos personalizados adaptados a nuestro ecosistema. Estábamos trabajando para fortalecer nuestro uso de “identidades no humanas”. Las medidas de seguridad implementadas implicaban que los métodos no estándar de autenticación en GitHub no funcionarían con una herramienta comercial que no fuera compatible con esta implementación interna. Nuestro flujo de trabajo incluía la implementación de un patrón de cifrado secreto de flujo de trabajo principal-secundario y el uso de tokens de GitHub transitorios y de un solo uso. La creación interna era la única forma práctica de integrar estas capas de seguridad únicas y minimizar la superficie de ataque en nuestro complejo entorno multinube.

La solución: Orquestación de flujo de trabajo para la gestión de dependencias

Nuestra solución partió del hecho de que queríamos basarnos en la herramienta de gestión de dependencias que ya usábamos, no reemplazarla y buscar otras soluciones. Había mostrado signos de su potencial, y su flexibilidad es importante para las distintas necesidades de toda nuestra organización. Consideramos diferentes soluciones, y lo que nos ayudó a decidir fueron las necesidades grandes y a veces especiales que tenemos que cubrir. Decidimos crear una plataforma de gestión de dependencias fiable y escalable, donde cada repositorio se procesa por sí mismo, lo que eliminaría los cuellos de botella y nos prepararía para crecer.

Diseñamos la plataforma mediante tres principios fundamentales:

1. Procesamiento en paralelo

Cada repositorio tiene su propio entorno de procesamiento de gestión de dependencias. No más colas. Nuestra concurrencia solo está limitada por la cantidad de recursos que gastamos. También aplicamos una programación distribuida inteligente para evitar que GitHub limite la velocidad.

2. Autoservicio

Usamos nuestro Catálogo de servicios (Backstage) para incorporar y gestionar automáticamente cualquier repositorio nuevo. Usamos nuestra propia definición de recursos para darle al usuario final la opción de seleccionar con qué frecuencia se procesará un repositorio, cuántos recursos quiere asignar a sus programaciones y si quiere desactivar o volver a activar el procesamiento por cualquier motivo. Planeamos agregar más opciones así a medida que las necesidades de nuestros usuarios evolucionen y se adapten mejor a la nueva instalación.

3. Alcance secreto reducido y aislamiento del espacio de nombres

Para aumentar la seguridad, suministramos a nuestros pods de gestión de dependencias tokens efímeros de GitHub que se generan al inicio de cada flujo de trabajo. Además, aislamos nuestras cargas de trabajo en espacios de nombres específicos para que solo se les proporcionen los secretos necesarios. Controlamos a qué secretos puede acceder cada uno de los flujos de trabajo de gestión de dependencias mediante Kubernetes RBAC. También utilizamos el cifrado para propagar el token de GitHub desde los flujos de trabajo principales a los secundarios.

Reconstruimos nuestra plataforma mediante Kubernetes y, al aprovechar el poder de Kubernetes, Argo Workflows impulsa la lógica de nuestros procesos, y Renovate CLI está configurado para escanear y procesar un repositorio a la vez.

La belleza: estamos utilizando proyectos de código abierto probados en batalla de una manera original, lo que ofrece nuevos ejemplos de trabajo para todos esos proyectos y, al mismo tiempo, aumenta la velocidad de desarrollo y consolida la reducción de CVE para nuestros equipos.

Arquitectura de gestión de dependencias: Cuatro microservicios

La plataforma cuenta con cuatro componentes personalizados:

Operador de los flujos de trabajo (Go/Kubebuilder)

Un operador de Kubernetes que gestiona el ciclo de vida del flujo de trabajo a través de tres definiciones de recursos personalizados (CRD):

• CRD de RepoConfig: Única fuente de verdad para la configuración de repositorios.

Así es como se define RepoConfig en el operador:

Y así es como se vería una instancia de RepoConfig:

• CRD principal: Gestiona CronWorkflows para escaneos programados.

Dentro del bucle de reconciliación del controlador principal, nos aseguramos de que los flujos de trabajo se creen y se mantengan actualizados o incluso se eliminen si es necesario.

En primer lugar, obtienes algunos ajustes configurados globalmente para los flujos de trabajo:

Se asegura de que un configmap de mutex esté actualizado para evitar que flujos de trabajo similares se ejecuten juntos:

Luego crea un gestor de flujo de trabajo que es la estructura que creará o actualizará los CronWorkflows y las plantillas de flujo de trabajo:

• CRD infantil: Gestiona las plantillas de flujo de trabajo con recursos por repositorio.

El controlador secundario tiene un deber de reconciliación similar al del padre, pero esta vez es responsable de las plantillas de flujo de trabajo en el espacio de nombres secundario que se activarán por los flujos de trabajo principales.

El patrón de controlador múltiple proporciona una clara separación: el controlador RepoConfig maneja la incorporación/eliminación, el controlador principal administra la programación y el controlador secundario maneja las plantillas de ejecución.

Puerta de enlace de eventos de GitHub (Go)

Un proxy de webhook seguro que recibe webhooks de GitHub, verifica firmas, filtra por organización/repositorio y los redirige a Argo Events. Creamos 10 sensores distintos que respondían a interacciones en paneles de dependencias, eventos de relaciones públicas y actualizaciones de paquetes.

Este gateway permite la integración con las aplicaciones de GitHub de la siguiente manera:

• Verifica las firmas entrantes de webhook de GitHub para mayor seguridad.

• Reenvía eventos válidos al EventSource de Argo Events con todos los encabezados relevantes y la autenticación.

• También configuramos un AuthSecret en EventSource y lo proporcionamos como un encabezado Bearer en las solicitudes reenviadas.

• Proporcionamos logging, métricas y lógica de reintentos.

Realiza varias validaciones en cada solicitud de evento de GitHub.

Se asegura de que algunos atributos HTTP estén presentes:

Al mismo tiempo que valida la firma de cada solicitud y su organización:

Por último, se redirige a Argo Events según el tipo de evento:

En lo que respecta a Argo Events, 10 sensores vigilan el EventBus de Argo Events en busca de nuevos eventos.

Luego, el script aplica la lógica de cada sensor:

Backstage Syncer (Go)

Esto sondea nuestro catálogo de servicios (Backstage) para las entidades de recursos reales del repositorio, las transforma en CRD de RepoConfig y mantiene la Platform sincronizada con los cambios de configuración. Los cambios se aplican en tres minutos.

Por último, escribe esos datos en instancias de RepoConfig.

Base de flujos de trabajo (mixta: JavaScript, Go, Helm)

La capa base contiene gráficos de Helm, configuraciones de JavaScript, un contenedor Go para Renovate CLI con soporte de cifrado y un indexador APK personalizado para paquetes Alpine.

Configuración de autoservicio

Los equipos configuran sus repositorios de manera declarativa a través de Backstage:

Los grupos de recursos asignan CPU y memoria en función del tamaño del repositorio:

• PEQUEÑO: CPU de 500m, memoria 1Gi.

• MEDIO: CPU 1000m, memoria 2Gi.

• GRANDE: CPU de 2000 m, memoria de 4 Gi.

La configuración está bajo control de versiones, es auditable y se aplica automáticamente.

El patrón padre-hijo

El modelo de ejecución usa un patrón de flujo de trabajo primario y secundario:

• Flujo de trabajo principal: CronWorkflow ligero que se ejecuta según lo programado. Cifra los secretos, determina si se debe ejecutar un escaneo y pasa la configuración al secundario.

• Flujo de trabajo infantil: pod efímero donde se ejecuta Renovate CLI. Asigna recursos de forma dinámica, descifra secretos de forma aislada y se cierra al completar la tarea.

Esta separación proporciona seguridad (los secretos se cifran en el nivel superior), optimización de recursos (los niveles superiores utilizan recursos mínimos) y escalabilidad (los niveles inferiores se ejecutan en paralelo).

Los resultados

Transformación del rendimiento

• Antes: Un repositorio a la vez, algunos repositorios no se procesaban posiblemente incluso por un día o más, menos de 1000 escaneos por día.

• Después: más de 100 escaneos simultáneos, normalmente 8000 escaneos y hasta 10 000 escaneos registrados al día, limitados únicamente por la cantidad de recursos que estamos dispuestos a invertir y cómo gestionamos los límites de GitHub.

Rentabilidad

Sin embargo, por extraño que parezca, ejecutar 8000 pods al día puede darte el mismo resultado de forma mucho más económica que tener un pod de larga duración que intenta lograr los mismos resultados.

En la configuración anterior, ejecutábamos una sola instancia que, en un buen día, realizaba entre 500 y 600 escaneos. Al mismo tiempo, debido al hecho de que se ejecutarían diferentes tipos de repositorios en el mismo pod, necesitábamos dimensionar el pod para los más grandes. Ese tamaño sería mucho mayor que nuestra oferta extra grande actual, que usa 8 CPU para el pod y 16 GB de memoria.

Para cumplir con la salida diaria actual, el pod único tendría que ejecutarse durante 12 días. Entonces, al comparar el costo de un solo pod que funciona durante 12 días con 8000 pods de nuestro tamaño “MEDIO” funcionando cada día, nuestro nuevo diseño es mucho más eficiente para la misma salida de escaneos:

Métrica

Escenario A (Flujos de trabajo)

Escenario B (El pod único de larga duración)

Configuración

8000 pods (1 vCPU / 2 GB)

1 pod (8 vCPU / 16 GB)*

Duración

10 minutos cada uno

12 días continuos

Tiempo total de trabajo

1333 horas de procesamiento

288 horas de computación

Costo total

$65,83

$113,75

Sin embargo, tomemos en consideración que nuestro valor predeterminado para nuestras cargas de trabajo está configurado en “PEQUEÑO”, con la gran mayoría ejecutándose con éxito con 0.5 CPU y 1 G de RAM, y solo unos pocos necesitan cambiar a mediano y grande. Veamos qué sucede si el 60 % de nuestras cargas de trabajo se ejecutan en “PEQUEÑO”, el 30 % en “MEDIANO” y el 10 % en “GRANDE”, lo cual está más cerca de la realidad.

Métrica

Escenario A (Enjambre mixto)

Escenario B (El corredor de fondo)

Estrategia

8000 pods (tamaños mixtos)

1 pod (8 vCPU / 16 GB)*

Duración

10 minutos cada uno

12 días continuos

Costo total

$52,66

$113,75

Ahorros

$61,09 (54 % más barato)

—

Podemos ver que, con la misma salida, somos mucho más rentables en nuestra configuración actual.

Seguridad mejorada

• Tokens efímeros de GitHub (minutos de exposición versus días).

• Aislamiento del espacio de nombres con límites de control de acceso basado en roles (RBAC).

• Cifrado secreto en reposo en flujos de trabajo principales.

• Acceso directo a Vault eliminado.

Rendimiento previsible

Con una frecuencia de escaneo garantizada, finalmente podemos establecer Objetivos de nivel de servicio (SLO). La autofusión funciona de forma confiable. Los equipos confían en la plataforma para cumplir lo prometido.

Decisiones arquitectónicas clave

Aquí tienes algunas de las decisiones clave de diseño que moldearon el aspecto de la plataforma.

• ¿Por qué flujos de trabajo padre-hijo?

Adoptamos este patrón para aplicar una estrategia de defensa en profundidad. Al restringir las credenciales de alto valor (como los secretos de GitHub App) a un espacio de nombres dedicado y bloqueado, usamos RBAC para asegurarnos de que los pods de ejecución efímeros no puedan acceder arbitrariamente a datos confidenciales. Las vulnerabilidades recientes de la cadena de suministro (por ejemplo, los ataques "Shai Hulud" de integración continua/entrega continua [CI/CD]) han demostrado la importancia de aislar entornos de ejecución que ejecutan scripts dinámicos desde el almacén de credenciales.

Simultáneamente, este desacoplamiento permite una optimización granular de recursos. Los flujos de trabajo "primarios" actúan como orquestadores ligeros con una huella mínima, mientras que los flujos de trabajo "secundarios" manejan el escaneo de dependencia con uso intensivo de computación. Esta separación simplifica la gestión de ciclo de vida al permitirnos aplicar una lógica de reconciliación distinta a cada capa, lo que brinda a los usuarios control sobre los parámetros de ejecución (hijo) mientras conservamos el control administrativo sobre la programación y la infraestructura de seguridad (principal).

• ¿Por qué es de autoservicio?

Eliminar a nuestro equipo como un cuello de botella para la configuración del repositorio fue un requisito crítico. Nuestra misión era diseñar una plataforma escalable y de autoservicio capaz de admitir diversos casos de uso. Nos dimos cuenta de que actuar como filtros para cada cambio de configuración era insostenible, dado el gran volumen de repositorios. En su lugar, adoptamos una filosofía de habilitación: proporcionar los “rieles” (infraestructura y barandillas) mientras capacitamos a los usuarios para conducir los “trenes” (ejecución y personalización). Creemos que este cambio hacia la autonomía del equipo mejora significativamente la productividad al permitir a los usuarios adaptar el sistema a sus necesidades operativas específicas.

• ¿Por qué el patrón de Kubernetes Operator?

Como se mencionó anteriormente, un principio de diseño fundamental era garantizar que la plataforma fuera completamente de autoservicio. Necesitábamos un mecanismo automatizado para capturar la intención de los usuarios (como alternar escaneos, ajustar la frecuencia de programación o ajustar los límites de recursos de tiempo de ejecución) y propagar instantáneamente esos cambios a los flujos de trabajo subyacentes. Al anticipar los requisitos futuros, el sistema también necesitaba ser fácilmente extensible.

Para lograr esto, desarrollamos un Operador de Kubernetes para la gestión de dependencias personalizado. Al utilizar CRD como interfaz para la configuración, establecimos un bucle de reconciliación nativo de Kubernetes. Este operador monitoriza continuamente el estado deseado definido por el usuario y orquesta automáticamente las actualizaciones necesarias en la infraestructura del flujo de trabajo. Esto asegura una operación fluida y basada en eventos, donde la lógica de la plataforma maneja toda la complejidad detrás de escena.

• ¿Para qué sirve diseñar una puerta de enlace de eventos de GitHub?

Adoptar una arquitectura impulsada por eventos (EDA) fue esencial para la capacidad de respuesta de la plataforma. Aunque CronWorkflows proporcionaba un calendario de referencia fiable, requeríamos la agilidad para gestionar ejecuciones ad hoc, como que los usuarios activaran escaneos manualmente a través del panel. Para lograr esto, necesitábamos una puerta de enlace de ingestión dedicada para validar la integridad de la carga útil y enrutar las solicitudes de manera inteligente.

Evaluamos las soluciones existentes, incluido el GitHub EventSource nativo para Argo, pero identificamos riesgos significativos en cuanto a la sobrecarga operativa y las estrictas cuotas de la API de GitHub (por ejemplo, los límites de webhook por repositorio). En consecuencia, creamos una puerta de enlace personalizada para desacoplar nuestra infraestructura de estas limitaciones.

Crucialmente, esta puerta de enlace sirvió como un punto de control de tráfico estratégico durante nuestra migración. Actuó como un interruptor, lo que nos permitió realizar una implementación gradual y granular (cambio de tráfico) del sistema heredado a la nueva infraestructura. Esto garantizó que la incorporación de miles de repositorios fuera un proceso controlado y sin riesgos, en lugar de un cambio radical.

Lecciones aprendidas

Algunas lecciones que hemos aprendido van de la mano con el código fuente de Elastic:

1. El cliente primero: las plataformas están diseñadas para los usuarios. Por eso es importante tener las necesidades de los usuarios como prioridad número uno. Esto moldea la plataforma en una infraestructura y aplicaciones diseñadas de manera eficiente que reducen la fricción con los usuarios, simplifican el escalado de la plataforma y facilitan la adopción.

2. Espacio-tiempo: a veces el camino de menor resistencia lleva a arenas movedizas. Inicialmente, intentamos optimizar el modelo de procesamiento secuencial existente, pero esto no resolvió nuestros problemas. De hecho, solo introdujo más complejidad y cabos sueltos. La audaz decisión de rediseñar la plataforma con procesamiento paralelo requirió un esfuerzo inicial significativo. Sin embargo, finalmente allanó el camino para un crecimiento sostenible de la plataforma y prácticamente eliminó el tedioso trabajo administrativo diario.

3. Depende: una plataforma no puede operar de forma aislada. Su éxito depende de qué tan bien se integre con el ecosistema más amplio. En nuestro caso, la integración con Backstage fue crítica, ya que sirve como la única fuente de verdad para la incorporación fluida de servicios. Del mismo modo, conectarnos a Artifactory nos permitió gestionar las actualizaciones de paquetes privados de manera eficiente, y la lista de integraciones esenciales continúa.

4. Progreso, perfección simple: a lo largo de la implementación, sometimos constantemente a prueba nuestras hipótesis iniciales y nos adaptamos a los nuevos obstáculos que iban surgiendo. En lugar de quedar paralizados por el perfeccionismo, adoptamos un enfoque iterativo, abordamos los desafíos uno por uno y ajustamos nuestra estrategia de migración para cumplir con las condiciones del mundo real.

Lo que se viene

La entrega de la plataforma nos permite realizar un trabajo más significativo que nos ayudará a mejorar la UX y la eficiencia de nuestra plataforma. Algunos ejemplos son:

• Aumento y protección de la adopción de la fusión automática

La característica de fusión automática acelera significativamente la velocidad del equipo al eliminar las tareas manuales tediosas. Sin embargo, tenemos que asegurarnos de que haya barreras estrictas para garantizar que este aumento de velocidad no se haga a expensas de la seguridad.

• Mejora la observabilidad en torno a la experiencia del usuario final

Una prioridad fundamental de nuestra hoja de ruta es mejorar la observabilidad, no solo a nivel de plataforma, sino también específicamente desde la perspectiva del usuario final. Aunque capturar métricas de infraestructura es sencillo, comprender la experiencia real del usuario requiere conocimientos más profundos. Estamos trabajando para definir los indicadores de rendimiento (KPI) centrados en el usuario de núcleo para que nuestra telemetría pueda detectar los puntos de fricción y los problemas de rendimiento antes de que se conviertan en quejas de los usuarios.

• Elimina obstáculos para una mayor adopción

De cara al futuro, nuestra prioridad es identificar y eliminar cualquier barrera que dificulte la adopción de plataformas. Ya sea que esto requiera desarrollar nuevas integraciones o desplegar conjuntos de características específicas, estamos comprometidos con la planificación basada en datos. Construimos con éxito una plataforma diseñada para escalar; nuestro enfoque ahora cambia a maximizar su potencial.

El panorama general

El proyecto de flujos de trabajo de gestión de dependencias demuestra un principio más amplio: cuando necesites escalar herramientas de código abierto más allá de su modelo de despliegue predeterminado, los patrones nativos de Kubernetes proporcionan un camino a seguir.

Al adoptar:

• CRDs para configuración.

• Operadores para la gestión de ciclo de vida.

• Arquitectura basada en eventos para mayor capacidad de respuesta.

• GitOps para el despliegue.

Creamos una orquestación que escala independientemente de la cantidad de repositorios que gestiona. El rendimiento de escanear un solo repositorio es el mismo tanto si gestionamos 100 como si gestionamos 1000.

Cuando se anuncia un CVE crítico, ahora tenemos respuestas en minutos, no en horas. Esa es la diferencia entre un cuello de botella y una ventaja competitiva.

Agradecimientos

Esta plataforma se basa en excelentes herramientas de código abierto:

• Kubebuilder: el marco de trabajo de código abierto que usamos para poner en marcha nuestros operadores Kubernetes que inician y orquestan nuestros flujos de trabajo. [1][2]

• Backstage: el marco de trabajo de código abierto sobre el cual hemos construido nuestro catálogo de servicios y que utilizamos como nuestra fuente de la verdad. [1][2]

• Argo Workflows y Argo Events: la suite de código abierto que usábamos para orquestar procesos complejos y agregar procesamiento dinámico basado en eventos. [1][2][3][4]

• Renovate CLI: la herramienta de gestión de dependencias de código abierto que procesa nuestros repositorios. [1][2]

* El modelo de precios de AWS Fargate se usó como referencia para el costo de un solo pod, aunque nuestras cargas de trabajo no se ejecutan necesariamente en AWS y se ejecutan en clústeres de Kubernetes completos.

Además, estos casos de uso suelen ser sensibles al tiempo, y pasar por las etapas típicas de desarrollo (crear una rama de código y luego esperar una nueva versión) es un proceso que consume mucho tiempo.

Entonces, ¿y si pudiéramos hacer todo este proceso solo con una llamada a la API, o mejor aún, con solo unos clics en Kibana?

Interfaz de Reglas de Consulta

Elasticsearch 8.10 introdujo Reglas de Consulta y Retriever de Reglas. Estas son herramientas diseñadas para inyectar resultados fijados en las consultas sin afectar la clasificación de los resultados orgánicos según reglas. Solo agregan lógica de negocio encima de los resultados de forma declarativa y sencilla.

Algunos casos de uso comunes para las Reglas de Consulta son:

• Destacar anuncios u ofertas promocionadas: Mostrar artículos en oferta o patrocinados en la parte superior.

• Excluyendo por contexto o geolocalización: ocultar ciertos objetos cuando la normativa local no permite mostrarlos.

• Priorizar los resultados clave: Cerciorar de que las búsquedas populares o fijas estén siempre en la cima, independientemente del ranking orgánico.

Para acceder a la interfaz e interactuar con estas herramientas, necesitas hacer clic en el menú lateral de Kibana e ir a Reglas de consulta, en Relevancia:

Cuando aparezca el menú de reglas de consulta, haz clic en Crear tu primer conjunto de reglas:

A continuación, tienes que nombrar tu conjunto de normas.

La forma para definir cada regla tiene tres componentes clave:

• Criterios: Las condiciones que deben cumplir para que la norma se aplique. Por ejemplo, "cuando el campo query_string contiene el valor Christmas" o "cuando el campo del país es CO."

• Acción: Esto es lo que quieres que ocurra cuando se cumplan las condiciones. Puede fijar (fijar un documento a los resultados superiores) o excluir (ocultar un documento).

• Metadatos: Estos son los campos que acompañan la consulta cuando se ejecuta. Pueden incluir la información del usuario (como ubicación o idioma), así como datos de búsqueda (query_string). Estos son los valores que emplean los criterios para decidir si aplicar o no una regla.

Ejemplo: objetos populares

Imaginemos que tenemos un sitio de comercio electrónico con diferentes artículos. Al analizar las métricas, observamos que uno de los artículos más vendidos en la categoría de consolas es el "DualShock 4 Wireless Controller", especialmente cuando los usuarios buscan las palabras clave "PS4" o "PlayStation 4". Así que decidimos poner este producto encima de los resultados cada vez que un usuario busque esas palabras clave.

Primero, indexemos los documentos de cada elemento usando una solicitud Bulk API:

Si no intervenimos en la consulta, el elemento suele aparecer en cuarto lugar. Aquí está la pregunta:

Y aquí están los resultados

Vamos a crear una regla de consulta para cambiar esto. Primero, vamos a agregarlo al reglamento de esta manera:

O solicitud API equivalente:

Para usar el conjunto de reglas en nuestra consulta, debemos usar un tipo de regla de consulta. Este tipo de consulta se compone de dos partes principales:

• match_criteria: Estos son los metadatos que se emplean para comparar con la consulta del usuario. En este ejemplo, el conjunto de reglas se activa cuando el campo query_string tiene el valor "PlayStation 4."

• Consulta: La consulta real que se usará para buscar y obtener los resultados orgánicos.

De este modo, primero ejecutas la consulta orgánica y luego Elasticsearch aplica las reglas de tu conjunto de reglas:

Ejemplo: metadatos basados en el usuario

Otra aplicación interesante de las Reglas de Consulta es usar metadatos para mostrar documentos específicos basar en información contextual del usuario o del sitio web.

Por ejemplo, imaginemos que queremos destacar artículos o ventas personalizadas basándonos en el nivel de fidelidad del usuario, representado como un valor numérico.

Podemos hacerlo ingiriendo estos metadatos directamente en la consulta para que las reglas se activen cuando dicho valor cumple ciertos criterios.

Primero, indexaremos un documento que solo los usuarios con un alto nivel de lealtad puedan ver:

Ahora, creemos una nueva regla dentro del mismo conjunto de reglas para que cuando el loyalty_level sea igual o superior a 80, el elemento aparezca encima de los resultados.

Almacena la regla y el reglamento.

Aquí está la solicitud REST equivalente:

Ahora, al ejecutar una consulta, necesitamos incluir el nuevo parámetro loyalty_level en los metadatos. Si se cumple la condición de la regla, el nuevo documento aparecerá encima de los resultados.

Por ejemplo, al enviar una consulta donde el loyalty_level es 80:

Veremos el documento de lealtad encima de los resultados:

En el caso siguiente, dado que el nivel de lealtad es 70, la regla no se cumple y el objeto no debería aparecer arriba:

Aquí están los resultados:

Ejemplo: exclusión inmediata

Supongamos que nuestro mando inalámbrico DualShock 4 (ID 2) está temporalmente indisponible y no puede vender. Así que, en lugar de eliminar manualmente el documento o esperar a que algún proceso de datos se active, el equipo de negocio decide eliminarlo de los resultados de búsqueda mientras tanto.

Usaremos un proceso similar al que acabamos de aplicar a los objetos populares, pero esta vez en lugar de seleccionar Fijado, elegiremos Excluir. Esta regla funciona como una especie de lista negra. Cambia los criterios a Siempre para que la exclusión funcione cada vez que se ejecute la consulta.

La regla debería ser así:

Almacena la regla y el conjunto de reglas para aplicar los cambios. Aquí está la solicitud REST equivalente:

Ahora, cuando ejecutamos la consulta de nuevo, verás que el elemento ya no aparece en los resultados, aunque la regla anterior sea fijarlo. Esto se debe a que las exclusiones tienen prioridad sobre los resultados de fijación.

Conclusión

Las Reglas de Consulta facilitan mucho ajustar la relevancia sin ningún cambio en el código. La nueva interfaz Kibana tepermite realizar estos cambios en cuestión de segundos, dándote a ti y a tu equipo empresarial más control sobre los resultados de búsqueda.

Más allá del comercio electrónico, las Reglas de Consulta pueden impulsar muchos otros escenarios: destacar guías de resolución de problemas en portales de soporte, mostrar documentos internos clave en bases de conocimiento, promover noticias de última hora en sitios de noticias o filtrar ofertas de empleo o contenido caducado. Incluso pueden hacer cumplir normas de cumplimiento, como ocultar material restringido por rol de usuario o región.

En este blog, emplearemos Mastra para construir un agente de conocimiento que recuerda lo que dicen los usuarios y puede recuperar información relevante más adelante, empleando Elasticsearch como backend de memoria y recuperación. Puedes extender fácilmente este mismo concepto a casos de uso reales, piensa en agentes de soporte que puedan recordar conversaciones y resoluciones pasadas, permitiéndoles adaptar las respuestas a usuarios específicos o a soluciones superficiales más rápido basar en contextos previos.

Sigue aquí para ver cómo construirlo paso a paso. Si te pierdes o simplemente quieres ejecutar un ejemplo terminado, echa un vistazo al repositorio aquí.

¿Qué es Mastra?

Mastra es un framework TypeScript de código abierto para construir agentes de IA con partes intercambiables para razonamiento, memoria y herramientas. Su función de recuperación semántica permite a los agentes recordar y recuperar interacciones pasadas almacenando mensajes como incrustaciones en una base de datos vectorial. Esto permite a los agentes mantener el contexto y la continuidad de la conversación a largo plazo. Elasticsearch es un excelente almacén vectorial para habilitar esta función, ya que soporta una búsqueda vectorial densa eficiente. Cuando se activa la recuperación semántica, el agente extrae mensajes pasados relevantes en la ventana de contexto del modelo, permitiendo que el modelo emplee ese contexto recuperado como base para su razonamiento y respuestas.

Lo que necesitas para empezar

• Nodo v18+

• Elasticsearch (versión 8.15 o posterior)

• Clave API de Elasticsearch

• Clave API de OpenAI

Nota: Necesitarás esto porque la demo usa el proveedor OpenAI, pero Mastra soporta otros SDKs de IA y proveedores de modelos comunitarios, así que puedes cambiarlo fácilmente según tu configuración.

Construyendo un proyecto de Mastra

Emplearemos la CLI integrada de Mamra para proporcionar el andamiaje de nuestro proyecto. Ejecuta el comando:

Recibirás un conjunto de indicaciones, que empiezan por:

1. Pon un nombre a tu proyecto.

2. Podemos mantener este valor predeterminado; No dudes en dejar esto en blanco.

3. Para este proyecto, emplearemos un modelo proporcionado por OpenAI.

4. Selecciona la opción "Saltar por ahora" porque almacenaremos todas nuestras variables de entorno en un archivo '.env' que configuraremos en un paso posterior.

5. También podemos saltar esta opción.

Una vez que termines de inicializar, podemos pasar al siguiente paso.

Instalación de dependencias

A continuación, necesitamos instalar algunas dependencias:

• ai - Paquete básico de SDK de IA que proporciona herramientas para gestionar modelos de IA, prompts y flujos de trabajo en JavaScript/TypeScript. Mastra está construido sobre el SDK de IA por Vercel, así que necesitamos esta dependencia para permitir la interacción del modelo con tu agente.

• @ai-sdk/openai - Plugin que conecta el SDK de IA con modelos OpenAI (como GPT-4, GPT-4o, etc.), habilitando llamadas API usando tu clave API OpenAI.

• @elastic/elasticsearch - Cliente oficial de Elasticsearch para Node.js, se emplea para conectarse a tu Elastic Cloud o a un clúster local para operaciones de indexación, búsqueda y vectores.

• dotenv - Carga variables de entorno desde un .env archivar en process.env, permitiendo inyectar de forma segura credenciales como claves API y endpoints Elasticsearch.

Configuración de variables de entorno

Crea un archivo .env en el directorio raíz de tu proyecto si aún no ves uno. Alternativamente, puedes copiar y renombrar el ejemplo .env que proporcioné en el repositorio. En este archivo, podemos agregar las siguientes variables:

Eso concluye la configuración básica. Desde aquí, ya puedes empezar a construir y orquestar agentes. Vamos un paso más allá y agregaremos Elasticsearch como la capa de almacenamiento y búsqueda vectorial.

Agregar Elasticsearch como almacenamiento vectorial

Crea una nueva carpeta llamada stores y dentro, agrega este archivo. Antes de que Mastra y Elastic lanzaran una integración oficial de almacenamiento vectorial de Elasticsearch, Abhi Aiyer(CTO de Mestra) compartió esta clase prototipo temprana llamada ElasticVector. Simplemente, conecta la abstracción de memoria de Mamra con las densas capacidades vectoriales de Elasticsearch, para que los desarrolladores puedan incluir Elasticsearch como base de datos vectorial para sus agentes.

Echemos un vistazo más profundo a las partes importantes de la integración:

Ingestión del cliente Elasticsearch

Esta sección define la clase ElasticVector y configura la conexión cliente de Elasticsearch con soporte tanto para despliegues estándar como serverless.

• ElasticVectorConfig extends ClientOptions: Esto crea una nueva interfaz de configuración que hereda todas las opciones del cliente de Elasticsearch (como node, auth, requestTimeout) y agrega nuestras propiedades personalizadas. Esto significa que los usuarios pueden pasar cualquier configuración válida de Elasticsearch junto con nuestras opciones específicas para serverless.

• extends MastraVector: Esto permite ElasticVector heredar de la clase base de MastraVector de Mastra, que es una interfaz común a la que se ajustan todas las integraciones de almacenamiento vectorial. Esto garantiza que Elasticsearch se comporte como cualquier otro backend de vectores Mastra desde la perspectiva del agente.

• private client: Client: Esta es una propiedad privada que contiene una instancia del cliente JavaScript Elasticsearch. Esto permite que la clase hable directamente con tu grupo.

• isServerless y deploymentChecked: Estas propiedades trabajan juntas para detectar y almacenar en caché si estamos conectados a un despliegue serverless o estándar de Elasticsearch. Esta detección ocurre automáticamente en el primer uso, o puede configurar explícitamente.

• constructor(config: ClientOptions): Este constructor toma un objeto de configuración (que contiene tus credenciales de Elasticsearch y configuraciones opcionales de serverless) y lo emplea para inicializar el cliente en la línea this.client = new Client(config).

• super(): Esto llama constructor base de Mastra, por lo que hereda el registro, los asistentes de validación y otros ganchos internos.

En este punto, Mastra sabe que hay un nuevo almacén vectorial llamado ElasticVector

Detección del tipo de despliegue

Antes de crear índices, el adaptador detecta automáticamente si estás usando Elasticsearch estándar o Elasticsearch Serverless. Esto es importante porque los despliegues serverless no permiten la configuración manual de shards.

Qué pasa:

• Primero comprueba si pusiste explícitamente isServerless en la configuración (se salta la auto-detección).

• Llama a la API info() de Elasticsearch para obtener información del clúster

• Comprueba el build_flavor field (los despliegues serverless devuelven serverless)

• Vuelve a revisar el lema si no hay variedad de build disponible

• Almacena en caché el resultado para evitar llamadas repetidas a la API

• Por defecto se aplica al despliegue estándar si falla la detección

Ejemplo de uso:

Creación del almacén de "memoria" en Elasticsearch

La función siguiente establece un índice Elasticsearch para almacenar incrustaciones. Comprueba si el índice ya existe. Si no, crea uno con el mapeo que aparece abajo y contiene un campo dense_vector para almacenar incrustaciones y métricas de similitud personalizadas.

Algunas cosas a tener en cuenta:

• El parámetro dimension es la longitud de cada vector de incrustación, que depende del modelo de incrustación que estés usando. En nuestro caso, generaremos incrustaciones usando el modelo text-embedding-3-small de OpenAI, que genera vectores de tamaño 1536. Usaremos esto como nuestro valor por defecto.

• La variable similarity empleada en el mapeo a continuación se define a partir de la función auxiliar const similarity = this.mapMetricToSimilarity(metric), que toma el valor del parámetro metric y lo convierte en una palabra clave compatible con Elasticsearch para la métrica de distancia elegida.

  • Por ejemplo: Mastra emplea términos generales para similitud vectorial como cosine, euclidean, y dotproduct. Si pasáramos la métrica euclidean directamente al mapeo de Elasticsearch, generaría un error porque Elasticsearch espera que la palabra clave l2_norm represente la distancia euclidiana.

• Compatibilidad sin servidor: El código omite automáticamente los ajustes de shard y réplica para despliegues sin servidor, ya que estos son gestionados automáticamente por Elasticsearch Serverless.

Almacenar una nueva recordación o nota tras una interacción

Esta función toma nuevas incrustaciones generadas tras cada interacción, junto con los metadatos, y luego las inserta o actualiza en el índice usando la API bulk de Elastic. La API bulk agrupa múltiples operaciones de escritura en una sola solicitud; Esta mejora en nuestro rendimiento de indexación garantiza que las actualizaciones se mantengan eficientes a medida que la memoria de nuestro agente sigue creciendo.

Consulta de vectores similares para la recuperación semántica

Esta función es el núcleo de la característica de recuperación semántica. El agente emplea búsqueda vectorial para encontrar incrustaciones almacenadas similares dentro de nuestro índice.

Bajo el capó:

• Ejecuta una consulta kNN (k-vecinos más cercanos) usando la API knn en Elasticsearch.

• Recupera los vectores top-K similares al vector de consulta de entrada.

• Opcionalmente, aplica filtros de metadatos para reducir resultados (por ejemplo, buscar solo dentro de una categoría o rango de tiempo específico)

• Devuelve resultados estructurados que incluyen el ID del documento, el puntaje de similitud y los metadatos almacenados.

Creación del agente del conocimiento

Ahora que vimos la conexión entre Mastra y Elasticsearch a través de la integración ElasticVector , creemos el propio Knowledge Agent.

Dentro de la carpeta agents, crea un archivo llamado knowledge-agent.ts. Podemos empezar conectando nuestras variables de entorno e inicializando el cliente Elasticsearch.

Aquí, nosotros:

• Usa dotenv para cargar nuestras variables desde nuestro archivo .env .

• Comprueba si las credenciales de Elasticsearch se están inyectando correctamente y podemos establecer una conexión exitosa con el cliente.

• Pasa el endpoint de Elasticsearch y la clave API al constructor ElasticVector para crear una instancia de nuestro almacén vectorial que definimos antes.

• Opcionalmente, especifica isServerless: true si usas Elasticsearch Serverless. Esto omite el paso de detección automática y mejora el tiempo de arranque. Si se omite, el adaptador detectará automáticamente el tipo de despliegue en el primer uso.

A continuación, podemos definir el agente usando la clase Agent de Mastra.

Los campos que podemos definir son:

• name y instructions: Darle una identidad y función primaria.

• model: Estamos usando la gpt-4o de OpenAI a través del paquete @ai-sdk/openai .

• memory:

  • vector: Apunta a nuestra tienda Elasticsearch, así que los embeddings se almacenan y recuperan desde allí.

  • embedder: Qué modelo usar para generar incrustaciones

  • semanticRecall Las opciones deciden cómo funciona la retirada:

    • topK: Cuántos mensajes semánticamente similares recuperar.

    • messageRange: Cuánto de la conversación incluir en cada partido.

    • scope: Define el límite de la memoria.

Casi termino. Solo tenemos que agregar este agente recién creado a nuestra configuración de Mestra. En el archivo llamado index.ts, importa el agente de conocimiento e insértalo en el campo agents .

Los otros campos incluyen:

• storage: Este es el almacén interno de datos de Mamra para historial de ejecuciones, métricas de observabilidad, puntajes y cachés. Para más información sobre el almacenamiento de mastras, visita aquí.

• logger: Mastra emplea Pino, que es un registrador JSON estructurado y ligero. Captura eventos como inicios y atajada de agentes, llamadas y resultados de herramientas, errores y tiempos de respuesta de los LLM.

• observability: Controla el rastreo de IA y la visibilidad de ejecución de los agentes. Sigue lo siguiente:

  • Inicio/final de cada paso de razonamiento.

  • Qué modelo o herramienta se empleó.

  • Entradas y salidas.

  • Puntajes y evaluaciones

Probando al agente con Mastra Studio

¡Felicidades! Si llegaste hasta aquí, estás listo para ejecutar este agente y probar sus capacidades semánticas de recuperación. Por suerte, Mastra ofrece una interfaz de chat integrada para que no tengamos que crear la nuestra.

Para iniciar el servidor de desarrollo de Mestra, abre un terminal y ejecuta el siguiente comando:

Tras el empaquetado y el arranque inicial del servidor, debería proporcionarte una dirección del Playground.

Pega esta dirección en tu navegador y te recibirás con Mastra Studio.

Selecciona la opción de knowledgeAgent y charla sin parar.

Para una prueba rápida y ver si todo está correctamente cableado, dale información como: "El equipo anunció que el rendimiento de ventas en octubre subió un 12%, impulsado principalmente por renovaciones empresariales. El siguiente paso es ampliar su alcance a clientes de gama media." Después, inicia un nuevo chat y haz una pregunta como: "¿En qué segmento de clientes dijimos que debemos centrarnos a continuación?" El agente de conocimiento debería ser capaz de recordar la información que le diste en el primer chat. Deberías ver una respuesta como:

Ver una respuesta así significa que el agente almacenó con éxito nuestro mensaje anterior como incrustaciones en Elasticsearch y lo recuperó después usando búsqueda vectorial.

Inspección del almacenamiento de memoria a largo plazo del agente

Ve a la pestaña memory en la configuración de tu agente en Mastra Studio. Esto te permite ver lo que tu agente aprendió con el tiempo. Cada mensaje, respuesta e interacción que se incrusta y almacena en Elasticsearch pasa a formar parte de esta memoria a largo plazo. Puedes buscar semánticamente en interacciones pasadas para encontrar rápidamente información o contexto recordado que el agente aprendió antes. Este es esencialmente el mismo mecanismo que emplea el agente durante la recuperación semántica, pero aquí puedes inspeccionarlo directamente. En nuestro ejemplo a continuación, buscamos el término "ventas" y recibimos cada interacción que incluyera algo relacionado con las ventas.

Conclusión

Al conectar Mastra y Elasticsearch, podemos dar memoria a nuestros agentes, que es una capa clave en la ingeniería de contexto. Con la memoria semántica, los agentes pueden construir contexto con el tiempo, basando sus respuestas en lo que aprendieron. Eso significa interacciones más precisas, fiables y naturales.

Esta integración temprana es solo el punto de partida. El mismo patrón aquí puede permitir que los agentes de soporte recuerden tiquetes anteriores, bots internos que recuperen la documentación relevante o asistentes de IA que puedan recuperar detalles de los clientes en medio de una conversación. También estamos trabajando en una integración oficial de Mestra, haciendo que esta pareja sea aún más fluida en un futuro próximo.

Estamos deseando ver qué construyes a continuación. Pruébalo, explora Mastra y sus funciones de memoria, y siéntete libre de compartir lo que descubras con la comunidad.