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