Политика, подключающая сущности 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— выполняет пять сборок и проверяет каждый результат.