Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Annotationsgesteuertes Monitoring — eine Annotation, viele Komponenten

Dieses Beispiel bindet ein Monitoring-Feature an sechs Dienste in einer verschachtelten Topologie an, ohne einen einzigen features:-Block pro Komponente zu schreiben. Eine einzige Betreiber-Annotation auf der obersten Boundary, verfeinert durch zwei Teilbaum-Überschreibungen, wird — über die features.annotations-Bindung des Manifest — zu einer core/prometheus-exporter-Anbindung an jeder enthaltenen Komponente expandiert, und jede rendert ihren eigenen Prometheus-ServiceMonitor.

Dies ist die Oberfläche der annotationsgesteuerten Feature-Expansion: das Muster, um sich wiederholende Feature-Anbindungen pro Komponente in eine einzige Annotation zu verdichten, die sich kaskadierend durch den Boundary-Baum fortsetzt.

Der Aufbau

  • Die Entwicklerabsicht (aggregate.yaml) deklariert nur sechs example/compute/service-Komponenten — gateway und api/worker/ledger/etl/reconcile. Keine Komponente trägt einen Monitoring-features:-Block.
  • Das Manifest (manifest.yaml) bindet die Annotation an das 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
  • Das Release (release.yaml) setzt die Annotation einmal auf der Boundary platform und verfeinert sie pro Teilbaum:
    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 und sein ServiceMonitor-FeatureRecipe mit Komponenten-Geltungsbereich werden aus dem Standardkatalog bezogen (dieses Beispiel deklariert keine lokale Kopie). Das Chart des Rezepts gibt pro angebundener Komponente einen monitoring.coreos.com/v1-ServiceMonitor aus und befüllt interval/port/path per Vorlage aus der aufgelösten Annotation — alle drei sind Scrape-Einstellungen des Betreibers im infra der Funktion. (Es handelt sich um die Ressourcengenerierung des FeatureRecipe — source: + valuesMapping:, gerendert vom helm-Provider — und nicht um einen Wasm-Mutator oder einen Pipeline-Schritt.)

Das Beispiel generieren

Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.

Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

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

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd annotation-driven-monitoring

Build

Der Pull löst die Lockfile auf, und der Build liest sie:

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

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `annotation-driven-monitoring` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `annotation-driven-monitoring` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `annotation-driven-monitoring`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `annotation-driven-monitoring`, `release` auf `release.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `annotation-driven-monitoring/dist/`.

Was die gerenderte Ausgabe belegt

Lösen Sie das Lockfile auf, führen Sie den Build aus und sehen Sie sich dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml an:

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

Dieser Dateiname lohnt eine Entschlüsselung, denn niemand hat ihn hier eingetippt. Dieses Ziel liest nur die Dateien, die direkt in einem Verzeichnis liegen, daher landen die Dateien einer Anbindung neben denen der Komponente selbst und tragen ihre zwei Koordinaten im Dateinamen statt in Verzeichnissegmenten: die Komponente, an die das Feature angebunden ist, dann den Namen, unter dem es angebunden ist. Hier ist die zweite Koordinate kein Name, den jemand geschrieben hat — die Annotation prägt ihn, und er ist der Annotationsschlüssel selbst, feature.aggrega.ai/monitoring. Ein Punkt und ein Schrägstrich können nicht so, wie sie geschrieben sind, in einen Dateinamen, daher wird jeder zu -z und einem Buchstaben: -zd für den Punkt, -zs für den Schrägstrich. Für die Komponente api in der Boundary payments schreibt der Build

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

Die Kodierung ist der Grund, warum der Schrägstrich in diesem Schlüssel kein eigenes Verzeichnis öffnet — und genau darum geht es, denn eine Datei eine Ebene tiefer ist eine Datei, die ein Scrape-Config-Konsument, der das Boundary-Verzeichnis liest, nicht aufgreifen würde.

Dieses Beispiel bezieht core/prometheus-exporter und sein ServiceMonitor-FeatureRecipe (sowie den helm-Provider) aus der Standardbibliothek. Die Demo-Komponente example/compute/service und ihr Rezept liegen im gemeinsamen Katalog unter dem Herausgeber example/, neben diesen Entitäten der Standardbibliothek. Sein .aggrega-config.yaml deklariert hub.aggrega.ai als Standard-Registry, daher werden die Entitäten aus dem Hub aufgelöst — keiner der beiden Befehle braucht ein --catalog-Flag.

ComponentBoundaryintervalportpath
gatewayplatform30s (Voreinstellung von platform)metrics/metrics
api / worker / ledgerpayments15s (Überschreibung)metrics/metrics
etl / reconcilebatch120s (Überschreibung)metrics/metrics

Drei Fakten, die die Tabelle konkret macht:

  1. Annotationsgesteuert, nicht vom Autor deklariert. Das Aggregate hat nirgends Monitoring-features:, und doch werden sechs ServiceMonitors gerendert. Sie existieren nur, weil die Annotation core/prometheus-exporter auf jede Komponente expandiert hat (der origin der Anbindung im Build-Graphen ist annotation, nicht explicit).
  2. Deep Merge pro Unterschlüssel. payments und batch setzen nur interval, und doch tragen ihre ServiceMonitors port: metrics und path: /metrics — geerbt vom strukturierten Wert der platform-Annotation, pro Unterschlüssel zusammengeführt. Ein Teilbaum überschreibt ein Feld und erbt dabei seine Geschwisterfelder.
  3. Fan-out. Sechs Komponenten werden über eine platform-Annotation plus zwei einzeilige Überschreibungen überwacht — kein features:-Block, der pro Komponente wiederholt wird.

Der ServiceMonitor scrapt den benannten Port metrics des Service (der synthetisierte Service stellt metrics: 9090 bereit), daher wird das port: metrics der Bindung zu einem realen Endpunkt aufgelöst.

Kompilierzeit und Laufzeit

Dies ist ein Kubernetes/Helm-Beispiel; der Beleg sind die gerenderten Manifeste in dist/. Der port des ServiceMonitor verweist auf den benannten Port des Service, daher passen Selektor und Endpunkt konstruktionsbedingt zusammen — zur Überprüfung der Verdrahtung wird kein Cluster benötigt. Ein laufender Prometheus Operator würde die gerenderten ServiceMonitors zum Zeitpunkt der Bereitstellung verarbeiten; die Arbeit des Compilers (Annotation → ServiceMonitor pro Komponente mit dem per Kaskade aufgelösten Profil) ist vollständig und vorab überprüfbar.

Der Build ist deterministisch — führen Sie ihn erneut aus, und die Ausgabe ist byte-identisch.