Політика, що приєднує сутності Features, яких ніхто не писав: анотації, впроваджені на етапі `annotation-transform`
Політика керування надає кожному компоненту магазину моніторинг платформи та роль AWS IAM. Вона робить це, додаючи анотації. Manifest прив’язує два ключі анотацій до двох сутностей Features, і анотація під прив’язаним ключем розгортається у вкладення Feature. Тож анотації, які додає політика, приносять кожному компоненту Prometheus ServiceMonitor і Kubernetes ServiceAccount, а ні Aggregate, ні Release не записують жодного з них.
Політику приєднано в ролі annotation-transform — по одному разу для кожного рушія політик, скомпільованого в CLI: Rego і CEL. Головний доказ — контрольна сутність Release, у якій ті самі анотації записано вручну. Зібрана без політики, вона рендерить ті самі файли, байт у байт, що й Release, яку анотує політика.
Що він збирає
| екземпляр | Component із каталогу | що він містить у release.yaml |
|---|---|---|
api | example/compute/service | нічого |
worker | example/compute/service | нічого |
gateway | example/compute/service | власна анотація моніторингу з інтервалом 10 секунд |
Усі три компілюються в Kubernetes через Helm, у dist/shop/helm/. example/compute/service — демонстраційна сутність Component у каталозі стандартної бібліотеки. Кожен її екземпляр мусить мати вкладення core/prometheus-exporter — це вимога, яку формулює Component і перевіряє збірка.
Дві прив’язки анотацій
manifest.yaml надає значення двом ключам анотацій:
features: type: core/prometheus-exporter: helm/prometheus-exporter:1.0.0 core/aws-irsa: helm/aws-irsa:1.0.0 annotations: feature.aggrega.ai/monitoring: feature: core/prometheus-exporter maps: infra: - interval - port - path aws-role: feature: core/aws-irsa maps: infra: - role_arnПрив’язка, що маршрутизує кілька підключів, приймає як значення об’єкт, який називає кожен із них, тож feature.aggrega.ai/monitoring приймає {interval: …, port: …, path: …}. Прив’язка, що маршрутизує один підключ, приймає рядок, тож aws-role приймає ARN ролі. Приєднання, на яке розгортається анотація, отримує назву за своїм ключем. core/aws-irsa називає свій ServiceAccount за приєднанням, тому цей ключ не містить ані крапки, ані скісної риски.
Під’єднання політики
.aggrega-config.yaml називає hub своїм реєстром, не вказує жодної теки каталогу й не містить під’єднання керування. Політику під’єднує файл, який збірка вказує через --config: governance-rego.yaml для рушія Rego, governance-cel.yaml для рушія CEL. Файл для Rego виглядає так:
plugins: governance: - uri: governance/rego:0.9.0 role: annotation-transform with: sources: - policies/platform-defaults.rego--config вказує глобальний файл конфігурації для цього запуску замість того, який машина прочитала б інакше, а .aggrega-config.yaml цього робочого простору й далі накладається поверх нього.
0.9.0 — це версія, у якій hub публікує сутність Plugin кожного рушія, тож приєднання розв’язується з реєстру, який читає робочий простір, або з бінарного файлу aggrega цього випуску, який її містить. Працює той рушій, що вкомпільований у бінарний файл aggrega, який виконує збірку, хоч би яку версію називало приєднання. Об’єкт, який приймає анотація моніторингу, потребує рушія, що вміє впроваджувати об’єкт підключів, а рушії випусків до 0.8.7 цього не вміють.
Що читає політика annotation-transform
Політика на annotation-transform читає дві речі:
input.targetsперелічує кожен компонент, який вона може анотувати. Кожна ціль маєboundary_path,component_nameіannotations, які сутність Release записує на цей компонент, кожне значення — у тому вигляді, у якому його записано.input.binding_keysперелічує ключі анотацій, які прив’язує сутність Manifest.
aggrega build --release <release> --dry-run --policy-input <dir> записує корисне навантаження, яке отримує кожна роль, у <dir> і більше нічого не записує. Після того як збірка release.yaml заповнила свій lock-файл:
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '.binding_keys' payloads/annotation-transform.json# ["feature.aggrega.ai/monitoring","aws-role"]jq -c '.targets[]' payloads/annotation-transform.json# {"boundary_path":"shop","component_name":"api","annotations":{}}# {"boundary_path":"shop","component_name":"worker","annotations":{}}# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}annotations цілі містять те, що сутність Release записує на сам компонент. aggrega.ai/namespace межі серед них немає.
Політика
policies/platform-defaults.rego збирає по одному рішенню на анотацію в annotations. Кожне рішення називає ціль за двома полями, під якими її було прочитано, потім ключ і значення:
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": monitoring, "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { monitoring in input.binding_keys some t in input.targets not monitoring in object.keys(t.annotations)}
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": role, "annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),} if { role in input.binding_keys some t in input.targets not role in object.keys(t.annotations)}Кожне правило спрацьовує лише для ключа з input.binding_keys, тож політика не додає нічого, чому сутність Manifest не надала значення. Кожне правило також пропускає ціль, яка вже має цей ключ. Рішення щодо ключа, який компонент уже має, замінює значення, записане в Release. Без цієї перевірки gateway втратив би свій 10-секундний інтервал на користь 30 секунд політики.
policies/platform-defaults.cel виражає ті самі два рішення одним виразом, з’єднуючи два списки через +. Ключ мапи перевіряється через in, а не через object.keys, а ARN ролі склеюється через +, бо мова виразів не має sprintf. Половина виразу, що стосується ролі, виглядає так:
+ input.targets .filter(t, "aws-role" in input.binding_keys && !("aws-role" in t.annotations)) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "aws-role", "annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name, }),Що рендерить збірка
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullзаписує дванадцять файлів у dist/shop/helm/: Deployment і Service для кожного компонента, ServiceMonitor, на який розгортається його анотація моніторингу, і ServiceAccount, на який розгортається його анотація aws-role. spec ServiceMonitor компонента api, отриманий з анотації, яку впровадила політика:
spec: selector: matchLabels: app.kubernetes.io/name: api endpoints: - port: metrics interval: 30s path: /metricsУ gateway він містить interval: 10s — значення, яке записує його запис у Release. ServiceAccount, під яким працює api, отриманий з упровадженої aws-role:
apiVersion: v1kind: ServiceAccountmetadata: name: api-aws-role namespace: shop annotations: eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api" aggrega.ai/boundary-path: shop aggrega.ai/recipe-uri: "aws-irsa:1.0.0" [… omitted: the labels, which carry the version of the aggrega binary that built the file]Упроваджено чи написано вручну: ті самі файли
release-by-hand.yaml — це release.yaml, у якому анотації, що їх упроваджує політика, записано на кожному компоненті вручну. Зібраний без під’єднаної політики,
aggrega build --release release-by-hand.yaml --auto-pullвін записує ті самі дванадцять файлів, байт у байт, що й release.yaml з політикою, під’єднаною на будь-якому з рушіїв. З цього порівняння нічого не виключено: те, чи було анотацію впроваджено, не записано в жодному відрендереному файлі. check.sh порівнює дерева під час кожного запуску.
Збірка читає впроваджене значення точно так само, як читає те саме значення, записане в Release, тож значення розгортається на те саме приєднання.
Де записано впровадження
Його записує граф збірки, а --ir-graph виводить граф. Кожен компонент, що отримав упроваджену анотацію, має серед своїх анотацій Release aggrega.ai/injected-by з назвою плагіна. Після aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph компонент api виглядає так:
"release_annotations": { "aggrega.ai/namespace": "shop", "aws-role": "arn:aws:iam::123456789012:role/shop-api", "aggrega.ai/injected-by": "governance/rego"},Запис ведеться за компонентами, а не за ключами: gateway теж його має — через свою aws-role. Кожне приєднання, на яке розгорнулися анотації, має в графі "origin": "annotation", як і для анотації, написаної вручну.
Ціль Helm не рендерить анотацію aggrega.ai/injected-by і повідомляє про це. У цій збірці кожен компонент, що отримав упровадження, додає до виводу три попередження. Перше з попереджень для api:
warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it--no-unsupported-field-warnings вимикає цей клас попереджень і нічого не змінює в тому, що записує збірка.
Роль додає анотації й нічого більше
Рішення називає один компонент, один ключ анотації та його значення. Ніщо в рішенні не додає компонент, не змінює мітку й не приєднує Feature безпосередньо. Політика досягає Feature лише через ключ, який прив’язує сутність Manifest, і саме Manifest вирішує, яка це Feature.
Рішення не може й видалити анотацію. Його значення — рядок або об’єкт підключів, а null відхиляється з указанням упровадження, бо null — це спосіб, у який автор виключає компонент з анотації, яку той інакше успадкував би.
Рядок там, де прив’язка маршрутизує три підключі
governance-monitoring-as-string.yaml під’єднує policies/monitoring-as-string.rego, яка впроваджує рядок "30s" під ключем моніторингу. Ця прив’язка маршрутизує три підключі, а рядок не називає жодного з них, тож
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pullзупиняється, завершується з кодом 1 і не записує dist/. Політика впровадила рядок в api і в worker, і кожне впровадження відхиляється. Кожна відмова називає плагін, що впровадив значення, і роль, до якої його під’єднано, тож значення простежується до політики, яка його вирішила, а не до рядка Release, якого ніхто не писав:
[… omitted: a warning that the attachment is in the global configuration named with --config][OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")---[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")Без політики
release.yaml, зібраний без під’єднання керування,
aggrega build --release release.yaml --auto-pullзупиняється. Його сутність Component вимагає приєднання core/prometheus-exporter, і ніщо не надає його ні api, ні worker:
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")gateway не названо, бо його запис у Release задає власний моніторинг. З під’єднаною політикою та сама сутність Release збирається: приєднання, на яке розгортається впроваджена анотація, задовольняє вимогу так само, як написане вручну.
Що записує lock-файл
Під’єднання annotation-transform змінює те, що рендерить збірка, тож lock-файл закріплює його. Після збірки з Rego release.lock містить під’єднання в mutators: — з його плагіном, роллю, а також вмістом і дайджестом файлу політики:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.regoВін також закріплює плагін у plugins::
plugins: - uri: governance/rego [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/rego:0.9.0Під’єднання називає версію, яку публікує hub, тож закріплення розв’язується через реєстр, який читає робочий простір, або з бінарного файлу aggrega цього випуску.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example policy-annotation-transformПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd policy-annotation-transformЗбирання
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullaggrega build --release release.yaml --config governance-cel.yaml --auto-pullaggrega build --release release-by-hand.yaml --auto-pullКаталог стандартної бібліотеки надає кожну сутність Component, Feature, Recipe і FeatureRecipe тут, а також сутності Plugin обох рушіїв. Вони розв’язуються з hub.aggrega.ai — типового реєстру, який називає .aggrega-config.yaml. Якщо локальну копію каталогу (де її отримати) вказано через --catalog, нічого не завантажується з реєстру, тож збірки працюють офлайн. --auto-pull заповнює lock-файл кожної сутності Release під час збірки. Lock-файли й відрендерений вивід генеруються, а не постачаються.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека Workspace ще не містить теки `policy-annotation-transform`, викличте один раз інструмент `scaffold`, задавши для `example` значення `policy-annotation-transform` і не задаючи `dir`: він запише приклад у нову теку `policy-annotation-transform`. Потім викличте інструмент `cli-build`, який запускає `aggrega build` і приймає його прапорець `--config`, задавши для `workspace_root` значення `policy-annotation-transform`, для `release` — `release.yaml`, для `auto_pull` — true і для `config` — `governance-rego.yaml`; потім викличте його ще раз так само, задавши для `config` значення `governance-cel.yaml`. Наостанок викличте інструмент `build`, задавши для `workspace_root` значення `policy-annotation-transform`, для `release` — `release-by-hand.yaml`, для `auto_pull` — true і для `write` — true. Скажіть мені, які файли записала кожна збірка; вони розташовані в `policy-annotation-transform/dist/`.Перевірка кожної збірки
Ця самоперевірка виконується в робочій копії репозиторію документації, яка містить потрібний їй спільний допоміжний скрипт збирання; копія, записана aggrega scaffold --example, цього скрипту не містить.
./check.shcheck.sh виконує п’ять збірок через допоміжний скрипт build-release і звіряє кожен результат з тим, який описує ця сторінка:
release-by-hand.yamlбез політики — еталон. Він має відрендерити шість файлів, на які розгортаються анотації.release.yamlбез політики має зупинитися зE0162дляapiіworkerі для жодного іншого компонента.release.yamlз політикою збирається по одному разу на кожному рушії. Кожна збірка має записати файли еталона байт у байт, закріпити плагін у своєму lock-файлі й записати всі три компоненти як упроваджені цим плагіном.release.yamlз підкинутим рядком має зупинитися з відмовою, наведеною вище.
Він виводить по одному рядку на збірку, потім файли, відрендерені двома прив’язками, і завершується з кодом 1, якщо будь-який результат відрізняється, виводячи вивід цієї збірки:
POLICY RELEASE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------none release-by-hand.yaml 0 reference OK: the six attachments' filesnone release.yaml 1 halt OK: E0162 for api and workerrego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedcel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedstring release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml: shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.Кожна збірка виконується у власній копії цього робочого простору, створеній у тимчасовій теці, причому шлях до каталогу в її .aggrega-config.yaml зроблено абсолютним, щоб він і далі розв’язувався звідти. У цю теку нічого не записується. Використовується бінарний файл, який знаходить допоміжний скрипт build-release, тож його вибирає AGGREGA_BIN, а аргументи після -- передаються кожній збірці. Його код завершення — це весь вердикт.
Де компілятор не інтерпретує
Компілятор передає політиці компоненти й прив’язані ключі. Він додає анотації, які вирішує політика, і розгортає їх через прив’язки сутності Manifest так само, як розгортає будь-яку анотацію. Він не знає, що сервіс слід моніторити, що таке інтервал збирання метрик або під якою роллю IAM має працювати компонент: ці значення належать політиці й сутності Manifest. Про ролі, корисні навантаження й ключі рішень див. сокет керування. Про розгортання анотацій без політики див. annotation-driven-monitoring.
Файли
aggregate.yaml— три сервіси, без анотацій.manifest.yaml— прив’язує тип компонента й дві сутності Features до їхніх Helm Recipes, а два ключі анотацій — до двох Features.release.yaml— сутність Release, яку анотує політика; анотацію записує лишеgateway.release-by-hand.yaml— контрольний варіант: кожну анотацію написано вручну..aggrega-config.yaml— типовий реєстр; без під’єднання керування.governance-rego.yaml,governance-cel.yaml— політика, під’єднана наannotation-transformчерез кожен із рушіїв, кожен файл вказується через--config.governance-monitoring-as-string.yaml— підкинута помилка, вказується через--config.policies/platform-defaults.rego,policies/platform-defaults.cel— політика, по одній на рушій.policies/monitoring-as-string.rego— підкинута помилка.build-release.sh— збирає одну сутність Release і виводить еквівалентну командуaggrega build.check.sh— виконує п’ять збірок і перевіряє кожен результат.