Политики, формирующие метки: уровень поддержки для каждого окружения и вердикт, который его читает
Плагины управления помечают каждый компонент, который развёртывает это рабочее пространство, его владельцем, уровнем поддержки, положенным его окружению, расписанием резервного копирования и коротким тегом, чтобы ни одному разработчику не приходилось вводить их вручную. Метки выводятся во время сборки четырьмя подключениями управления:
- три на роли
label-transform, которые формируют метки на узлах сборки: политика Rego, читающая окружение сущности Release, и два плагина тегирования, скомпилированные в CLI, —label-injectorиselector-tagger; - одно на роли
ir-verdict— политика Rego над графом сборки, которая останавливает production-сборку, в которой какой-либо узел остался без уровня поддержки.
Две сущности Releases одной сущности Aggregate различаются окружением, staging и production, и их узлы в итоге получают разные метки. Третья сборка, которую check.sh выполняет из копии этого рабочего пространства, где политика охватывает на одну категорию меньше, останавливается и называет пропущенный узел.
Что собирается
| экземпляр | сущность Component из каталога | чем он является здесь |
|---|---|---|
db | core/datastore/mariadb | база данных магазина |
cache | core/datastore/redis | его кэш сессий |
web | core/devtool/adminer | интерфейс администрирования базы данных, подключённый к db |
Все три компилируются в Docker Compose, в dist/compose/docker-compose.yaml. Ни сущность Aggregate, ни обе сущности Releases не задают собственных меток: каждую метку ниже записывает подключение.
Четыре подключения
Они подключены в .aggrega-config.yaml этого рабочего пространства, в разделе plugins.governance, поэтому их применяет каждая сборка, запущенная здесь:
| плагин | роль | что он записывает | |
|---|---|---|---|
| 1 | governance/rego:0.9.0 с policies/support-tier.rego | label-transform | ops.example.com/environment на каждом узле; ops.example.com/support-tier на каждом узле, категория которого указана в его настройках |
| 2 | governance/label-injector:0.9.0 | label-transform | ops.example.com/owner на каждом узле; backup.example.com/schedule на каждом узле категории datastore |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag из отображения в policies/tags.yaml |
| 4 | governance/rego:0.9.0 с policies/production-support.rego | ir-verdict | ничего: останавливает сборку или позволяет ей завершиться |
0.9.0 — версия трёх сущностей Plugin в каталоге стандартной библиотеки; сами плагины скомпилированы в CLI, и сборка берёт их оттуда. aggrega build --release release-production.yaml --auto-pull --detail показывает и то и другое для каждого из трёх:
[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry] in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0 in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/rego ← governance/rego:0.9.0 in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0 in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]Подключения на одной роли выполняются в порядке перечисления, и каждое читает метки, записанные предыдущими: инжектор меток получает две метки, записанные политикой Rego, а тегировщик по селектору получает их и метки инжектора. Вердикт выполняется после всех трёх, над графом, который они оставляют.
Что читает политика label-transform
Политика на label-transform читает узлы в input.graph.nodes, с ключом по id узла, у каждого из которых есть:
component— сущность Component, экземпляр которой создаёт узел, напримерcore/datastore/mariadb;resolved_version— версия, к которой разрешилась эта сущность Component;labels— метки, которые несёт узел при запуске политики: собственные метки сущности Component и записанные любым предыдущим преобразованием;values— значения, которые экземпляр узла объявляет в сущности Aggregate; отсутствует, если он их не объявляет. Здесь значение объявляет толькоdb:database: appdb.
Сущность Release она читает в input.compilation_context: release_name и environment. Именно это позволяет одной политике принимать разные решения для разных окружений.
Политика на ir-verdict, напротив, читает весь граф сборки, и его узлы лежат на уровень глубже, в input.graph.spec.nodes. Правило, перенесённое с одной роли на другую, нужно редактировать, а не копировать: с неверным путём оно ничего не читает и никогда не срабатывает. Полезная нагрузка ir-verdict не содержит compilation_context, поэтому вердикт не может прочитать окружение из Release. Вот почему первая политика здесь также записывает ops.example.com/environment на каждом узле: вердикт читает окружение из этой метки.
Чтобы увидеть полезные нагрузки, а не читать о них, выполните сборку один раз, чтобы появился lock-файл, а затем:
aggrega build --release release-production.yaml --dry-run --policy-input payloadsзаписывает полезную нагрузку, которую получает каждое подключение, в payloads/ — по одному файлу на подключение там, где несколько подключений на одной роли получают разные полезные нагрузки (label-transform.1.rego.json, label-transform.2.label-injector.json, label-transform.3.selector-tagger.json), плюс по одному файлу на каждую другую роль — и больше ничего не записывает.
Политика Rego
policies/support-tier.rego собирает свои решения в labels, по одному на метку, называя узел, ключ метки и значение:
env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if { some id, _ in input.graph.nodes}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] in data.supported_categories}Её настройки — это документ data политики, и они содержат словарь организации:
settings: # The categories whose components get a support tier. supported_categories: [datastore, devtool] # The tier each environment gives them. support_tiers: production: on-call staging: office-hoursЧто записывает каждый встроенный плагин
label-injector применяет список правил. Узел, метки которого включают каждую пару из match правила, получает каждую пару из его set — добавленной или заменяющей значение метки, которая у узла уже есть. match без пар соответствует любому узлу. Правила он читает из своей настройки rules, как здесь, или, если в настройках их нет, из первого файла в sources, где они есть. Его два правила здесь дают каждому узлу ops.example.com/owner: shop-team, а db и cache, двум узлам категории datastore, — backup.example.com/schedule: nightly. web относится к категории devtool и расписания резервного копирования не получает.
selector-tagger записывает одну метку, всегда под ключом tag. Её значение берётся из отображения имён сущностей Component в теги, прочитанного из файлов в sources. Узел, сущности Component которого нет в отображении, получает настройку default, а без default остаётся без tag. policies/tags.yaml отображает базу данных и кэш:
core/datastore/mariadb: orderscore/datastore/redis: sessionsа default подключения — untagged, поэтому web получает тег untagged.
Оба принимают решение только по меткам узла и его сущности Component. Ни один не читает окружение, поэтому они записывают одинаковые метки в обеих сущностях Releases.
Оба обслуживают только label-transform. Подключённый на ir-verdict, любой из них отклоняется до запуска; selector-tagger, подключённый там, останавливает сборку с сообщением:
[E0085] ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandboxСоздание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example policy-label-transformЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd policy-label-transformСборка
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pullКаталог стандартной библиотеки предоставляет каждую сущность Component, Recipe и Feature здесь и три сущности Plugin. Они разрешаются из hub.aggrega.ai — реестра по умолчанию, который указывает .aggrega-config.yaml. Если рабочая копия каталога (где её взять) указана через --catalog, ничего не загружается из реестра, поэтому сборки работают офлайн. --auto-pull заполняет lock-файл каждой сущности Release во время сборки; lock-файлы и отрисованный вывод генерируются, а не поставляются.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке Workspace ещё нет папки `policy-label-transform`, вызовите один раз инструмент `scaffold`, задав для `example` значение `policy-label-transform` и не задавая `dir`: он запишет пример в новую папку `policy-label-transform`. Затем вызовите инструмент `build` по одному разу для каждой сущности Release в таком порядке — `release-staging.yaml` и `release-production.yaml` — каждый раз задавая для `workspace_root` значение `policy-label-transform`, для `release` — этот файл, для `auto_pull` — true и для `write` — true. Сообщите мне, какие файлы записала каждая сборка; они находятся в `policy-label-transform/dist/`.Метки, с которыми остаётся каждый узел
--ir-graph выводит граф сборки в стандартный вывод перед сводкой сборки, и граф содержит метки каждого узла в том виде, в каком их оставили преобразования. После aggrega build --release release-production.yaml --auto-pull --ir-graph узел web выглядит так:
"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "ops.example.com/environment": "production", "ops.example.com/support-tier": "on-call", "ops.example.com/owner": "shop-team", "tag": "untagged" }, [… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]}Первые три метки — собственные метки сущности Component; последние четыре записаны тремя преобразованиями. check.sh читает граф каждой сборки и перечисляет метки, записанные подключениями:
labels the attachments wrote, release-staging.yaml: db ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team tag: untagged
labels the attachments wrote, release-production.yaml: db ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team tag: untaggedМежду сущностями Releases меняются только две метки политики Rego.
Как только сборка заполнила lock-файл, aggrega inspect release-production.yaml --ir-graph выводит тот же граф без сборки, перед своим удобочитаемым представлением сущности Release, поскольку преобразования читают свои файлы из lock-файла. Без lock-файла выводимый граф не содержит ни одной из меток, которые определяют эти файлы: нет ни ops.example.com/environment, ни ops.example.com/support-tier, а на каждом узле — tag: untagged.
Преобразование меняет метки и ничего больше
Решение на label-transform называет один узел, один ключ метки и его значение или просит удалить одну метку. Нет решения, которое добавляет узел, меняет сущность Component или версию узла или затрагивает его значения, поэтому преобразование не может выразить ничего из этого. Решение, называющее узел, которого нет в сборке, не игнорируется: сборка останавливается с E0069 и называет узел и метку, которую не удалось установить.
Это показывают две сборки release-production.yaml — с этими подключениями и без них. Их графы сборки различаются метками, перечисленными выше, и ничем больше. Их отрисованный вывод не различается вовсе: здешние Recipes для Compose не отрисовывают ни одной из этих меток, поэтому dist/compose/docker-compose.yaml — один и тот же файл, байт в байт, с подключениями и без них, и check.sh сравнивает два дерева при каждом запуске. Метки живут в графе сборки, где их читает вердикт.
Вердикт и сборка, которую он останавливает
policies/production-support.rego подключена на ir-verdict, после преобразований, и читает записанные ими метки:
deny contains msg if { some id, node in input.graph.spec.nodes node.labels["ops.example.com/environment"] == "production" not node.labels["ops.example.com/support-tier"] msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])}Обе сущности Releases собираются: в staging вердикт ничего не требует, а в production каждый узел несёт уровень. Сузьте охват политики, и вердикт поймает узел, который она пропускает. Если записать supported_categories как [datastore] в .aggrega-config.yaml, web не получит уровня поддержки, и aggrega build --release release-production.yaml --auto-pull остановится:
[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label caused by: policy violationСборка завершается с кодом 1 и не записывает dist/. release-staging.yaml по-прежнему собирается с суженной политикой: его узлы помечены staging, и вердикт ничего от них не требует. check.sh выполняет эту сборку в копии рабочего пространства, поэтому, чтобы её увидеть, здесь ничего не нужно редактировать.
Вердикт принимает или отклоняет и ничего больше не делает: он не может добавить недостающую метку, чтобы сборка прошла. Какую метку должен нести production-узел — правило организации, записанное в её политике; компилятор переносит метки в граф как строки и не вкладывает в них никакого смысла.
Что записывает lock-файл
Lock-файл записывает два вида подключений по-разному. После production-сборки release-production.lock содержит каждое подключение-преобразование в mutators: — его плагин, роль, настройки, а также содержимое и дайджест каждого его файла — и закрепляет каждый плагин преобразования в plugins::
plugins: - uri: governance/label-injector [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/label-injector:0.9.0 - uri: governance/rego [… omitted: the artifact digest, recorded twice] referenced_from: - governance/rego:0.9.0 - uri: governance/selector-tagger [… omitted: the artifact digest, recorded twice] referenced_from: - governance/selector-tagger:0.9.0Подключение вердикта появляется только в verdict_inputs:, по sha256 его файла:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.regoПодключение вердикта не закрепляется. Если подключить только вердикт — убрав три преобразования из .aggrega-config.yaml, — lock-файл содержит mutators: [] и plugins: [], а файл вердикта — в verdict_inputs:. Преобразование меняет сборку, с которой работает остальная часть конвейера, поэтому lock-файл хранит плагин, внёсший изменение; вердикт лишь решает, завершится ли сборка.
Проверка каждой сборки
Эта самопроверка выполняется в рабочей копии репозитория документации, которая содержит используемый ею общий вспомогательный скрипт сборки; копия, записанная aggrega scaffold --example, этого скрипта не содержит.
./check.shcheck.sh выполняет четыре сборки через вспомогательный скрипт build-release и сверяет каждый результат с тем, который описывает эта страница:
release-production.yamlв копии этого рабочего пространства без подключения управления — в качестве эталона;release-staging.yamlиrelease-production.yamlздесь, каждая из которых должна завершиться с перечисленными выше метками на каждом узле, причём production-дерево должно байт в байт совпадать с эталоном;release-production.yamlв копии, политика которой охватывает только категориюdatastore; она должна остановиться сE0005и предложением выше, без какого-либо другого отказа рядом.
Он выводит по одной строке на сборку, затем метки, и завершается с кодом 1, если какой-либо результат отличается, выводя вывод этой сборки:
RELEASE GOVERNANCE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-production.yaml none 0 reference OKrelease-staging.yaml as attached 0 pass OK: the expected labelsrelease-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with nonerelease-production.yaml narrowed 1 halt OK: E0005, the expected sentence[… omitted: the two label listings shown above]check: every build ended as expected.Две копии создаются во временном каталоге, причём путь к каталогу сущностей в их .aggrega-config.yaml сделан абсолютным, чтобы он по-прежнему разрешался оттуда. Ни один файл в этом каталоге не редактируется; две сборки, выполняемые здесь, заполняют его lock-файлы, как это делает любая сборка. Используется бинарный файл, который находит ./build-release.sh, поэтому его выбирает AGGREGA_BIN, а аргументы после -- передаются каждой сборке. Он отказывается запускаться, пока в этом каталоге находится dist/, потому что сравнивает деревья, которые записывают сборки, и не оставляет ни одного после себя. Его код завершения — это весь вердикт.
Где компилятор не интерпретирует
Компилятор передаёт каждому преобразованию узлы и окружение сущности Release, применяет решённые им метки и передаёт результат вердикту. Он не знает, что такое уровень поддержки, что on-call выше office-hours или что devtool нуждается в уровне: эти смыслы — настройки и правила политик. О ролях, полезных нагрузках и о том, как политика называет метку, см. сокет управления, а о месте политики в продукте — Управление и соответствие требованиям.
Файлы
aggregate.yaml— база данных, кэш и интерфейс администрирования, подключённый к базе данных; меток нет.manifest.yaml— привязывает каждый тип компонента и секретную сущность Feature к соответствующему Docker Compose Recipe. Общий для обеих сущностей Releases.release-staging.yaml,release-production.yaml— два окружения..aggrega-config.yaml— реестр по умолчанию и четыре подключения управления.policies/support-tier.rego— политика преобразования меток.policies/production-support.rego— вердикт.policies/tags.yaml— сопоставление компонентов с тегами для тегировщика селекторов.build-release.sh— собирает одну сущность Release и выводит эквивалентную командуaggrega build.check.sh— выполняет четыре сборки и проверяет результат каждой.