Monitoraggio guidato dalle annotazioni — un’annotazione, molti componenti
Questo esempio associa una Feature di monitoraggio a sei servizi in una topologia annidata senza scrivere un solo blocco features: per componente. Un’unica annotazione dell’operatore sul confine più esterno, affinata da due sovrascritture di sottoalbero, si espande — tramite il vincolo features.annotations del Manifest — in un’associazione di core/prometheus-exporter su ogni componente contenuto, e ciascuno renderizza il proprio ServiceMonitor di Prometheus.
Questa è la superficie dell’espansione di Feature guidata dalle annotazioni: il pattern per comprimere associazioni di Feature ripetitive per componente in un’unica annotazione che si propaga a cascata lungo l’albero dei confini.
La struttura
- L’intento dello sviluppatore (
aggregate.yaml) dichiara solo sei componentiexample/compute/service—gateway, eapi/worker/ledger/etl/reconcile. Nessun componente porta un bloccofeatures:di monitoraggio. - Il Manifest (
manifest.yaml) vincola l’annotazione alla 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) imposta l’annotazione una sola volta sul confineplatforme la affina per sottoalbero: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 e la sua FeatureRecipe ServiceMonitor con ambito di componente vengono consumati dal catalogo standard (questo esempio non ne dichiara alcuna copia locale). Il chart della ricetta emette un ServiceMonitor monitoring.coreos.com/v1 per ogni componente associato, ricavando tramite template interval/port/path dall’annotazione risolta — tutti e tre sono impostazioni di scrape dell’operatore nell’infra della funzionalità. (Si tratta della generazione di risorse della FeatureRecipe — source: + valuesMapping: renderizzati dal provider helm — non di un mutatore Wasm né di un passo di pipeline.)
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example annotation-driven-monitoringPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd annotation-driven-monitoringBuild
Il pull risolve il lockfile e la build lo legge:
aggrega pull --release release.yamlaggrega build --release release.yamlCon un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu stesso alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `annotation-driven-monitoring`, chiama una sola volta lo strumento `scaffold` con `example` impostato su `annotation-driven-monitoring` e senza `dir`: scrive l’esempio in una nuova cartella `annotation-driven-monitoring`. Poi chiama lo strumento `build` con `workspace_root` impostato su `annotation-driven-monitoring`, `release` impostato su `release.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `annotation-driven-monitoring/dist/`.Che cosa dimostra l’output renderizzato
Risolvi il lockfile, esegui il build ed esamina dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml:
aggrega pull --release release.yamlaggrega build --release release.yamlVale la pena decifrare quel nome di file, perché qui nessuno l’ha digitato. Questo target legge solo i file che si trovano direttamente in una directory, quindi i file di un’associazione finiscono accanto a quelli del componente stesso e portano le loro due coordinate nel nome del file anziché in segmenti di directory: il componente a cui la Feature è associata, poi il nome con cui è associata. Qui la seconda coordinata non è un nome che qualcuno abbia scritto — la conia l’annotazione, ed è la chiave stessa dell’annotazione, feature.aggrega.ai/monitoring. Un punto e una barra non possono entrare in un nome di file così come sono scritti, quindi ciascuno diventa -z seguito da una lettera: -zd per il punto, -zs per la barra. Per il componente api nel confine payments il build scrive
dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yamlLa codifica è il motivo per cui la barra in quella chiave non apre una directory propria — ed è proprio questo lo scopo, poiché un file un livello più in basso è un file che un consumatore di scrape-config che legge la directory del confine non raccoglierebbe.
Questo esempio consuma core/prometheus-exporter e la sua FeatureRecipe ServiceMonitor (oltre al provider helm) dalla libreria standard. Il componente dimostrativo example/compute/service e la sua ricetta si trovano nel catalogo condiviso sotto l’editore example/, accanto a quelle entità della libreria standard. Il suo .aggrega-config.yaml dichiara hub.aggrega.ai come registry predefinito, quindi le entità vengono risolte dall’hub — nessuno dei due comandi ha bisogno di un flag --catalog.
| Component | Confine | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s (predefinito di platform) | metrics | /metrics |
api / worker / ledger | payments | 15s (sovrascrittura) | metrics | /metrics |
etl / reconcile | batch | 120s (sovrascrittura) | metrics | /metrics |
Tre fatti che la tabella rende concreti:
- Guidato dalle annotazioni, non dichiarato dall’autore. L’Aggregate non ha
features:di monitoraggio da nessuna parte, eppure vengono renderizzati sei ServiceMonitor. Esistono solo perché l’annotazione ha espansocore/prometheus-exportersu ogni componente (l’origindell’associazione nel grafo di build èannotation, nonexplicit). - Deep merge per sottochiave.
paymentsebatchimpostano solointerval, eppure i loro ServiceMonitor portanoport: metricsepath: /metrics— ereditati dal valore strutturato dell’annotazione di platform, uniti sottochiave per sottochiave. Un sottoalbero sovrascrive un campo ereditando i campi fratelli. - Fan-out. Sei componenti sono monitorati a partire da una sola annotazione di platform più due sovrascritture di una riga — nessun blocco
features:ripetuto per componente.
Il ServiceMonitor esegue lo scrape della porta con nome metrics del Service (il Service sintetizzato espone metrics: 9090), quindi il port: metrics del vincolo si risolve in un endpoint reale.
Tempo di compilazione e tempo di esecuzione
Questo è un esempio Kubernetes/Helm; la prova sono i manifest renderizzati in dist/. Il port del ServiceMonitor fa riferimento alla porta con nome del Service, quindi selettore ed endpoint corrispondono per costruzione — non serve alcun cluster per verificare il cablaggio. Un Prometheus Operator in esecuzione consumerebbe i ServiceMonitor renderizzati al momento della distribuzione; il lavoro del compilatore (annotazione → ServiceMonitor per componente con il profilo risolto a cascata) è completo e ispezionabile in anticipo.
Il build è deterministico — eseguilo di nuovo e l’output è identico byte per byte.