Ce que la rétrocompatibilité implique pour l'API Kibana Dashboards

Pendant la préversion technique, la forme de l'API pouvait changer d'une version à l'autre.[1] Ce n'est plus le cas. La disponibilité générale (DG) signifie :

• Rétrocompatibilité totale. De nouveaux champs et types de panneaux seront ajoutés au fil du temps, mais les champs et comportements existants demeureront inchangés. Toute modification majeure susceptible de rompre la compatibilité sera examinée avec la plus grande attention et ne sera introduite que dans une nouvelle version majeure de la pile technologique.

• Prête pour la production avec compatibilité totale. L'API bénéficie des garanties de compatibilité complète d'Elastic. Vous pouvez l'utiliser en toute sécurité dans les environnements de production pour les déploiements automatisés, la promotion de l'environnement et la gestion programmatique des tableaux de bord.

Nouveaux points de terminaison de l'API Kibana pour les panneaux Tags, Markdown et Links

Elastic 9.5 introduit également un nouveau point de terminaison autonome pour le panneau Tags, qui vous permet de catégoriser et filtrer les tableaux de bord. Vous pouvez désormais les gérer par programmation via des points de terminaison CRUD dédiés, ce qui facilite leur organisation à grande échelle dans différents environnements.

De nouveaux points de terminaison pour les panneaux Markdown et Liens sont désormais disponibles dans Serverless et seront intégrés dans la prochaine version de la pile (9.6).

Quels types de panneaux l'API Kibana Dashboards prend-elle en charge ?

L'API Dashboards prend en charge tous les panneaux par valeur de la version 9.5 (ceux définis directement dans un tableau de bord, par opposition aux panneaux de bibliothèque enregistrés pour être réutilisés). Chaque type de panneau pris en charge dispose d'un schéma typé et validé.

Type de panneau

État

Graphiques XY

Compatibles

Métriques

Compatibles

Circulaires

Compatibles

Jauge

Compatibles

Carte thermique

Compatibles

Tables de données

Compatibles

Arborescence

Compatibles

Sessions Discover

Compatibles

Contrôles

Compatibles

Markdown

Compatibles

Liens

Compatibles

Panneaux ML

Compatibles

Panneaux Observability

Compatibles

Maps

Bientôt disponible

Vega

Bientôt disponible

Comment gérer les tableaux de bord Kibana sous forme de code

L'API Dashboards permet un workflow complet de tableaux de bord sous forme de code : exportez un tableau de bord au format JSON propre et facilement comparable, validez-le dans Git comme source de référence, examinez les modifications via des requêtes pull et déployez la même définition dans les environnements de développement, de préproduction et de production. Une fois qu'un tableau de bord est géré sous forme de code, considérez Git comme source de référence unique : les modifications effectuées directement dans l'interface utilisateur seront écrasées lors du prochain déploiement.

La principale difficulté lors du transfert d'un tableau de bord entre des espaces, des clusters ou des environnements est que les tableaux de bord font référence à des objets (data views ou visualisations de bibliothèques, par exemple) au moyen d'identifiants. Comme ces identifiants sont générés automatiquement et varient d'un environnement à l'autre, un tableau de bord exporté depuis un environnement peut pointer vers des objets inexistants dans un autre. Il existe trois méthodes pour gérer cette situation, présentées ici de la plus automatisée à la moins automatisée :

• Utilisez Terraform. Le fournisseur Elastic Stack Terraform suit chaque ressource et associe automatiquement les identifiants par environnement, afin que les références restent cohérentes lorsque vous faites passer un tableau de bord de l'environnement de développement à l'environnement de production.

• Définissez par valeur les panneaux Elasticsearch Query Language (ES|QL). La méthode la plus portable pour créer un panneau consiste à définir sa visualisation à l'aide d'ES|QL directement dans le tableau de bord. Une requête ES|QL lit les données à partir des index qui y sont spécifiés ; le panneau ne contient donc aucune référence externe à des data views ou à des objets de bibliothèque. On obtient ainsi un tableau de bord entièrement autonome et portable.

• Attribuer les identifiants correspondants. Si vous référencez des objets enregistrés, tels que des data views ou des visualisations de bibliothèque, créez-les avec un identifiant spécifique en utilisant la méthode PUT (upsert) plutôt que POST (qui génère automatiquement un identifiant). Utilisez des identifiants explicites et lisibles, comme logs-prod, afin qu'ils soient faciles à reconnaître et à réutiliser d'un environnement à l'autre.

Pour une présentation détaillée de ces modèles de portabilité et du workflow complet des tableaux de bord sous forme de code, consultez la documentation Gérer les tableaux de bord sous forme de code.

Création d'un tableau de bord Kibana avec l'API Dashboards en utilisant PUT

Voici un exemple rapide de création d'un tableau de bord avec un panneau de métriques, utilisant la méthode PUT au lieu de POST pour attribuer un identifiant personnalisé basé sur le nom du tableau de bord (service-health-overview). La même logique s'applique à la création de visualisations autonomes enregistrées dans la bibliothèque.

Roadmap de l'API Kibana Dashboards : Maps, Vega et points de terminaison autonomes

Nous travaillons activement à étendre la surface de l'API. La prise en charge des panneaux Maps et Vega est la prochaine étape, avec ajout de schémas typés. Nous développons également des points de terminaison CRUD autonomes pour les sessions Discover (au-delà de leur prise en charge actuelle en tant que panneaux de tableau de bord), les panneaux Vega, Maps et les Annotations, le tout dissocié du cycle de vie des tableaux de bord.

Pour les définitions complètes des schémas, consultez la documentation de l'API Dashboards. Pour les utilisateurs de Terraform, le fournisseur Elastic Stack Terraform prend en charge l'API Dashboards en DG.

Remarque

1. Les points de terminaison principaux restent inchangés par rapport à la préversion technique. Si vous avez développé des intégrations pour la version 9.4, elles fonctionneront avec la version 9.5. Les seuls changements entraînant une rupture de compatibilité sont deux modifications mineures concernant la liste des tableaux de bord et les formats d'unité de durée ; elles sont documentées ici.

Aujourd’hui, tout devient beaucoup plus simple. Les clés API Elastic Cloud peuvent désormais être utilisées pour s’authentifier directement auprès des API Elasticsearch et Kibana dans Elastic Cloud Serverless. Vous pouvez désormais utiliser un seul identifiant pour gérer les ressources de votre organisation et exécuter des opérations sur les données, comme des requêtes Elasticsearch Query Language (ES|QL), l’ingestion de données et l’alerting.

Voyons pourquoi nous avons conçu cette solution, comment nous avons mis en place une couche d’identité distribuée à l’échelle mondiale pour la rendre possible, et comment elle pose les bases d’une recherche interprojets.

Le fardeau de la gestion des secrets

Mettre en place des pipelines CI/CD fiables, des workflows GitOps ou une automatisation Terraform autour des plateformes de données a un coût caché : la prolifération des secrets.

Dans le modèle précédent, les développeurs étaient confrontés à une gestion de l’authentification fragmentée :

• Plan de contrôle (clés API Elastic Cloud) : clés au périmètre de l’organisation utilisées pour créer des projets, inviter des utilisateurs et gérer la facturation via l’API Elastic Cloud.

• Plan de données (clés API Elasticsearch) : Clés de portée projet créées à l'intérieur d'un projet Serverless spécifique pour interagir avec Elasticsearch et Kibana API.

Cela signifiait que votre script de déploiement devait s’authentifier auprès d’Elastic Cloud, provisionner un projet Serverless, extraire une clé API Elasticsearch nouvellement générée depuis ce projet, puis injecter cette seconde clé dans l’application en aval ou l’outil d’automatisation, ce qui entraînait des pipelines complexes, des journaux d’audit fragmentés et un risque accru de fuite d’identifiants.

Authentification unifiée dans Elastic Cloud Serverless

Avec cette version, cette séparation disparaît pour les projets Serverless. Vous pouvez désormais créer une clé API Elastic Cloud explicitement autorisée pour les API Cloud, Elasticsearch et Kibana.

• Avant : une clé API Elastic Cloud était strictement un jeton du plan de contrôle. Elle permettait de créer des projets, de gérer la facturation et d’inviter des utilisateurs, mais présentait une limite stricte : elle ne pouvait pas être utilisée pour appeler les API Elasticsearch ou Kibana au sein de ces projets. Vous aviez toujours besoin d’une seconde clé, spécifique au projet, pour les opérations sur les données.

• Maintenant : en optant pour l'accès aux API Cloud, Elasticsearch et Kibana lors de la création d'une clé API Elastic Cloud, la limite stricte est supprimée pour Serverless. Cette clé API devient un véritable identifiant unifié. Il conserve sa capacité à gérer l'infrastructure de votre organisation, tout en bénéficiant d'un accès natif pour interroger, ingérer et analyser les données de tout projet Serverless autorisé.

