Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Surveillance pilotée par annotation — une annotation, de nombreux composants

Cet exemple rattache une Feature de surveillance à six services répartis dans une topologie imbriquée sans écrire un seul bloc features: par composant. Une seule annotation de l’opérateur sur la frontière de plus haut niveau, affinée par deux surcharges de sous-arbre, s’étend — via la liaison features.annotations du Manifest — en un rattachement de core/prometheus-exporter sur chaque composant contenu, et chacun rend son propre ServiceMonitor Prometheus.

C’est la surface d’expansion de Feature pilotée par annotation : le motif qui permet de condenser des rattachements de Feature répétitifs par composant en une seule annotation qui se propage en cascade dans l’arbre des frontières.

La structure

  • L’intention du développeur (aggregate.yaml) ne déclare que six composants example/compute/service — gateway, et api/worker/ledger/etl/reconcile. Aucun composant ne porte de bloc features: de surveillance.
  • Le Manifest (manifest.yaml) lie l’annotation à la Feature :
    features:
    type:
    core/prometheus-exporter: helm/prometheus-exporter:1.0.0 # the FeatureRecipe version binding
    annotations:
    feature.aggrega.ai/monitoring:
    feature: core/prometheus-exporter
    maps:
    infra: [interval, port, path] # structured-value subkeys → the feature's infra
  • La Release (release.yaml) définit l’annotation une seule fois sur la frontière platform et l’affine par sous-arbre :
    platform:
    annotations:
    feature.aggrega.ai/monitoring: {interval: 30s, port: metrics, path: /metrics} # gateway inherits this
    boundaries:
    payments:
    annotations:
    feature.aggrega.ai/monitoring: {interval: 15s} # api/worker/ledger
    batch:
    annotations:
    feature.aggrega.ai/monitoring: {interval: 120s} # etl/reconcile

core/prometheus-exporter et sa FeatureRecipe ServiceMonitor à portée de composant sont consommés depuis le catalogue standard (cet exemple n’en déclare aucune copie locale). Le chart de la recette émet un ServiceMonitor monitoring.coreos.com/v1 par composant rattaché, en générant par template interval/port/path à partir de l’annotation résolue — tous trois sont des réglages de scrape de l’opérateur dans l’infra de la fonctionnalité. (Il s’agit de la génération de ressources de FeatureRecipe — source: + valuesMapping: rendus par le fournisseur helm — et non d’un mutateur Wasm ni d’une étape de pipeline.)

Générer l’exemple

Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

Terminal window
aggrega scaffold --example annotation-driven-monitoring

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd annotation-driven-monitoring

Build

Le pull résout le lockfile et le build le lit :

Terminal window
aggrega pull --release release.yaml
aggrega build --release release.yaml

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `annotation-driven-monitoring`, appelez une seule fois l’outil `scaffold` avec `example` défini sur `annotation-driven-monitoring` et sans `dir` : il écrit l’exemple dans un nouveau dossier `annotation-driven-monitoring`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `annotation-driven-monitoring`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `annotation-driven-monitoring/dist/`.

Ce que prouve la sortie rendue

Résolvez le lockfile, lancez le build et examinez dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml :

Terminal window
aggrega pull --release release.yaml
aggrega build --release release.yaml

Ce nom de fichier mérite d’être décodé, car personne ici ne l’a saisi. Cette cible ne lit que les fichiers situés directement dans un répertoire, si bien que les fichiers d’un rattachement se retrouvent à côté de ceux du composant lui-même et portent leurs deux coordonnées dans le nom du fichier plutôt que dans des segments de répertoire : le composant auquel la Feature est rattachée, puis le nom sous lequel elle est rattachée. Ici, la seconde coordonnée n’est pas un nom que quelqu’un a écrit — l’annotation le forge, et c’est la clé d’annotation elle-même, feature.aggrega.ai/monitoring. Un point et une barre oblique ne peuvent pas entrer tels quels dans un nom de fichier, si bien que chacun devient -z suivi d’une lettre : -zd pour le point, -zs pour la barre oblique. Pour le composant api dans la frontière payments, le build écrit

dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yaml

C’est à cause de cet encodage que la barre oblique de cette clé n’ouvre pas de répertoire à elle — et c’est tout l’intérêt, car un fichier situé un niveau plus bas est un fichier qu’un consommateur de scrape-config lisant le répertoire de la frontière ne prendrait pas en compte.

Cet exemple consomme core/prometheus-exporter et sa FeatureRecipe ServiceMonitor (ainsi que le fournisseur helm) depuis la bibliothèque standard. Le composant de démonstration example/compute/service et sa recette se trouvent dans le catalogue partagé sous l’éditeur example/, aux côtés de ces entités de la bibliothèque standard. Son .aggrega-config.yaml déclare hub.aggrega.ai comme registre par défaut, si bien que les entités sont résolues depuis le hub — aucune des deux commandes n’a besoin d’une option --catalog.

ComponentFrontièreintervalportpath
gatewayplatform30s (valeur par défaut de platform)metrics/metrics
api / worker / ledgerpayments15s (surcharge)metrics/metrics
etl / reconcilebatch120s (surcharge)metrics/metrics

Trois faits que le tableau rend concrets :

  1. Piloté par annotation, et non déclaré par l’auteur. L’Aggregate n’a aucun features: de surveillance nulle part, et pourtant six ServiceMonitors sont rendus. Ils n’existent que parce que l’annotation a étendu core/prometheus-exporter à chaque composant (l’origin du rattachement dans le graphe de build est annotation, et non explicit).
  2. Fusion profonde par sous-clé. payments et batch ne définissent que interval, et pourtant leurs ServiceMonitors portent port: metrics et path: /metrics — hérités de la valeur structurée de l’annotation de platform, fusionnée sous-clé par sous-clé. Un sous-arbre surcharge un champ tout en héritant de ses champs voisins.
  3. Fan-out. Six composants sont surveillés à partir d’une annotation de platform plus deux surcharges d’une ligne — aucun bloc features: répété par composant.

Le ServiceMonitor scrape le port nommé metrics du Service (le Service synthétisé expose metrics: 9090), si bien que le port: metrics de la liaison se résout en un endpoint réel.

Temps de compilation et temps d’exécution

Ceci est un exemple Kubernetes/Helm ; la preuve, ce sont les manifestes rendus dans dist/. Le port du ServiceMonitor référence le port nommé du Service, si bien que le sélecteur et l’endpoint correspondent par construction — aucun cluster n’est nécessaire pour vérifier le câblage. Un Prometheus Operator en fonctionnement consommerait les ServiceMonitors rendus au moment du déploiement ; le travail du compilateur (annotation → ServiceMonitor par composant avec le profil résolu en cascade) est complet et inspectable à l’avance.

Le build est déterministe — relancez-le et la sortie est identique octet pour octet.