Моніторинг на основі анотацій — одна анотація, багато компонентів
Цей приклад під’єднує Feature моніторингу до шести сервісів у вкладеній
топології, не написавши жодного окремого блоку features: для компонента. Одна
анотація оператора на верхній межі, уточнена двома перевизначеннями піддерев,
розгортається — через прив’язку features.annotations у Manifest — у
під’єднання core/prometheus-exporter до кожного вкладеного компонента, і кожен з них рендерить
власний Prometheus ServiceMonitor.
Це поверхня розгортання Feature на основі анотацій: шаблон для стискання повторюваних під’єднань Feature до окремих компонентів в одну анотацію, що каскадно поширюється деревом меж.
Структура
- Намір розробника (
aggregate.yaml) оголошує лише шість компонентівexample/compute/service—gatewayтаapi/worker/ledger/etl/reconcile. Жоден компонент не має блоку моніторингуfeatures:. - Сутність Manifest (
manifest.yaml) прив’язує анотацію до 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 - Сутність Release (
release.yaml) задає анотацію один раз на межіplatformі уточнює її для кожного піддерева: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 і його FeatureRecipe ServiceMonitor рівня компонента беруться зі стандартного каталогу (цей приклад не оголошує локальної копії). Чарт рецепта створює один ServiceMonitor monitoring.coreos.com/v1 на кожен під’єднаний компонент, підставляючи interval/port/path з розв’язаної анотації — усі три є параметрами збирання метрик оператора в infra функції. (Це генерування ресурсів FeatureRecipe — source: + valuesMapping:, які рендерить провайдер helm, — а не мутатор Wasm чи крок конвеєра.)
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example annotation-driven-monitoringПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd annotation-driven-monitoringЗбирання
Pull розв’язує lockfile, а збірка його читає:
aggrega pull --release release.yamlaggrega build --release release.yamlЗ ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `annotation-driven-monitoring`, викличте один раз інструмент `scaffold`, задавши для `example` значення `annotation-driven-monitoring` і не задаючи `dir`: він запише приклад у нову теку `annotation-driven-monitoring`. Потім викличте інструмент `build`, задавши для `workspace_root` значення `annotation-driven-monitoring`, для `release` — `release.yaml`, для `auto_pull` — true і для `write` — true. Скажіть мені, які файли записала збірка; вони лежать у `annotation-driven-monitoring/dist/`.Що доводить відрендерений результат
Розв’яжіть lockfile, зберіть його та перегляньте dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml:
aggrega pull --release release.yamlaggrega build --release release.yamlЦю назву файлу варто розшифрувати, бо ніхто тут її не вводив. Ця ціль
читає лише файли, що лежать безпосередньо в каталозі, тож файли під’єднання
опиняються поруч із власними файлами компонента й несуть свої дві координати в назві файлу,
а не в сегментах каталогу: компонент, до якого під’єднано Feature, а потім
ім’я, під яким його під’єднано. Тут друга координата — не ім’я, яке хтось
написав: її створює анотація, і це сам ключ анотації,
feature.aggrega.ai/monitoring. Крапка й скісна риска не можуть увійти в назву файлу
як є, тож кожна стає -z і літерою: -zd для крапки, -zs для
скісної риски. Для компонента api у межі payments збірка записує
dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yamlСаме через кодування скісна риска в цьому ключі не відкриває окремого каталогу — і в цьому суть, адже файл на рівень нижче — це файл, якого споживач конфігурації збирання метрик, що читає каталог межі, не підхопив би.
Цей приклад бере core/prometheus-exporter і його FeatureRecipe ServiceMonitor (а також провайдер helm) зі стандартної бібліотеки. Демонстраційний компонент example/compute/service і його рецепт містяться в спільному каталозі під видавцем example/, поруч із цими сутностями стандартної бібліотеки. Його .aggrega-config.yaml оголошує hub.aggrega.ai реєстром за замовчуванням, тож сутності розв’язуються з хабу — жодній із команд не потрібен прапорець --catalog.
| Component | Межа | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s (типове значення платформи) | metrics | /metrics |
api / worker / ledger | payments | 15s (перевизначення) | metrics | /metrics |
etl / reconcile | batch | 120s (перевизначення) | metrics | /metrics |
Три факти, які таблиця робить наочними:
- На основі анотацій, а не оголошено автором. Сутність Aggregate ніде не має
features:для моніторингу, проте рендеряться шість ServiceMonitor. Вони існують лише тому, що анотація розгорнулаcore/prometheus-exporterна кожен компонент (originприкріплення в графі збирання —annotation, а неexplicit). - Глибоке злиття за підключами.
paymentsіbatchзадають лишеinterval, проте їхні ServiceMonitor містятьport: metricsіpath: /metrics— успадковані зі структурованого значення анотації платформи, злиті за підключами. Піддерево перевизначає одне поле, успадковуючи сусідні. - Розгалуження. Шість компонентів відстежуються з однієї анотації платформи
плюс двох однорядкових перевизначень — жодного блоку
features:, повтореного для кожного компонента.
ServiceMonitor збирає метрики з іменованого порту metrics сервісу Service (синтезований
Service відкриває metrics: 9090), тож port: metrics прив’язки розв’язується в
реальну кінцеву точку.
Час компіляції та час виконання
Це приклад для Kubernetes/Helm; доказом є відрендерені маніфести в
dist/. port у ServiceMonitor посилається на іменований порт сервісу Service, тож
селектор і кінцева точка збігаються за побудовою — для перевірки з’єднань кластер
не потрібен. Робочий Prometheus Operator споживав би відрендерені ServiceMonitor під час
розгортання; робота компілятора (анотація → ServiceMonitor для кожного компонента з
каскадно розв’язаним профілем) завершена й доступна для перегляду заздалегідь.
Збірка детермінована — запустіть її повторно, і результат буде ідентичним до байта.