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ówexample/compute/service—gatewayorazapi/worker/ledger/etl/reconcile. Żaden komponent nie zawiera bloku monitorowaniafeatures:. - Encja Manifest (
manifest.yaml) wiąże adnotację z encją 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 - Encja Release (
release.yaml) ustawia adnotację raz na granicyplatformi doprecyzowuje ją w poszczególnych poddrzewach: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 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:
aggrega scaffold --example annotation-driven-monitoringNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd annotation-driven-monitoringKompilacja
Pull rozwiązuje lockfile, a build go odczytuje:
aggrega pull --release release.yamlaggrega build --release release.yamlZ 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:
aggrega pull --release release.yamlaggrega build --release release.yamlWarto 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.yamlTo 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.
| Component | Granica | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s (domyślna wartość platformy) | metrics | /metrics |
api / worker / ledger | payments | 15s (nadpisanie) | metrics | /metrics |
etl / reconcile | batch | 120s (nadpisanie) | metrics | /metrics |
Trzy fakty, które tabela czyni konkretnymi:
- 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ęłacore/prometheus-exporterna każdy komponent (originzałącznika w grafie budowania toannotation, a nieexplicit). - Głębokie scalanie według podkluczy.
paymentsibatchustawiają tylkointerval, a mimo to ich obiekty ServiceMonitor zawierająport: metricsipath: /metrics— odziedziczone ze strukturalnej wartości adnotacji platformy, scalonej według podkluczy. Poddrzewo nadpisuje jedno pole, dziedzicząc pola sąsiednie. - 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.