Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Monitorowanie sterowane adnotacjami — jedna adnotacja, wiele komponentów

Ten przykład dołącza Feature monitorowania do sześciu usług w zagnieżdżonej topologii bez pisania ani jednego bloku features: dla poszczególnych komponentów. Jedna adnotacja operatora na najwyższej granicy, doprecyzowana dwoma nadpisaniami w poddrzewach, rozwija się — poprzez powiązanie features.annotations w encji Manifest — w dołączenie core/prometheus-exporter do każdego zawartego komponentu, a każdy z nich renderuje własny ServiceMonitor Prometheusa.

To jest mechanizm rozwijania Feature sterowanego adnotacjami: wzorzec kompresowania powtarzalnych dołączeń Feature do poszczególnych komponentów w jedną adnotację, która kaskadowo schodzi w dół drzewa granic.

Struktura

  • Intencja programisty (aggregate.yaml) deklaruje jedynie sześć komponentów example/compute/service — gateway oraz api/worker/ledger/etl/reconcile. Żaden komponent nie zawiera bloku monitorowania features:.
  • Encja Manifest (manifest.yaml) wiąże adnotację z encją 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
  • Encja Release (release.yaml) ustawia adnotację raz na granicy platform i doprecyzowuje ją w poszczególnych poddrzewach:
    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 i jego FeatureRecipe ServiceMonitor o zasięgu komponentu są pobierane ze standardowego katalogu (ten przykład nie deklaruje lokalnej kopii). Chart tej receptury emituje jeden ServiceMonitor monitoring.coreos.com/v1 na każdy dołączony komponent, szablonując interval/port/path na podstawie rozwiązanej adnotacji — wszystkie trzy są parametrami scrapowania operatora w sekcji infra tej funkcji. (Jest to generowanie zasobów przez FeatureRecipe — source: + valuesMapping: renderowane przez dostawcę helm — a nie mutator Wasm ani krok potoku).

Generowanie przykładu

Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd annotation-driven-monitoring

Kompilacja

Pull rozwiązuje lockfile, a build go odczytuje:

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

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `annotation-driven-monitoring`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `annotation-driven-monitoring` i bez `dir`: zapisze ono przykład w nowym folderze `annotation-driven-monitoring`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `annotation-driven-monitoring`, `release` ustawionym na `release.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisało budowanie; znajdują się w `annotation-driven-monitoring/dist/`.

Co dowodzi wyrenderowany wynik

Należy rozwiązać plik blokady, zbudować przykład i sprawdzić 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

Warto rozszyfrować tę nazwę pliku, ponieważ nikt jej tu nie wpisał. Ten cel odczytuje tylko pliki leżące bezpośrednio w katalogu, więc pliki dołączenia trafiają obok własnych plików komponentu i niosą swoje dwie współrzędne w nazwie pliku zamiast w segmentach katalogów: komponent, do którego dołączono Feature, a następnie nazwę, pod którą go dołączono. Tutaj druga współrzędna nie jest nazwą, którą ktokolwiek napisał — wybija ją adnotacja i jest nią sam klucz adnotacji, feature.aggrega.ai/monitoring. Kropka i ukośnik nie mogą trafić do nazwy pliku w postaci dosłownej, więc każde z nich staje się -z i literą: -zd dla kropki, -zs dla ukośnika. Dla komponentu api w granicy payments build zapisuje

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

To kodowanie sprawia, że ukośnik w tym kluczu nie otwiera własnego katalogu — i o to właśnie chodzi, ponieważ pliku o jeden poziom niżej konsument konfiguracji scrapowania odczytujący katalog granicy by nie pobrał.

Ten przykład pobiera core/prometheus-exporter i jego FeatureRecipe ServiceMonitor (oraz provider helm) z biblioteki standardowej. Demonstracyjny komponent example/compute/service i jego receptura znajdują się we wspólnym katalogu pod wydawcą example/, obok tych encji biblioteki standardowej. Jego plik .aggrega-config.yaml deklaruje hub.aggrega.ai jako domyślny rejestr, więc encje są rozwiązywane z huba — żadne z poleceń nie wymaga flagi --catalog.

ComponentGranicaintervalportpath
gatewayplatform30s (domyślna wartość platformy)metrics/metrics
api / worker / ledgerpayments15s (nadpisanie)metrics/metrics
etl / reconcilebatch120s (nadpisanie)metrics/metrics

Trzy fakty, które tabela czyni konkretnymi:

  1. Sterowane adnotacjami, a nie deklarowane przez autora. Encja Aggregate nigdzie nie ma monitorowania features:, a mimo to renderuje się sześć obiektów ServiceMonitor. Istnieją wyłącznie dlatego, że adnotacja rozwinęła core/prometheus-exporter na każdy komponent (origin załącznika w grafie budowania to annotation, a nie explicit).
  2. Głębokie scalanie według podkluczy. payments i batch ustawiają tylko interval, a mimo to ich obiekty ServiceMonitor zawierają port: metrics i path: /metrics — odziedziczone ze strukturalnej wartości adnotacji platformy, scalonej według podkluczy. Poddrzewo nadpisuje jedno pole, dziedzicząc pola sąsiednie.
  3. Rozgałęzienie (fan-out). Sześć komponentów jest monitorowanych na podstawie jednej adnotacji platformy oraz dwóch jednowierszowych nadpisań — bez bloku features: powtarzanego dla każdego komponentu.

ServiceMonitor scrapuje nazwany port metrics obiektu Service (syntetyzowany Service udostępnia metrics: 9090), więc port: metrics z powiązania rozwiązuje się do rzeczywistego punktu końcowego.

Czas kompilacji a czas wykonania

To przykład dla Kubernetes/Helm; dowodem są wyrenderowane manifesty w dist/. Pole port obiektu ServiceMonitor odwołuje się do nazwanego portu obiektu Service, więc selektor i punkt końcowy pasują do siebie z założenia — do weryfikacji połączeń nie jest potrzebny klaster. Działający Prometheus Operator pobrałby wyrenderowane obiekty ServiceMonitor w czasie wdrożenia; zadanie kompilatora (adnotacja → ServiceMonitor dla każdego komponentu z profilem rozwiązanym kaskadowo) jest zakończone i możliwe do sprawdzenia z wyprzedzeniem.

Build jest deterministyczny — po ponownym uruchomieniu wynik jest identyczny co do bajtu.