En unifiant cela avec une seule clé API Elastic Cloud, vous disposez d’une identité unique pouvant être définie par périmètre, auditée, renouvelée et révoquée comme une seule entité. Chaque appel API, qu’il serve à provisionner un nouveau projet ou à exécuter une requête ES|QL, apparaît sous le même identifiant dans vos journaux d’audit, vous offrant une trace unique à suivre lors des enquêtes d’incident ou des audits de conformité. La rotation des identifiants devient une opération en une seule étape, au lieu d’une mise à jour coordonnée entre les secrets du plan de contrôle et du plan de données. Et comme les rôles sont attribués par projet, une seule clé peut couvrir plusieurs projets : gérer l’ingestion dans votre projet d’observabilité et exécuter des requêtes dans votre projet de sécurité, sans avoir à manipuler des identifiants distincts pour chacun.

Il est important de noter qu' unifié ne signifie pas tout-puissant. En utilisant le payload role_assignments, vous pouvez restreindre la portée d'une clé unifiée à un seul projet et à un rôle spécifique (lecture seule, par exemple), ce qui garantit que le rayon d'impact reste totalement contenu si un identifiant est exposé. En cas de départ d'un développeur ou de mise hors service d'une application, vous pouvez révoquer une seule clé depuis la console Elastic Cloud, ce qui met immédiatement fin à l'accès à la fois au plan de contrôle et à tous les projets Elasticsearch associés.

(Remarque : pour les déploiements Elastic Cloud Hosted/gérés, les clés API Cloud ne gèrent toujours que le plan de contrôle.) La prise en charge de l’extension aux API de la stack hébergée est prévue dans une prochaine version.)

Automatiser vos workflows

La mise en route est simple. Vous pouvez configurer cela entièrement via la console Elastic Cloud ou l'automatiser en utilisant l'API Elastic Cloud.

Le processus de l'interface utilisateur reste le même, mais vous pouvez désormais sélectionner l'accès aux API Cloud, Elasticsearch et Kibana dans l'affectation des rôles du projet.

Voici comment créer une clé unifiée de façon programmatique en utilisant l’API Elastic Cloud. Notez le tableau application_roles, car c’est ce qui donne à la clé un accès natif au plan de données Elasticsearch :

Une fois créée, il vous suffit de transmettre exactement la même clé dans l'en-tête Authorization: ApiKey à api.elastic-cloud.com et à vos points de terminaison Elasticsearch Serverless spécifiques.

En coulisses : conception d’une couche d’identité distribuée

Faire fonctionner une clé API Cloud à la fois sur le plan de contrôle et sur le plan de données ne se résume pas à transmettre un jeton. Cela nécessite de résoudre un défi fondamental des systèmes distribués.

Historiquement, les clés API Cloud étaient stockées dans un cluster de sécurité global centralisé. Cela fonctionne bien pour les opérations du plan de contrôle, où une latence plus élevée est acceptable. Cependant, les requêtes de données Elasticsearch nécessitent une latence extrêmement faible. Nous ne pouvons pas nous permettre un aller-retour à travers le globe vers un plan de contrôle central pour valider chaque requête de recherche ou d’ingestion.

Pour résoudre ce problème, nous avons introduit une nouvelle architecture d’authentification reposant sur un datastore distribué à l’échelle mondiale. Le diagramme de séquence suivant montre un client envoyant une requête Elasticsearch à l’aide d’une clé API Elastic Cloud, illustrant comment l’authentification s’effectue entièrement dans la région locale, sans aller-retour vers le plan de contrôle global. Elasticsearch délègue l’authentification au service IAM régional, qui valide la clé et résout ses attributions de rôles à partir d’une réplique locale de la base de données distribuée à l’échelle mondiale. Une fois autorisé, Elasticsearch exécute la requête et renvoie les résultats au client.

Persistance distribuée à l’échelle mondiale

Au lieu de s’appuyer uniquement sur un cluster de sécurité centralisé, les clés API Elastic Cloud et leurs définitions de rôles associées sont désormais stockées dans une base de données distribuée à l’échelle mondiale et hautement disponible. Cette base de données synchronise les données de gestion des identités et des accès (IAM) entre le plan de contrôle global et les plans de données régionaux où vos projets Serverless s’exécutent réellement.

Validation locale avec IAM régional

Lorsque votre client envoie une requête à Elasticsearch à l’aide d’une clé API Elastic Cloud, la requête ne revient pas vers le plan de contrôle global. Elle est plutôt redirigée vers le nouveau service IAM régional. Celui-ci valide la clé à partir de la réplique locale de la base de données, garantissant une authentification avec une latence quasi nulle et totalement isolée des pannes du plan de contrôle global.

Mappage dynamique des rôles

L'authentification n'est que la moitié de la bataille ; le système doit également autoriser la demande. Le service IAM régional traduit instantanément vos attributions de rôles au niveau du cloud (par exemple, application_roles) en privilèges Elasticsearch natifs. Elasticsearch peut alors autoriser et exécuter la requête localement, sans jamais avoir besoin d’un index .security local.

La base de la recherche interprojets

Cette architecture d'identité distribuée est un élément fondamental pour l'avenir de la plateforme Elastic.

L'identité et l'accès étant désormais unifiés et synchronisés à l'échelle mondiale, nous disposons du framework nécessaire pour transmettre votre identité en toute sécurité entre différents projets. Cela permet d'activer les capacités de recherche inter-projets (CPS) à venir pour Serverless.

Avec CPS, vous pourrez interroger des données couvrant plusieurs projets Serverless distants, par exemple en combinant des charges de travail de sécurité et d’observabilité, aussi simplement que s’il s’agissait d’un seul jeu de données. En s’appuyant sur des clés API unifiées, le système peut automatiquement évaluer vos autorisations sur l’ensemble des projets simultanément, sans vous obliger à configurer des relations de confiance complexes, des certificats ou des identifiants dupliqués pour chaque projet cible.

En savoir plus

Êtes-vous prêt à simplifier votre stack ?

• Lisez la documentation sur les clés API d'Elastic Cloud pour savoir comment attribuer l'accès à la pile.

• Consultez la référence Create API key (Elastic Cloud API) pour automatiser la génération de clés.

• Consultez les clés API Elastic pour une comparaison complète des types de clés sur la plateforme Elastic.

Commencez ou continuez à construire dans Elastic Cloud dès aujourd’hui.

Avis de non-responsabilité

La publication et la date de publication de toute fonctionnalité ou fonction décrite dans le présent article restent à la seule discrétion d'Elastic. Toute fonctionnalité ou fonction qui n'est actuellement pas disponible peut ne pas être livrée à temps ou ne pas être livrée du tout.

Elastic Workflows est un moteur d'automatisation intégré à Kibana qui vous permet de définir des processus à plusieurs étapes à l'aide d'une configuration YAML simple. Chaque workflow peut être déclenché selon une planification ou un événement, ou en tant qu'outil dans Elastic Agent Builder, et chaque étape peut appeler les API de Kibana, interroger Elasticsearch ou transformer des données.

Nous utiliserons les compteurs de vues du tableau de bord comme exemple concret, mais le même modèle s'applique à n'importe quel indicateur exposé via l'API des objets enregistrés de Kibana.

Produits requis

• Elastic Cloud ou cluster autogéré exécutant la version 9.3

• Workflows activés (paramètres avancés)

Étape 1 : Explorer les données brutes dans les Outils de développement

Avant toute chose, examinons les données disponibles. Kibana stocke la majeure partie de sa configuration et de ses métadonnées sous forme d'objets enregistrés dans un index interne dédié. Parmi les éléments suivis par Kibana figurent les consultations des tableaux de bord, grâce à un type d'objet enregistré spécifique appelé "compteurs d'utilisation". Vous pouvez les interroger directement depuis les outils de développement :

La réponse se présente comme suit :

Le champ counterName est l'identifiant du tableau de bord, et count est le nombre cumulé de vues pour ce tableau de bord ce jour-là. Kibana crée un objet compteur par tableau de bord par jour ; vous pouvez voir le suffixe de date dans l'ID de l'objet (...viewed:server:20260310). Le nombre augmente tout au long de la journée lorsque les utilisateurs ouvrent le tableau de bord.

Plutôt que de reproduire ce modèle de document quotidien dans notre index, nous créerons un document par exécution de workflow. Chaque document enregistre le nombre de vues que ce tableau de bord avait accumulées pour la journée au moment de la capture.

Étape 2 : Créer l'index de destination

Nous avons besoin d'un index pour stocker les snapshots de nos vues de tableau de bord. La commande suivante le crée avec des mappings explicites afin de pouvoir les agréger et les visualiser ultérieurement. Exécutez cette commande dans les outils de développement :

