Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Политики, формирующие метки: уровень поддержки для каждого окружения и вердикт, который его читает

Плагины управления помечают каждый компонент, который развёртывает это рабочее пространство, его владельцем, уровнем поддержки, положенным его окружению, расписанием резервного копирования и коротким тегом, чтобы ни одному разработчику не приходилось вводить их вручную. Метки выводятся во время сборки четырьмя подключениями управления:

  • три на роли label-transform, которые формируют метки на узлах сборки: политика Rego, читающая окружение сущности Release, и два плагина тегирования, скомпилированные в CLI, — label-injector и selector-tagger;
  • одно на роли ir-verdict — политика Rego над графом сборки, которая останавливает production-сборку, в которой какой-либо узел остался без уровня поддержки.

Две сущности Releases одной сущности Aggregate различаются окружением, staging и production, и их узлы в итоге получают разные метки. Третья сборка, которую check.sh выполняет из копии этого рабочего пространства, где политика охватывает на одну категорию меньше, останавливается и называет пропущенный узел.

Что собирается

экземплярсущность Component из каталогачем он является здесь
dbcore/datastore/mariadbбаза данных магазина
cachecore/datastore/redisего кэш сессий
webcore/devtool/adminerинтерфейс администрирования базы данных, подключённый к db

Все три компилируются в Docker Compose, в dist/compose/docker-compose.yaml. Ни сущность Aggregate, ни обе сущности Releases не задают собственных меток: каждую метку ниже записывает подключение.

Четыре подключения

Они подключены в .aggrega-config.yaml этого рабочего пространства, в разделе plugins.governance, поэтому их применяет каждая сборка, запущенная здесь:

плагинрольчто он записывает
1governance/rego:0.9.0 с policies/support-tier.regolabel-transformops.example.com/environment на каждом узле; ops.example.com/support-tier на каждом узле, категория которого указана в его настройках
2governance/label-injector:0.9.0label-transformops.example.com/owner на каждом узле; backup.example.com/schedule на каждом узле категории datastore
3governance/selector-tagger:0.9.0label-transformtag из отображения в policies/tags.yaml
4governance/rego:0.9.0 с policies/production-support.regoir-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-файл, а затем:

Terminal window
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: orders
core/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

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

Terminal window
aggrega scaffold --example policy-label-transform

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd policy-label-transform

Сборка

Terminal window
aggrega build --release release-staging.yaml --auto-pull
aggrega 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, этого скрипта не содержит.

Terminal window
./check.sh

check.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 OK
release-staging.yaml as attached 0 pass OK: the expected labels
release-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with none
release-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 — выполняет четыре сборки и проверяет результат каждой.