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 composantsexample/compute/service—gateway, etapi/worker/ledger/etl/reconcile. Aucun composant ne porte de blocfeatures: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 bindingannotations:feature.aggrega.ai/monitoring:feature: core/prometheus-exportermaps: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èreplatformet l’affine par sous-arbre :platform:annotations:feature.aggrega.ai/monitoring: {interval: 30s, port: metrics, path: /metrics} # gateway inherits thisboundaries:payments:annotations:feature.aggrega.ai/monitoring: {interval: 15s} # api/worker/ledgerbatch: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 :
aggrega scaffold --example annotation-driven-monitoringElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd annotation-driven-monitoringBuild
Le pull résout le lockfile et le build le lit :
aggrega pull --release release.yamlaggrega build --release release.yamlAvec 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 :
aggrega pull --release release.yamlaggrega build --release release.yamlCe 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.yamlC’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.
| Component | Frontière | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s (valeur par défaut de platform) | metrics | /metrics |
api / worker / ledger | payments | 15s (surcharge) | metrics | /metrics |
etl / reconcile | batch | 120s (surcharge) | metrics | /metrics |
Trois faits que le tableau rend concrets :
- 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 étenducore/prometheus-exporterà chaque composant (l’origindu rattachement dans le graphe de build estannotation, et nonexplicit). - Fusion profonde par sous-clé.
paymentsetbatchne définissent queinterval, et pourtant leurs ServiceMonitors portentport: metricsetpath: /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. - 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.