L'utilisation des mappings keyword pour les ID et les noms permet des agrégations. L'utilisation de integer pour view_count est une valeur par défaut sûre, car Kibana réinitialise le compteur quotidiennement ; atteindre la limite de 32 bits (plus de 2 milliards de vues en une seule journée) n'est donc pas un problème réaliste. Il prend toujours en compte les opérations numériques, comme max, avg et min entre autres.

Étape 3 : Créer le workflow

Accédez à Stack Management > Workflows > Nouveau workflow, puis collez la configuration YAML de workflow suivante :

Dans la section suivante, nous allons détailler le workflow étape par étape.

Fonctionnement du workflow

Déclencheurs

Le workflow s'exécute sur un déclencheur planifié toutes les 30 minutes. Cela nous permet d'obtenir des données temporelles sans solliciter l'API.

récupérer les vues du tableau de bord

Utilise kibana.request pour appeler l'API des objets enregistrés de Kibana. Aucune configuration d'authentification n'est nécessaire : le moteur de workflow associe automatiquement les en-têtes corrects en fonction du contexte de l'exécution.

index_each_dashboard (foreach)

Itère sur le tableau saved_objects renvoyé par l'étape précédente. L'élément actuel de chaque itération est disponible sous la forme foreach.item. À l'intérieur de la boucle, nous exécutons deux étapes imbriquées pour chaque tableau de bord.

1. fetch_dashboard_name :

Résout le titre du tableau de bord lisible par l'utilisateur en appelant GET /api/saved_objects/dashboard/{id}. Nous ajoutons on-failure: continue: true pour que, si un tableau de bord a été supprimé mais qu'il contient encore des compteurs de vues, la boucle continue au lieu d'interrompre l'exécution.

2. index_doc :

Indexe chaque document à l'aide de POST /dashboard-views/_doc (sans identifiant explicite), ce qui permet à Elasticsearch de générer automatiquement des identifiants. Un nouveau document est ainsi créé à chaque exécution, ce qui permet d'établir un historique du nombre de vues au fil du temps plutôt que d'écraser le snapshot précédent.

Deux choses à noter :

• Le champ captured_at utilise le filtre de date pour formater l'horodatage au format ISO 8601. Sans ce filtre, la valeur apparaît sous la forme d'une chaîne de date JavaScript, comme Tue Mar 10 2026 05:03:47 GMT+0000, qu'Elasticsearch ne pourra pas interpréter comme une date.

• Le view_count utilise la syntaxe ${{ }} avec | plus: 0 pour préserver le type numérique. L'utilisation de {{ }} le rendrait sous forme de chaîne, ce qui empêcherait les opérations mathématiques dans le tableau de bord.

L'interface utilisateur vous permet de déboguer efficacement chacune des étapes du workflow.

Étape 4 : Créer le tableau de bord des statistiques

Une fois que le workflow a été exécuté plusieurs fois et que les données ont été collectées, créez un nouveau tableau de bord dans Kibana en utilisant la data view dashboard-views.

Voici quelques panneaux pour commencer :

• Principaux tableaux de bord par vues : utilisez un graphique à barres avec dashboard_name sur l'axe des X et last_value(view_count) sur l'axe des Y. Cela indique le nombre actuel de vues quotidiennes par tableau de bord.

• Vues au fil du temps : utilisez un graphique linéaire avec captured_at sur l'axe X et last_value(view_count) sur l'axe Y, décomposé par dashboard_name. Comme chaque exécution ajoute un nouveau document, utilisez la dernière valeur pour obtenir le nombre maximal par intervalle temporel au lieu d'additionner les doublons.

• Snapshot actuel : utilisez un tableau de données avec les dernières valeurs captured_at pour afficher les nombres de vues les plus récents sur tous les tableaux de bord.

Étant donné que chaque workflow crée un nouveau document, vous pouvez filtrer par plage horaire pour analyser l'activité sur des périodes spécifiques, comparer d'une semaine à l'autre ou créer des alertes lorsqu'un tableau de bord passe en dessous d'un seuil d'affichage.

Conclusion

Elastic Workflows est parfaitement adapté à ce type de collecte de données périodique, car la source (API Kibana) et la destination (Elasticsearch) sont natives, ce qui élimine toute gestion d'identifiants. Le moteur de workflow gérant automatiquement l'authentification pour les étapes kibana.request et elasticsearch.request, vous n'avez qu'à écrire la logique.

Ressources

• Elastic Workflows

• API Kibana

Gestion des dépendances chez Elastic

Chez Elastic, nous devons gérer des centaines, voire des milliers de référentiels privés et publics. Lorsqu'une CVE critique est découverte, nous avons besoin de réponses et d'actions immédiates : quels référentiels sont vulnérables ? Dans quel délai pouvons-nous les réparer ? Outre la sécurité, des questions de productivité se posent également : comment transmettre rapidement la publication d'une nouvelle version d'un package à tous les référentiels qui en dépendent, sans passer trop de temps à effectuer des tâches manuelles ?

La recherche de méthodes de gestion des dépendances a été motivée à l'origine par la nécessité d'établir une base sécurisée avec des mises à jour automatisées pour réduire les CVE. Après avoir soigneusement réfléchi aux solutions de gestion des dépendances, nous avons d'abord commencé à travailler sur une infrastructure auto-hébergée. Nous utilisions notre propre cluster Kubernetes pour exécuter Mend Renovate Community auto-hébergé. L'idée était de pouvoir fournir une plateforme de gestion des dépendances à laquelle nos utilisateurs pourraient accéder en libre-service.

L'expérience initiale s'est avérée fructueuse, si bien que de plus en plus d'équipes ont commencé à adopter notre plateforme et à l'utiliser dans le cycle de vie quotidien de leurs référentiels pour les mises à jour et les correctifs CVE. Cela s'est passé si vite que nous avons rapidement atteint les limites de notre installation auto-hébergée.

Le défi : comment pouvons-nous scaler une plateforme de gestion des dépendances dans une grande organisation disposant d'un nombre important de référentiels ?

Notre plateforme de gestion des dépendances traitait un référentiel à la fois et le modèle de traitement séquentiel ne pouvait pas suivre le rythme, compte tenu du grand nombre de référentiels que nous gérons. Nous avions déjà constaté que le problème provenait du fait qu'une seule instance de notre outil de gestion des dépendances pouvait traiter notre liste importante et toujours croissante de référentiels. Les référentiels attendaient parfois pendant plusieurs heures dans une file d'attente. Plus de 50 % de nos référentiels n'étaient même pas traités quotidiennement. Autrement dit, plus de la moitié de nos référentiels attendaient plus de 24 heures entre les analyses.

Les grands référentiels ont créé des goulots d'étranglement plus importants, en raison de leurs bases de code volumineuses et de leurs multiples requêtes pull ouvertes. Les événements du webhook GitHub ont perturbé la séquence. La fusion automatique est devenue peu fiable car le moment des analyses était imprévisible. Nous avions fait une promesse à nos utilisateurs concernant la fréquence des analyses, mais nous n'avons pas pu la tenir.

La décision de développer en interne : répondre aux besoins uniques de scalabilité et de sécurité d'Elastic

Bien que nous envisagions des options commerciales, dont l'édition auto-hébergée Renovate Enterprise de Mend, nous avions en interne chez Elastic quelques initiatives clés en cours de développement.

Notre décision de créer une plateforme en interne a été motivée par la prise de conscience que seule une solution hautement personnalisée pouvait répondre aux exigences spécifiques et non négociables d'Elastic :

1. Investissement dans notre plateforme de développement interne : à l'époque, nous avions déjà investi massivement dans notre plateforme de développement interne. Nous réfléchissions à la manière d'intégrer chacun de nos services à cette plateforme et nous concevions des solutions pour y parvenir. Cela impliquait de tester nos propres règles et pratiques pour notre plateforme de gestion des dépendances. De plus, de nouvelles directives entraient en vigueur et nous souhaitions concevoir la plateforme en amont.

2. Intégration native et personnalisation du workflow : nous avions besoin d'une intégration simple à nos outils et processus internes. Par exemple, nous souhaitions centraliser la configuration sous forme de code avec notre catalogue de services (Backstage). L'utilisation de Backstage nous impose des exigences spécifiques avec lesquelles nous voulions que notre plateforme soit compatible. Ainsi, bien qu'il soit possible d'utiliser les API auto-hébergées de Renovate en complément de notre automatisation Backstage, cela ne couvrirait pas entièrement nos processus internes.

