Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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 componenti example/compute/service — gateway, e api/worker/ledger/etl/reconcile. Nessun componente porta un blocco features: 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 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) imposta l’annotazione una sola volta sul confine platform e la affina per sottoalbero:
    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 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:

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

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd annotation-driven-monitoring

Build

Il pull risolve il lockfile e la build lo legge:

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

Con 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:

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

Vale 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.yaml

La 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.

ComponentConfineintervalportpath
gatewayplatform30s (predefinito di platform)metrics/metrics
api / worker / ledgerpayments15s (sovrascrittura)metrics/metrics
etl / reconcilebatch120s (sovrascrittura)metrics/metrics

Tre fatti che la tabella rende concreti:

  1. 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 espanso core/prometheus-exporter su ogni componente (l’origin dell’associazione nel grafo di build è annotation, non explicit).
  2. Deep merge per sottochiave. payments e batch impostano solo interval, eppure i loro ServiceMonitor portano port: metrics e path: /metrics — ereditati dal valore strutturato dell’annotazione di platform, uniti sottochiave per sottochiave. Un sottoalbero sovrascrive un campo ereditando i campi fratelli.
  3. 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.