Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Моніторинг на основі анотацій — одна анотація, багато компонентів

Цей приклад під’єднує 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 binding
    annotations:
    feature.aggrega.ai/monitoring:
    feature: core/prometheus-exporter
    maps:
    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 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 і його FeatureRecipe ServiceMonitor рівня компонента беруться зі стандартного каталогу (цей приклад не оголошує локальної копії). Чарт рецепта створює один ServiceMonitor monitoring.coreos.com/v1 на кожен під’єднаний компонент, підставляючи interval/port/path з розв’язаної анотації — усі три є параметрами збирання метрик оператора в infra функції. (Це генерування ресурсів FeatureRecipe — source: + valuesMapping:, які рендерить провайдер helm, — а не мутатор Wasm чи крок конвеєра.)

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

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

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd annotation-driven-monitoring

Збирання

Pull розв’язує lockfile, а збірка його читає:

Terminal window
aggrega pull --release release.yaml
aggrega 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:

Terminal window
aggrega pull --release release.yaml
aggrega 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Межаintervalportpath
gatewayplatform30s (типове значення платформи)metrics/metrics
api / worker / ledgerpayments15s (перевизначення)metrics/metrics
etl / reconcilebatch120s (перевизначення)metrics/metrics

Три факти, які таблиця робить наочними:

  1. На основі анотацій, а не оголошено автором. Сутність Aggregate ніде не має features: для моніторингу, проте рендеряться шість ServiceMonitor. Вони існують лише тому, що анотація розгорнула core/prometheus-exporter на кожен компонент (origin прикріплення в графі збирання — annotation, а не explicit).
  2. Глибоке злиття за підключами. payments і batch задають лише interval, проте їхні ServiceMonitor містять port: metrics і path: /metrics — успадковані зі структурованого значення анотації платформи, злиті за підключами. Піддерево перевизначає одне поле, успадковуючи сусідні.
  3. Розгалуження. Шість компонентів відстежуються з однієї анотації платформи плюс двох однорядкових перевизначень — жодного блоку features:, повтореного для кожного компонента.

ServiceMonitor збирає метрики з іменованого порту metrics сервісу Service (синтезований Service відкриває metrics: 9090), тож port: metrics прив’язки розв’язується в реальну кінцеву точку.

Час компіляції та час виконання

Це приклад для Kubernetes/Helm; доказом є відрендерені маніфести в dist/. port у ServiceMonitor посилається на іменований порт сервісу Service, тож селектор і кінцева точка збігаються за побудовою — для перевірки з’єднань кластер не потрібен. Робочий Prometheus Operator споживав би відрендерені ServiceMonitor під час розгортання; робота компілятора (анотація → ServiceMonitor для кожного компонента з каскадно розв’язаним профілем) завершена й доступна для перегляду заздалегідь.

Збірка детермінована — запустіть її повторно, і результат буде ідентичним до байта.