3. Sécurité renforcée par défense en profondeur spécifique à Elastic : notre conformité stricte en matière de sécurité exigeait des mécanismes de sécurité sur mesure, adaptés à notre écosystème. Nous nous efforcions de renforcer la sécurité de notre utilisation des "identités non humaines". Ce renforcement des accès impliquait que les méthodes d'authentification non standard auprès de GitHub ne fonctionneraient pas avec un outil standard qui ne prenait pas en charge cette implémentation interne. Notre workflow comprenait la mise en œuvre d'un modèle de chiffrement des secrets de workflow parent-enfant et l'utilisation de jetons GitHub temporaires à usage unique. Le développement en interne était la seule solution pratique pour intégrer ces couches de sécurité uniques et minimiser la surface d'attaque dans notre environnement multicloud complexe.

La solution : l'orchestration des workflows pour la gestion des dépendances

Notre solution est née de notre volonté de tirer parti de l'outil de gestion des dépendances que nous utilisions déjà plutôt que de le remplacer et rechercher d'autres solutions. Cet outil avait démontré son potentiel, et sa flexibilité est essentielle pour répondre aux différents besoins de notre organisation. Nous avons examiné différentes solutions, et ce qui a guidé notre choix, ce sont les besoins importants et parfois spécifiques que nous devons satisfaire. Nous avons donc décidé de créer une plateforme de gestion des dépendances fiable et évolutive, où chaque référentiel est traité individuellement, éliminant ainsi les goulots d'étranglement et nous préparant à la croissance.

Nous avons conçu la plateforme en respectant trois principes fondamentaux :

1. Traitement parallèle

Chaque référentiel est doté de son propre environnement de gestion des dépendances. Plus de files d'attente. Notre simultanéité d'exécution n'est limitée que par le nombre de ressources que nous utilisons. Nous avons également appliqué une programmation distribuée intelligente pour éviter d'être limité par GitHub.

2. Libre-service

Nous utilisons notre catalogue de services (Backstage) pour intégrer et gérer automatiquement les nouveaux référentiels. Grâce à notre propre système de définition des ressources, l'utilisateur final peut choisir la fréquence de traitement des référentiels, le nombre de ressources à allouer à ses planifications, et activer ou désactiver le traitement à tout moment. Nous prévoyons d'ajouter d'autres options à mesure que les besoins de nos utilisateurs évoluent et qu'ils se familiarisent avec la nouvelle installation.

3. Réduction de la portée des secrets et de l’isolation des espaces de noms

Pour une sécurité accrue, nous fournissons à nos modules de gestion des dépendances des jetons GitHub éphémères qui sont générés au début de chaque workflow. En outre, nous isolons nos charges de travail dans des espaces de noms spécifiques afin de ne leur fournir que les secrets nécessaires. Nous contrôlons les secrets qui peuvent être accessibles par chaque workflow de gestion des dépendances en utilisant le RBAC de Kubernetes. Nous utilisons également le chiffrement pour transmettre le jeton GitHub du workflow parent au workflow enfant.

Nous avons reconstruit notre plateforme en utilisant Kubernetes et en exploitant sa puissance. Argo Workflows gère la logique de nos processus et Renovate CLI est configuré pour analyser et traiter un référentiel à la fois.

L'intérêt de ce modèle : nous utilisons des projets open source éprouvés d'une manière originale, en fournissant de nouveaux exemples fonctionnels pour tous ces projets et, en même temps, en amplifiant la vitesse de développement et en consolidant la réduction des CVE pour nos équipes.

Architecture de gestion des dépendances : Quatre microservices

La plateforme comprend quatre composants conçus sur mesure :

Opérateur de workflow (Go/Kubebuilder)

Un opérateur Kubernetes gérant le cycle de vie du workflow à travers trois définitions de ressources personnalisées (CRD) :

• CRD RepoConfig : source unique de référence pour la configuration du référentiel.

Voici comment RepoConfig est défini dans l'opérateur :

Et voici à quoi ressemblerait une instance de RepoConfig :

• CRD parent : gère les workflows Cron pour les analyses programmées.

À l'intérieur de la boucle de rapprochement du contrôleur parent, nous nous assurons que les paramètres du workflow sont créés et maintenus à jour, voire supprimés si nécessaire.

Tout d'abord, le contrôleur parent obtient certains paramètres configurés globalement pour les workflows :

Il s'assure que la configuration du mutex est à jour afin d'empêcher l'exécution simultanée de workflows similaires :

Ensuite, il crée un gestionnaire de workflow qui est la structure qui va créer ou mettre à jour les workflows Cron et les modèles de workflow :

• CRD enfant : gère les modèles de workflow avec des ressources par référentiel.

Le contrôleur enfant a une mission de rapprochement similaire à celle du parent, mais ici, il est responsable des modèles de workflow dans l'espace de noms enfant qui seront déclenchés par les workflows parents.

Le modèle multicontrôleur offre une séparation claire : le contrôleur RepoConfig gère l'intégration/dissociation, le contrôleur parent gère la planification, et le contrôleur enfant gère les modèles d'exécution.

Portail d'événements GitHub (Go)

Proxy sécurisé de webhook qui reçoit les webhooks GitHub, vérifie les signatures, filtre par organisation/référentiel, et redirige vers Argo Events. Nous avons conçu 10 capteurs distincts répondant aux interactions du tableau de bord des dépendances, aux événements de requêtes pull (PR) et aux mises à jour des packages.

Cette passerelle permet l'intégration aux applications GitHub par :

• Vérification de la sécurité des signatures des webhooks GitHub entrants.

• Transmission des événements valides à l'EventSource Argo Events avec tous les en-têtes correspondants et l'authentification.

• Nous configurons également un authSecret sur l'EventSource et le fournissons comme en-tête Bearer dans les requêtes transférées.

• Fourniture de logging, indicateurs, et logique de tentatives.

Le webhook effectue diverses validations sur chaque requête d'événement GitHub.

Il s'assure que certains attributs HTTP sont présents :

Tout en validant également la signature de chaque requête et son organisation :

Enfin, il redirige vers Argo Events en fonction du type d'événement :

Du côté d'Argo Events, 10 capteurs surveillent l'EventBus d'Argo pour détecter les nouveaux événements.

Le script applique ensuite la logique de chaque capteur :

Backstage Syncer (Go)

Ce composant interroge notre catalogue de services (Backstage) pour obtenir les entités de ressources réelles du référentiel, les transforme en CRD RepoConfig et maintient la plateforme synchronisée avec les modifications de configuration. Celles-ci sont appliquées en trois minutes.

Enfin, il écrit ces données dans des instances RepoConfig.

Base de workflows (mixte : JavaScript, Go, Helm)

La couche de base contient des charts Helm, des configurations JavaScript, un wrapper Go pour Renovate CLI avec prise en charge du chiffrement et un indexeur APK personnalisé pour les packages Alpine.

Configuration en libre-service

Les équipes configurent leurs référentiels de manière déclarative via Backstage :

Les groupes de ressources allouent le processeur et la mémoire en fonction de la taille du référentiel :

• SMALL : CPU 500 m, mémoire 1 Go.

• MEDIUM : CPU 1000 m, mémoire 2 Go.

• LARGE : CPU 2000 m, mémoire 4 Go.

La configuration est versionnée, auditable et s'applique automatiquement.

Le modèle parent-enfant

Le modèle d'exécution utilise un modèle de workflow parent-enfant :

• Workflow parent : workflow Cron léger qui s'exécute comme prévu. Chiffre les secrets, détermine si une analyse doit être exécutée, transmet la configuration à l'enfant.

• Workflow enfant : pod éphémère où s'exécute Renovate CLI. Allocation dynamique des ressources, déchiffrement des secrets de manière isolée, arrêt après exécution.

Cette séparation offre sécurité (secrets chiffrés au niveau parent), optimisation des ressources (les parents utilisent des ressources minimales) et scalabilité (les enfants s'exécutent en parallèle).

Résultats

Transformation des performances

• Avant : un référentiel à la fois, certains référentiels n'étaient pas traités, parfois même pendant un jour ou plus, moins de 1 000 analyses par jour.

• Après : plus de 100 analyses simultanées, généralement 8 000 analyses et jusqu'à 10 000 analyses enregistrées par jour, limitées uniquement par la quantité de ressources que nous sommes prêts à consacrer et par la façon dont nous gérons les limites de débit de GitHub.

Rentabilité

Cependant, aussi étrange que cela puisse paraître, exécuter 8 000 pods par jour peut permettre d'obtenir le même résultat à moindre coût qu'avec un seul pod fonctionnant en continu pour tenter d'atteindre le même résultat.

Dans la configuration précédente, nous utilisions une seule instance qui, en conditions optimales, effectuait 500 à 600 analyses. Par ailleurs, comme différents types de référentiels étaient exécutés sur le même pod, nous devions dimensionner celui-ci pour les plus volumineux. Ce dimensionnement était bien supérieur à notre offre actuelle "extra large", qui utilise 8 cœurs de processeur et 16 Go de mémoire par pod.

Pour traiter le volume quotidien actuel, le pod unique devrait s'exécuter pendant 12 jours. Ainsi, en comparant le coût de ce pod unique fonctionnant pendant 12 jours à celui de 8 000 pods de taille "MEDIUM" s'exécutant chaque jour, notre nouvelle architecture est bien plus efficace pour un même volume d'analyses.

Métrique

Scénario A (workflows)

Scénario B (pod unique et exécution de longue durée)

Configuration

8 000 pods (1 vCPU/2 Go)

1 pod (8 vCPU / 16 Go)*

Durée

10 minutes chacun

12 jours en continu

Temps de travail total

1 333 heures de calcul

288 heures de calcul

Coût total

65,83 $

113,75 $

Cependant, prenons en considération le fait que notre valeur par défaut pour nos charges de travail est définie sur "SMALL", la grande majorité fonctionnant correctement avec une utilisation CPU de 0,5 Go et 1 Go de RAM, et seules quelques-unes nécessitant une configuration moyenne ou grande. Voyons ce qui se passe si 60 % de nos charges de travail s'exécutent sur "SMALL", 30 % sur "MEDIUM" et 10 % sur "LARGE", ce qui est plus proche de la réalité.

Métrique

Scénario A (essaim mixte)

Scénario B (exécution de longue durée)

Stratégie

8 000 pods (tailles variées)

1 pod (8 vCPU / 16 Go)*

Durée

10 minutes chacun

12 jours en continu

Coût total

52,66 $

113,75 $

Économies

61,09 $ (54 % moins cher)

—

Nous pouvons constater que, pour le même volume, nous sommes beaucoup plus rentables dans notre configuration actuelle.

Sécurité renforcée

• Jetons GitHub éphémères (minutes d'exposition contre plusieurs jours).

• Isolation d'espace de nom avec limites de contrôle d'accès basé sur les rôles (RBAC).

• Chiffrement des secrets au repos dans les workflows parents.

• Accès direct au coffre-fort supprimé.

Performance prévisible

Grâce à une fréquence d'analyse garantie, nous pouvons enfin définir des objectifs de niveau de service (SLO). La fusion automatique fonctionne de manière fiable. Les équipes ont confiance en la plateforme pour tenir ses promesses.

Décisions architecturales clés

Voici quelques-unes des décisions de conception majeures qui ont façonné l'apparence de la plateforme.

• Pourquoi des workflows parent-enfant ?

Nous avons adopté ce modèle pour mettre en œuvre une stratégie de défense en profondeur. En limitant les identifiants sensibles (tels que les secrets d'applications GitHub) à un espace de noms dédié et sécurisé, nous utilisons le RBAC pour garantir que les pods d'exécution éphémères ne puissent pas accéder arbitrairement aux données sensibles. De récentes vulnérabilités de la chaîne d'approvisionnement (par exemple, les attaques "Shai Hulud" ciblant l'intégration continue et le déploiement continu [CI/CD]) ont démontré l'importance cruciale d'isoler les environnements d'exécution qui exécutent des scripts dynamiques depuis le magasin d'identifiants.

Simultanément, ce découplage permet une optimisation granulaire des ressources. Les workflows "parents" agissent comme des orchestrateurs légers avec un encombrement minimal, tandis que les workflows "enfants" gèrent l'analyse des dépendances gourmande en ressources IT. Cette séparation simplifie la gestion du cycle de vie en nous permettant d'appliquer une logique de rapprochement distincte à chaque couche, offrant ainsi aux utilisateurs le contrôle des paramètres d'exécution (enfants) tout en conservant le contrôle administratif sur l'infrastructure de planification et de sécurité (parents).

• Pourquoi en libre-service ?

Il était essentiel d'éliminer notre équipe comme goulot d'étranglement pour la configuration des référentiels. Notre mission était de concevoir une plateforme scalable et en libre-service, capable de prendre en charge divers cas d'utilisation. Nous avons constaté qu'il était impossible, compte tenu du nombre considérable de référentiels, de jouer le rôle de contrôleur d'accès pour chaque modification de configuration. Nous avons donc adopté une approche axée sur l'enablement : fournir les "rails" (l'infrastructure et les garde-fous), tout en donnant aux utilisateurs les moyens d'agir et de conduire les "trains" (l'exécution et la personnalisation). Nous pensons que cette évolution vers l'autonomie des équipes améliore considérablement la productivité en permettant aux utilisateurs d'adapter le système à leurs besoins opérationnels spécifiques.

• Pourquoi le modèle d'opérateur Kubernetes ?

Comme indiqué précédemment, un principe de conception fondamental consistait à garantir que la plateforme soit entièrement en libre-service. Nous avions besoin d'un mécanisme automatisé pour capturer les intentions de l'utilisateur (par exemple, activer/désactiver les analyses, ajuster la fréquence de planification ou paramétrer les limites des ressources d'exécution) et transmettre instantanément ces modifications aux workflows sous-jacents. Afin d'anticiper les besoins futurs, le système devait aussi être facilement extensible.

Pour ce faire, nous avons développé un opérateur Kubernetes de gestion des dépendances personnalisé. En utilisant les CRD comme interface de configuration, nous avons établi une boucle de rapprochement native Kubernetes. Cet opérateur surveille en permanence l'état souhaité défini par l'utilisateur et orchestre automatiquement les mises à jour nécessaires de l'infrastructure de workflow. Ceci garantit un fonctionnement transparent et piloté par les événements, où la logique de la plateforme gère toute la complexité en arrière-plan.

• Pourquoi concevoir une passerelle d’événements GitHub ?

L'adoption d'une architecture pilotée par les événements (EDA) était essentielle à la réactivité de la plateforme. Si les workflows Cron fournissaient une planification de base fiable, nous avions besoin d'agilité pour gérer les exécutions ad hoc, comme le déclenchement manuel d'analyses par les utilisateurs via le tableau de bord. Pour ce faire, nous avions besoin d'une passerelle d'ingestion dédiée afin de valider l'intégrité des données et acheminer intelligemment les requêtes.

Nous avons évalué les solutions existantes, notamment l'EventSource natif de GitHub pour Argo, mais nous avons identifié des risques importants liés à la surcharge opérationnelle et aux quotas stricts de l'API GitHub (par exemple, les limites de webhook par référentiel). Par conséquent, nous avons développé une passerelle personnalisée afin de découpler notre infrastructure de ces limitations.

Cette passerelle s'est avérée cruciale en tant que point de contrôle du trafic lors de notre migration. Elle a agi comme un commutateur, nous permettant d'effectuer un déploiement progressif et granulaire (transfert de trafic) de l'ancien système vers la nouvelle infrastructure. Ainsi, l'intégration de milliers de référentiels s'est déroulée de manière contrôlée et sans risque, plutôt que par une transition brutale.

Enseignements

Certains enseignements que nous avons tirés vont de pair avec le code source d'Elastic :

1. Priorité au client : les plateformes sont conçues pour les utilisateurs. Il est donc essentiel de placer leurs besoins au cœur de nos priorités. Cela permet de concevoir une infrastructure et des applications performantes qui réduisent les obstacles pour les utilisateurs, simplifient le scaling de la plateforme et facilitent son adoption.

2. Espace, temps : parfois, la voie de la facilité mène à des sables mouvants. Nous avons d'abord tenté d'optimiser le modèle de traitement séquentiel existant, mais cela n'a pas résolu nos problèmes ; au contraire, cela n'a fait qu'accroître la complexité et créer des zones d'ombre. La décision audacieuse de repenser l'architecture de la plateforme avec un traitement parallèle a nécessité un investissement initial important. Cependant, elle a finalement ouvert la voie à une croissance durable de la plateforme et a quasiment éliminé les tâches administratives quotidiennes fastidieuses.

3. Informatique, dépendances : une plateforme ne peut pas fonctionner de manière isolée ; son succès dépend de la manière dont elle s'intègre dans un écosystème plus large. Dans notre cas, l'intégration à Backstage était essentielle, car elle constitue la source de référence pour une intégration fluide des services. De même, la connexion à Artifactory nous a permis de gérer efficacement les mises à jour des packages privés, et la liste des intégrations essentielles ne s'arrête pas là.

4. Progrès, perfection SIMPLE : tout au long de la mise en œuvre, nous avons constamment testé nos hypothèses initiales et nous nous sommes adaptés aux nouveaux obstacles à mesure qu'ils apparaissaient. Plutôt que de nous laisser paralyser par le perfectionnisme, nous avons adopté une approche itérative, en relevant les défis les uns après les autres et en ajustant notre stratégie de migration aux conditions réelles.

Prochaines étapes

La mise en place de la plateforme nous permet de nous consacrer à des tâches plus importantes qui contribueront à améliorer l'expérience utilisateur et l'efficacité de notre plateforme. En voici quelques exemples :

• Renforcer et garantir l'adoption de la fusion automatique

La fonctionnalité de fusion automatique accélère considérablement la rapidité de l'équipe en éliminant les tâches manuelles fastidieuses. Toutefois, il est essentiel de mettre en place des garde-fous stricts afin de garantir que cette rapidité accrue ne s'obtienne pas au détriment de la sécurité.

• Améliorer la visibilité sur l'expérience des utilisateurs finaux

L'une des priorités essentielles de notre feuille de route est l'amélioration de l'observabilité, non seulement au niveau de la plateforme, mais aussi du point de vue de l'utilisateur final. Si la collecte des indicateurs d'infrastructure est simple, la compréhension de l'expérience utilisateur réelle exige une analyse plus approfondie. Nous travaillons à la définition d'indicateurs clés de performance (KPI) centrés sur l'utilisateur afin que notre système de télémétrie puisse détecter les points de friction et les problèmes de performance avant qu'ils ne se transforment en plaintes d'utilisateurs.

• Supprimer les obstacles à une plus grande adoption

Pour l'avenir, notre priorité est d'identifier et de lever les obstacles à l'adoption de la plateforme. Qu'il s'agisse de développer de nouvelles intégrations ou de déployer des fonctionnalités spécifiques, nous privilégions une planification fondée sur les données. Nous avons développé avec succès une plateforme conçue pour évoluer ; notre objectif est désormais d'en maximiser le potentiel.

Le tableau d'ensemble

Le projet de workflows de gestion des dépendances illustre un principe plus large : lorsque vous devez scaler des outils open source au-delà de leur modèle de déploiement par défaut, les modèles natifs Kubernetes offrent une voie à suivre.

En adoptant :

• Les CRD pour la configuration.

• Les opérateurs pour la gestion du cycle de vie.

• Une architecture basée sur les événements pour une meilleure réactivité

• GitOps pour le déploiement.

Nous avons conçu une orchestration qui scale indépendamment du nombre de référentiels gérés. Les performances d'analyse d'un seul référentiel restent identiques, que nous en gérions 100 ou 1 000.

Lorsqu'une CVE critique est annoncée, nous obtenons désormais des réponses en quelques minutes, et non plus en quelques heures. C'est ce qui fait la différence entre un goulot d'étranglement et un avantage concurrentiel.

Remerciements

Cette plateforme s'appuie sur d'excellents outils open source :

• Kubebuilder : le framework open source que nous avons utilisé pour lancer nos opérateurs Kubernetes qui démarrent et orchestrent nos workflows. [1][2]

• Backstage : le framework open source sur lequel nous avons construit notre catalogue de services et que nous utilisons comme source de référence. [1][2]

• Argo Workflows et Argo Events : la suite open source que nous avons utilisée pour orchestrer des processus complexes et ajouter un traitement dynamique basé sur des événements. [1][2][3][4]

• Renovate CLI : l'outil open source de gestion des dépendances qui traite nos référentiels. [1][2]

* Le modèle de tarification AWS Fargate a été utilisé comme référence pour le coût d'un seul pod, bien que nos charges de travail ne s'exécutent pas nécessairement sur AWS et s'exécutent sur des clusters Kubernetes complets.

En outre, ces cas d'utilisation sont généralement sensibles au temps, et passer par les étapes de développement habituelles (créer une branche de code et attendre une nouvelle version) est un processus qui prend beaucoup de temps.

Et si nous pouvions réaliser l'ensemble de ce processus par un simple appel d'API ou, mieux encore, en quelques clics dans Kibana ?

Règles d'interrogation

Elasticsearch 8.10 a introduit les règles de requête et le récupérateur de règles. Il s'agit d'outils conçus pour injecter des résultats épinglés dans les requêtes sans affecter le classement des résultats organiques sur la base de règles. Ils ne font qu'ajouter une logique d'entreprise aux résultats d'une manière simple et déclarative.

Voici quelques exemples d'utilisation courante des règles de requête :

• Mise en évidence des annonces ou des ventes promues: Afficher les articles en vente ou sponsorisés en haut de la page.

• Exclusion en fonction du contexte ou de la géolocalisation: Masquer certains éléments lorsque la réglementation locale ne permet pas de les afficher.

• Donner la priorité aux résultats clés: Veiller à ce que les recherches populaires ou fixes soient toujours en tête, quel que soit le classement organique.

Pour accéder à l'interface et interagir avec ces outils, vous devez cliquer sur le menu latéral de Kibana et aller dans Règles de requête, sous Pertinence:

Lorsque le menu des règles de requête s'affiche, cliquez sur Créer votre premier jeu de règles :

Ensuite, vous devez nommer votre jeu de règles.

Le formulaire permettant de définir chaque règle comporte trois éléments clés :

• Critères: Les conditions qui doivent être remplies pour que la règle s'applique. Par exemple, "lorsque le champ query_string contient la valeur Christmas" ou "lorsque le champ country est CO".

• Action: C'est ce que vous voulez qu'il se passe lorsque les conditions sont remplies. Il peut être épinglé (fixation d'un document dans les premiers résultats) ou exclu (masquage d'un document).

• Métadonnées: Il s'agit des champs qui accompagnent la requête lors de son exécution. Elles peuvent inclure des informations sur l'utilisateur (comme la localisation ou la langue) ainsi que des données de recherche (query_string). Il s'agit des valeurs utilisées par les critères pour décider d'appliquer ou non une règle.

Exemple : articles populaires

Imaginons que nous ayons un site de commerce électronique proposant différents articles. En vérifiant les mesures, nous remarquons que l'un des articles les plus vendus dans la catégorie des consoles est la "manette sans fil DualShock 4", en particulier lorsque les utilisateurs recherchent les mots clés "PS4" ou "PlayStation 4". Nous décidons donc de placer ce produit en tête des résultats lorsqu'un utilisateur effectue une recherche avec ces mots-clés.

Tout d'abord, nous allons indexer les documents pour chaque article à l'aide d'une requête API en bloc :

Si nous n'intervenons pas dans la requête, l'article apparaît généralement en quatrième position. Voici la requête :

Et voici les résultats

Créons une règle de requête pour modifier cela. Tout d'abord, ajoutons-le au jeu de règles comme suit :

Ou demande d'API équivalente :

Pour utiliser l'ensemble de règles dans notre requête, nous devons utiliser un type de règle de requête. Ce type de requête se compose de deux parties principales :

• match_criteria: Il s'agit des métadonnées utilisées pour la comparaison avec la requête de l'utilisateur. Dans cet exemple, le jeu de règles est activé lorsque le champ query_string a la valeur "PlayStation 4".

• requête: la requête réelle qui sera utilisée pour effectuer la recherche et obtenir les résultats organiques.

De cette façon, vous exécutez d'abord la requête organique, puis Elasticsearch applique les règles de votre ensemble de règles :

Exemple : métadonnées basées sur l'utilisateur

Une autre application intéressante des règles d'interrogation consiste à utiliser les métadonnées pour afficher des documents spécifiques sur la base d'informations contextuelles provenant de l'utilisateur ou de la page web.

Par exemple, imaginons que nous souhaitions mettre en avant des articles ou des ventes personnalisées en fonction du niveau de fidélité d'un utilisateur, représenté par une valeur numérique.

Nous pouvons le faire en intégrant ces métadonnées directement dans la requête, de sorte que les règles s'activent lorsque la valeur en question répond à certains critères.

Tout d'abord, nous allons indexer un document que seuls les utilisateurs ayant un niveau de fidélité élevé peuvent consulter :

Maintenant, créons une nouvelle règle dans le même jeu de règles pour que lorsque le niveau de fidélité est égal ou supérieur à 80, l'article apparaisse en tête des résultats.

Enregistrez la règle et le jeu de règles.

Voici la requête REST équivalente :

Désormais, lors de l'exécution d'une requête, nous devons inclure le nouveau paramètre loyalty_level dans les métadonnées. Si la condition de la règle est remplie, le nouveau document apparaît en tête des résultats.

Par exemple, lors de l'envoi d'une requête dont le niveau de fidélité est 80 :

Nous verrons le document de fidélisation en haut des résultats :

Dans le cas ci-dessous, le niveau de fidélité étant de 70, la règle n'est pas respectée et l'objet ne doit pas apparaître en haut de la liste :

Voici les résultats :

Exemple : exclusion immédiate

Supposons que notre manette sans fil DualShock 4 (ID 2) soit temporairement indisponible et ne puisse être vendue. Ainsi, au lieu de supprimer manuellement le document ou d'attendre qu'un processus de données se mette en place, l'équipe commerciale décide de le supprimer des résultats de recherche en attendant.

Nous utiliserons un processus similaire à celui que nous venons d'appliquer aux articles populaires, mais cette fois-ci, au lieu de sélectionner Épinglé, nous choisirons Exclure. Cette règle fonctionne comme une sorte de liste noire. Changez les critères en Toujours pour que l'exclusion fonctionne à chaque fois que la requête est exécutée.

La règle devrait ressembler à ceci :

Enregistrez la règle et le jeu de règles pour appliquer les modifications. Voici la requête REST équivalente :

Maintenant, lorsque nous exécutons à nouveau la requête, vous verrez que l'élément ne figure plus dans les résultats, bien que la règle préalable soit de l'épingler. En effet, les exclusions ont la priorité sur les résultats de l'épinglage.

Conclusion

Les règles de requête permettent d'ajuster très facilement la pertinence sans modifier le code. La nouvelle interface utilisateur Kibana vous permetd'effectuer ces modifications en quelques secondes, ce qui vous donne, ainsi qu'à votre équipe commerciale, un meilleur contrôle sur vos résultats de recherche.

Au-delà du commerce électronique, les règles de requête peuvent servir à de nombreux autres scénarios : mise en évidence des guides de dépannage dans les portails d'assistance, mise en évidence des documents internes clés dans les bases de connaissances, promotion des dernières nouvelles dans les sites d'information ou filtrage des offres d'emploi ou des listes de contenu expirées. Ils peuvent même appliquer des règles de conformité, par exemple en masquant les documents à diffusion restreinte en fonction du rôle de l'utilisateur ou de la région.

Dans ce blog, nous utiliserons Mastra pour construire un agent de connaissance qui se souvient de ce que les utilisateurs disent et peut rappeler les informations pertinentes plus tard, en utilisant Elasticsearch comme mémoire et backend de récupération. Vous pouvez facilement étendre ce même concept à des cas d'utilisation réels, comme des agents d'assistance qui peuvent se souvenir de conversations et de résolutions antérieures, ce qui leur permet d'adapter les réponses à des utilisateurs spécifiques ou de trouver des solutions plus rapidement en fonction du contexte antérieur.

Suivez ici les étapes de sa construction. Si vous vous perdez ou si vous voulez simplement exécuter un exemple fini, consultez le repo ici.

Qu'est-ce que Mastra ?

Mastra est un framework TypeScript open-source pour la construction d'agents d'intelligence artificielle avec des parties interchangeables pour le raisonnement, la mémoire et les outils. Sa fonction de rappel sémantique permet aux agents de se souvenir des interactions passées et de les retrouver en stockant les messages sous forme d'enchâssements dans une base de données vectorielle. Cela permet aux agents de conserver le contexte et la continuité de la conversation à long terme. Elasticsearch est un excellent magasin de vecteurs pour activer cette fonctionnalité, car il prend en charge la recherche vectorielle dense efficace. Lorsque le rappel sémantique est déclenché, l'agent introduit les messages antérieurs pertinents dans la fenêtre contextuelle du modèle, ce qui permet à ce dernier d'utiliser le contexte récupéré comme base de son raisonnement et de ses réponses.

Ce qu'il faut pour commencer

• Node v18+

• Elasticsearch (version 8.15 ou plus récente)

• Clé API Elasticsearch

• Clé API OpenAI

Note : Vous en aurez besoin parce que la démo utilise le fournisseur OpenAI, mais Mastra prend en charge d'autres SDK d'IA et fournisseurs de modèles communautaires, vous pouvez donc facilement l'échanger en fonction de votre configuration.

Construire un projet Mastra

Nous utiliserons le CLI intégré de Mastra pour fournir l'échafaudage de notre projet. Exécutez la commande :

Vous obtiendrez une série d'invites, commençant par :

1. Donnez un nom à votre projet.

2. Nous pouvons conserver cette valeur par défaut ; n'hésitez pas à la laisser vide.

3. Pour ce projet, nous utiliserons un modèle fourni par OpenAI.

4. Sélectionnez l'option "Skip for now" car nous allons stocker toutes nos variables d'environnement dans un fichier `.env` que nous configurerons plus tard.

5. Nous pouvons également ignorer cette option.

Une fois l'initialisation terminée, nous pouvons passer à l'étape suivante.

Installation des dépendances

Ensuite, nous devons installer quelques dépendances :

• ai - Ensemble de SDK d'IA de base qui fournit des outils pour gérer les modèles d'IA, les invites et les flux de travail en JavaScript/TypeScript. Mastra est construit sur le SDK AI de Vercel, nous avons donc besoin de cette dépendance pour permettre les interactions du modèle avec votre agent.

• @ai-sdk/openai - Plugin qui connecte le SDK AI aux modèles OpenAI (comme GPT-4, GPT-4o, etc.), permettant des appels API en utilisant votre clé API OpenAI.

• @elastic/elasticsearch - Client Elasticsearch officiel pour Node.js, utilisé pour se connecter à votre Elastic Cloud ou à votre cluster local pour l'indexation, la recherche et les opérations vectorielles.

• dotenv - Charge les variables d'environnement à partir d'un fichier .env dans le fichier process.env, vous permettant d'injecter en toute sécurité des informations d'identification telles que des clés d'API et des points d'extrémité Elasticsearch.

Configuration des variables d'environnement

Créez un fichier .env dans le répertoire racine de votre projet si vous n'en avez pas déjà un. Vous pouvez également copier et renommer l'exemple .env que j'ai fourni dans le répertoire. Dans ce fichier, nous pouvons ajouter les variables suivantes :

Voilà qui conclut la configuration de base. À partir de là, vous pouvez déjà commencer à construire et à orchestrer des agents. Nous allons aller plus loin et ajouter Elasticsearch en tant que couche de stockage et de recherche vectorielle.

Ajouter Elasticsearch comme magasin de vecteurs

Créez un nouveau dossier appelé stores et ajoutez-y ce fichier. Avant que Mastra et Elastic ne proposent une intégration officielle de Elasticsearch vector store, Abhi Aiyer(Mastra CTO) a partagé ce prototype de classe appelé ElasticVector. Simplement, il relie l'abstraction mémoire de Mastra aux capacités vectorielles denses d'Elasticsearch, de sorte que les développeurs peuvent utiliser Elasticsearch comme base de données vectorielle pour leurs agents.

Examinons plus en détail les éléments importants de l'intégration :

Ingestion du client Elasticsearch

Cette section définit la classe ElasticVector et met en place la connexion du client Elasticsearch avec un support pour les déploiements standards et sans serveur.

• ElasticVectorConfig extends ClientOptions: Ceci crée une nouvelle interface de configuration qui hérite de toutes les options du client Elasticsearch (comme node, auth, requestTimeout) et ajoute nos propriétés personnalisées. Cela signifie que les utilisateurs peuvent passer n'importe quelle configuration Elasticsearch valide avec nos options spécifiques au serveur.

• extends MastraVector: Cela permet à ElasticVector d'hériter de la classe de base MastraVector de Mastra, qui est une interface commune à laquelle se conforment toutes les intégrations de magasins vectoriels. Cela garantit qu'Elasticsearch se comporte comme n'importe quel autre backend vectoriel Mastra du point de vue de l'agent.

• private client: Client: Il s'agit d'une propriété privée qui contient une instance du client JavaScript Elasticsearch. Cela permet à la classe de s'adresser directement à votre cluster.

• isServerless et deploymentChecked: Ces propriétés fonctionnent ensemble pour détecter et mettre en cache si nous sommes connectés à un déploiement Elasticsearch standard ou sans serveur. Cette détection se fait automatiquement lors de la première utilisation ou peut être configurée explicitement.

• constructor(config: ClientOptions): Ce constructeur prend un objet de configuration (contenant vos identifiants Elasticsearch et des paramètres serverless optionnels) et l'utilise pour initialiser le client dans la ligne this.client = new Client(config).

• super(): Il appelle le constructeur de base de Mastra, ce qui lui permet d'hériter de la journalisation, des aides à la validation et d'autres crochets internes.

À ce stade, Mastra sait qu'il existe un nouveau magasin de vecteurs appelé ElasticVector

Détection du type de déploiement

Avant de créer des index, l'adaptateur détecte automatiquement si vous utilisez Elasticsearch standard ou Elasticsearch Serverless. C'est important car les déploiements sans serveur ne permettent pas la configuration manuelle des shards.

Ce qui se passe :

• Vérifie d'abord si vous avez explicitement défini isServerless dans la configuration (ignore l'autodétection).

• Appelle l'API info() d'Elasticsearch pour obtenir des informations sur les clusters.

• Vérifie le build_flavor field (les déploiements sans serveur renvoient serverless).

• Renvoie à la vérification du slogan si la saveur de la construction n'est pas disponible

• Met en cache le résultat afin d'éviter les appels répétés à l'API

• Déploiement standard par défaut en cas d'échec de la détection

Exemple d'utilisation :

Création du magasin "memory" dans Elasticsearch

La fonction ci-dessous met en place un index Elasticsearch pour le stockage des embeddings. Il vérifie si l'index existe déjà. Si ce n'est pas le cas, il en crée un avec le mappage ci-dessous qui contient un champ dense_vector pour stocker les embeddings et les métriques de similarité personnalisées.

Quelques points à noter :

• Le paramètre dimension est la longueur de chaque vecteur d'intégration, qui dépend du modèle d'intégration utilisé. Dans notre cas, nous allons générer des embeddings en utilisant le modèle text-embedding-3-small d'OpenAI, qui produit des vecteurs de taille 1536. Nous l'utiliserons comme valeur par défaut.

• La variable similarity utilisée dans la correspondance ci-dessous est définie à partir de la fonction d'aide const similarity = this.mapMetricToSimilarity(metric), qui prend la valeur du paramètre metric et la convertit en un mot-clé compatible avec Elasticsearch pour la métrique de distance choisie.

  • Par exemple : Mastra utilise des termes généraux pour la similarité vectorielle comme cosine, euclidean, et dotproduct. Si nous devions passer la métrique euclidean directement dans le mappage Elasticsearch, une erreur se produirait car Elasticsearch s'attend à ce que le mot-clé l2_norm représente la distance euclidienne.

• Compatibilité sans serveur : Le code omet automatiquement les paramètres de shard et de réplique pour les déploiements sans serveur, car ils sont gérés automatiquement par Elasticsearch Serverless.

Enregistrement d'un nouveau souvenir ou d'une nouvelle note après une interaction

Cette fonction prend les nouveaux embeddings générés après chaque interaction, ainsi que les métadonnées, puis les insère ou les met à jour dans l'index à l'aide de l'API bulk d'Elastic. L'API bulk regroupe plusieurs opérations d'écriture en une seule demande ; cette amélioration de nos performances d'indexation garantit que les mises à jour restent efficaces alors que la mémoire de notre agent ne cesse de croître.

Interrogation des vecteurs similaires pour le rappel sémantique

Cette fonction est au cœur de la fonction de rappel sémantique. L'agent utilise la recherche vectorielle pour trouver des enregistrements similaires dans notre index.

Sous le capot :

• Exécute une requête kNN (k-nearest neighbors) à l'aide de l'API knn dans Elasticsearch.

• Récupère les K premiers vecteurs similaires au vecteur d'entrée de la requête.

• Possibilité d'appliquer des filtres de métadonnées pour limiter les résultats (par exemple, recherche uniquement dans une catégorie ou une période spécifique).

• Renvoie des résultats structurés comprenant l'identifiant du document, le score de similarité et les métadonnées stockées.

Création de l'agent de connaissance

Maintenant que nous avons vu la connexion entre Mastra et Elasticsearch à travers l'intégration ElasticVector, créons l'agent de connaissance lui-même.

Dans le dossier agents, créez un fichier appelé knowledge-agent.ts. Nous pouvons commencer par connecter nos variables d'environnement et initialiser le client Elasticsearch.

Ici, nous :

• Utilisez dotenv pour charger nos variables à partir de notre fichier .env.

• Vérifiez que les informations d'identification Elasticsearch sont injectées correctement et que nous pouvons établir une connexion réussie avec le client.

• Passez le point de terminaison Elasticsearch et la clé API dans le constructeur ElasticVector pour créer une instance de notre magasin vectoriel que nous avons défini plus tôt.

• Spécifiez éventuellement isServerless: true si vous utilisez Elasticsearch Serverless. Cela permet d'éviter l'étape d'autodétection et d'améliorer le temps de démarrage. S'il est omis, l'adaptateur détectera automatiquement votre type de déploiement lors de la première utilisation.

Ensuite, nous pouvons définir l'agent à l'aide de la classe Agent de Mastra.

Les champs que nous pouvons définir sont les suivants :

• name et instructions: lui donner une identité et une fonction première.

• model: Nous utilisons gpt-4o d'OpenAI à travers le paquet @ai-sdk/openai.

• memory:

  • vector: Pointe vers notre magasin Elasticsearch, de sorte que les embeddings sont stockés et récupérés à partir de ce magasin.

  • embedder: Quel modèle utiliser pour générer des embeddings ?

  • semanticRecall décident de la manière dont le rappel fonctionne :

    • topK: Nombre de messages sémantiquement similaires à récupérer.

    • messageRange: Quelle partie de la conversation doit être incluse dans chaque match.

    • scope: Définit la limite de la mémoire.

Presque terminé. Il ne nous reste plus qu'à ajouter cet agent nouvellement créé à notre configuration Mastra. Dans le fichier appelé index.ts, importez l'agent de connaissance et insérez-le dans le champ agents.

Les autres champs sont les suivants :

• storage: Il s'agit du magasin de données interne de Mastra pour l'historique des exécutions, les mesures d'observabilité, les scores et les caches. Pour plus d'informations sur le stockage Mastra, cliquez ici.

• logger: Mastra utilise Pino, qui est un enregistreur JSON structuré et léger. Il capture des événements tels que le démarrage et l'arrêt de l'agent, les appels d'outils et les résultats, les erreurs et les temps de réponse du LLM.

• observability: Contrôle le suivi de l'IA et la visibilité de l'exécution pour les agents. Il suit :

  • Début/fin de chaque étape du raisonnement.

  • Quel modèle ou outil a été utilisé.

  • Entrées et sorties.

  • Notes et évaluations

Test de l'agent avec Mastra Studio

Félicitations ! Si vous êtes arrivé jusqu'ici, vous êtes prêt à faire fonctionner cet agent et à tester ses capacités de rappel sémantique. Heureusement, Mastra fournit une interface de chat intégrée, ce qui nous évite d'avoir à créer notre propre interface.

Pour démarrer le serveur de développement Mastra, ouvrez un terminal et exécutez la commande suivante :

Après le regroupement initial et le démarrage du serveur, celui-ci devrait vous fournir une adresse pour le terrain de jeu.

Collez cette adresse dans votre navigateur et vous serez accueilli par le Mastra Studio.

Sélectionnez l'option knowledgeAgent et discutez.

Pour vérifier rapidement si tout est bien branché, donnez-lui des informations telles que : "L'équipe a annoncé que les ventes d'octobre ont augmenté de 12%, principalement grâce aux renouvellements de contrats d'entreprise. La prochaine étape consistera à élargir le champ d'action aux clients du marché intermédiaire". Ensuite, démarrez un nouveau chat et posez une question du type : "Sur quel segment de clientèle avons-nous dit que nous devions nous concentrer ensuite ?". L'agent de connaissance doit pouvoir se souvenir des informations que vous lui avez communiquées lors de la première conversation. Vous devriez obtenir une réponse du type

Une telle réponse signifie que l'agent a stocké avec succès notre message précédent sous forme d'éléments intégrés dans Elasticsearch et qu'il l'a récupéré ultérieurement à l'aide d'une recherche vectorielle.

Inspection de la mémoire à long terme de l'agent

Rendez-vous sur l'onglet memory dans la configuration de votre agent dans le Studio Mastra. Cela vous permet de voir ce que votre agent a appris au fil du temps. Chaque message, réponse et interaction qui est intégré et stocké dans Elasticsearch fait partie de cette mémoire à long terme. Vous pouvez effectuer une recherche sémantique dans les interactions passées pour retrouver rapidement les informations ou le contexte que l'agent a appris précédemment. Il s'agit essentiellement du même mécanisme que celui utilisé par l'agent lors du rappel sémantique, mais ici, vous pouvez l'inspecter directement. Dans l'exemple ci-dessous, nous recherchons le terme "ventes" et nous obtenons en retour toutes les interactions qui contiennent un élément relatif aux ventes.

Conclusion

En connectant Mastra et Elasticsearch, nous pouvons donner à nos agents de la mémoire, qui est une couche clé dans l'ingénierie contextuelle. Grâce au rappel sémantique, les agents peuvent construire un contexte au fil du temps, en fondant leurs réponses sur ce qu'ils ont appris. Cela signifie des interactions plus précises, plus fiables et plus naturelles.

Cette intégration précoce n'est que le point de départ. Le même modèle peut permettre aux agents d'assistance de se souvenir des tickets précédents, aux robots internes de retrouver la documentation pertinente ou aux assistants d'IA de se souvenir des détails d'un client au cours d'une conversation. Nous travaillons également à l'intégration officielle de Mastra, afin de rendre cette association encore plus transparente dans un avenir proche.

Nous sommes impatients de voir ce que vous allez construire. Essayez-le, explorez Mastra et ses fonctions de mémoire, et n'hésitez pas à partager vos découvertes avec la communauté.