Політика над відрендереним результатом: одне внутрішнє правило, чотири цілі, два рушії
Одне внутрішнє правило, прикріплене в ролі render-verdict, оцінює файли, які збирання записує для чотирьох цілей, і відхиляє порушення, закладене в кожній із них. Правило має дві умови:
Кожен образ контейнера називає фіксовану версію — тег, відмінний від
latest, або дайджест. Кожен екземпляр бази даних зберігає свої дані в зашифрованому вигляді.
Цей робочий простір збирає один Aggregate для чотирьох цілей — Kubernetes через Helm, Docker Compose, Terraform і CloudFormation. Роль render-verdict оцінює файли, які записує збирання, після того як їх відрендерили всі цілі, а правило читає власну форму результату кожної цілі: образи в об’єктах Kubernetes і у файлі Compose, екземпляр RDS у файлі Terraform і в шаблоні CloudFormation. Кожна ціль має сутність Release, яка проходить перевірку, і сутність Release із закладеним порушенням, яку правило відхиляє.
Правило написано двічі, по одному разу для кожного рушія політик, вкомпільованого в CLI, — Rego і CEL, — і обидві копії погоджуються в кожному збиранні тут. Скрипт поруч із сутностями Releases збирає всі шістнадцять комбінацій і перевіряє кожен результат.
aggrega buildваша політика
підключена до компілятора
пройдено
файли записано
готові до перегляду й розгортання
не пройдено
збірку зупинено
Політика може зупинити збірку й сказати, що виправити. Вона ніколи не змінює ваші файли, щоб вони пройшли перевірку.
Що він збирає
| екземпляр | Component із каталогу | що це тут |
|---|---|---|
db | core/datastore/postgres | база даних замовлень |
report | core/compute/task | завдання звітів, що читає db і запускається вручну: воно містить core/manual-trigger, тож під час розгортання сутності Release жоден запуск не починається |
report читає адресу, порт та ім’я бази даних через своє з’єднання database як DB_HOST, DB_PORT і DB_NAME. Aggregate — той самий файл для кожного збирання; кожна сутність Release називає Manifest, який вибирає ціль:
| Manifest | db | report |
|---|---|---|
manifest-helm.yaml | helm/postgres, StatefulSet | helm/task, CronJob, що утримується призупиненим |
manifest-compose.yaml | compose/postgres, сервіс | compose/task, сервіс за профілем |
manifest-terraform.yaml | terraform/postgres-rds, екземпляр RDS | terraform/task-ecs, визначення завдання Amazon ECS |
manifest-cloudformation.yaml | cloudformation/postgres-rds, екземпляр RDS | cloudformation/task-ecs, визначення завдання Amazon ECS |
Кожен Recipe тут рендерить лише з каталогу: базу даних Kubernetes синтезовано, а не завантажено як чарт, тіло бази даних Terraform пише її Recipe, а модуль завдання Terraform зберігається поруч із його Recipe. Тож кожне збирання виконується офлайн.
Вісім сутностей Releases
| Release | ціль | що знаходить правило | збирання |
|---|---|---|---|
release-helm.yaml | Kubernetes | report запускає registry.example.com/orders-report:1.4.2 | завершується |
release-helm-unpinned.yaml | Kubernetes | report запускає той самий образ із тегом latest | зупиняється |
release-compose.yaml | Docker Compose | report запускає registry.example.com/orders-report:1.4.2 | завершується |
release-compose-unpinned.yaml | Docker Compose | report запускає образ без тегу | зупиняється |
release-terraform.yaml | Terraform | екземпляр зашифровано ключем, який називає сутність Release | завершується |
release-terraform-unencrypted.yaml | Terraform | сутність Release не називає ключа, тож екземпляр не зашифровано | зупиняється |
release-cloudformation.yaml | CloudFormation | сутність Release вмикає StorageEncrypted | завершується |
release-cloudformation-unencrypted.yaml | CloudFormation | сутність Release залишає його вимкненим | зупиняється |
Образ визначає сутність Release: core/compute/task не пакує жодного програмного забезпечення, тож Release називає образ, який виконує запуск, у infra.image, разом із тегом. На двох цілях AWS шифрування бази даних також визначає Release. Terraform Recipe читає infra.overrides.kms_key_id і, якщо його задано, рендерить storage_encrypted = true поруч із ключем; CloudFormation Recipe читає infra.overrides.StorageEncrypted і KmsKeyId під власними назвами властивостей ресурсу. Сутність Release, яка не задає жодного з них, рендерить екземпляр зовсім без атрибута шифрування — саме так роблять сутності Releases із закладеними порушеннями.
Бази даних Kubernetes і Compose запускають образ postgres:16 із фіксованим тегом, тож правило оцінює їх і пропускає в кожній сутності Release.
Прикріплення правила
.aggrega-config.yaml вказує хаб як свій реєстр і не оголошує жодної теки каталогу, ані жодного прикріплення врядування. Правило прикріплює файл, який збирання називає через --config: governance-rego.yaml для рушія Rego, governance-cel.yaml для рушія CEL. Файл для Rego виглядає так:
plugins: governance: - uri: governance/rego:0.9.0 role: render-verdict with: sources: - policies/house-rule.rego--config називає глобальний файл конфігурації для цього запуску замість того, який інакше прочитала б машина, а .aggrega-config.yaml цього робочого простору й надалі накладається поверх нього. Список plugins.governance у файлі робочого простору замінив би список із названого файлу, тому файл робочого простору його не оголошує. 0.9.0 — версія сутності Plugin кожного рушія в каталозі стандартної бібліотеки. Обидва рушії вкомпільовано в CLI — aggrega plugin list перелічує governance/rego і governance/cel серед вбудованих модулів, — тож жодне збирання тут не завантажує плагін.
Що читає політика render-verdict
Політика в ролі render-verdict читає файли, які записує збирання, у input.artifacts, по одному запису на файл, відсортовані за шляхом. Кожен запис містить:
path— шлях файлу вdist/, наприкладterraform/modules/db/main.tf;content— текст файлу в записаному вигляді;format— формат, який провайдер цілі оголосив для файлу:yamlдля файлу Compose,jsonдля шаблону CloudFormation,hclдля кожного файлу Terraform, включно з тілом бази даних, яке пише її Recipe. Там, де нічого не оголошено, це порожній рядок, як для файлів Kubernetes тут;documents— вміст файлу, розібраний у структуру, як список документів: тут по одному на кожен файл;parse_error— присутній лише у файлі, який не вдалося розібрати, замістьdocuments.
Окрім файлів, input.sources містить власний файл політики прикріплення, а input.settings — його налаштування: тут це порожній об’єкт, оскільки це прикріплення їх не оголошує.
aggrega build --release <release> --dry-run --policy-input <dir> записує корисне навантаження, яке отримує кожна роль, у <dir> і більше нічого не записує. У ролі render-verdict цей файл — те, що отримує рушій, а не те, що читає політика: кожен файл у ньому містить свої path і content та format, оголошений його провайдером, а рушій розбирає documents із вмісту, щойно отримає корисне навантаження. Тож файл перелічує файли, які буде показано правилу, але не їхні документи. Після того як збирання release-terraform.yaml заповнило свій файл блокування:
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '[.artifacts[].path]' payloads/render-verdict.json# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]Шлях, який правило читає всередині documents, перевіряється у збиранні, де рушій їх розібрав. Жоден файл, який пишуть ці сутності Recipes, не провалює розбір, тож жоден файл тут не містить parse_error. Кожна умова цього правила читає documents, тож файл, який не вдалося розібрати, пройшов би її неперевіреним; правило, яке не має цього допускати, додає умову, що відхиляє файл із parse_error.
Як кожна умова читає форму своєї цілі
Кожна умова називає форму, яку читає, а файл іншої форми не містить того, що називає умова: у Rego шлях не визначено, і умова не виконується. Тож одне правило працює над результатом кожної цілі, і кожна умова знаходить лише своє.
Compose записує один файл, документ якого задає кожен сервіс за іменем у services:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services unpinned(service.image) msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])}Об’єкти Kubernetes містять свої контейнери в шаблоні pod, який CronJob тримає на один рівень глибше, ніж інші робочі навантаження, у spec.jobTemplate.spec:
pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"Terraform у нативному HCL вкладає блок під його тип, а потім під кожну з його міток, і остання мітка містить список блоків, бо блоки зі спільними типом і мітками збираються в один список. Тож атрибути екземпляра розташовані на один індекс нижче за його ім’я, і умова обходить цей список:
deny contains msg if { some artifact in input.artifacts native_hcl(artifact) some doc in artifact.documents some name, blocks in doc.resource.aws_db_instance some block in blocks not block.storage_encrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])}Список тут важливіший, ніж для правила, що шукає значення, бо ця умова відхиляє через відсутність. Якщо написати її для одного блоку — some name, block in doc.resource.aws_db_instance, — то block буде списком, block.storage_encrypted на ньому не визначено, а not виконується для всього невизначеного: умова відхилить і release-terraform.yaml, екземпляр якого зашифровано, з тим самим повідомленням, що й сутність Release із закладеним порушенням.
Файл .tf.json читається так, як його записав Recipe, де ім’я містить сам блок, тож правило, написане для однієї форми, не читає іншу. Ось чому умова спершу читає format: native_hcl приймає файл із форматом hcl або з порожнім форматом та іменем, що закінчується на .tf, — файл, для якого жоден провайдер не оголосив формат, розбирається за іменем, тож і правило розпізнає його за іменем, а не пропускає. Кожен файл Terraform, зібраний тут, оголошено як hcl, тож жоден файл тут не розпізнається за іменем. Ці сутності Recipes не пишуть файлів .tf.json, тож правило не читає іншої форми. Що розкриває корисне навантаження кожної ролі описує обидві форми.
CloudFormation записує один шаблон, ресурси якого задано за логічним ID у Resources, кожен зі своїми Type і Properties:
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some id, resource in doc.Resources resource.Type == "AWS::RDS::DBInstance" not resource.Properties.StorageEncrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])}Екземпляр без властивості StorageEncrypted або з цією властивістю, що має будь-яке значення, крім true, відхиляється: not … == true виконується в обох випадках.
Чому правило CEL написано інакше
policies/house-rule.cel формулює ті самі дві умови й доходить того самого вердикту в кожному збиранні тут. Воно написане інакше у трьох місцях, кожне — з причини, пов’язаної з рушієм.
Воно перевіряє кожен ключ, перш ніж його читати. Читання ключа, якого немає у значенні, у CEL — це помилка обчислення, а не невизначений шлях, а помилка зупиняє збирання. У файлах кожної цілі немає ключів, які є в інших, — в об’єкта Kubernetes немає services, у файлу Compose немає kind, — тож кожна умова спершу перевіряє ключі, які читає, за допомогою has():
// Docker Compose: a service whose image names no fixed version.input.artifacts .filter(a, has(a.documents) && a.documents.exists(d, has(d.services) && d.services.exists(s, has(d.services[s].image) [… omitted: the image test, and the rest of the clause]Без перевірки has(d.services) команда aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull зупиняється, хоч би які образи запускали об’єкти Kubernetes, завершується з кодом 1 і не записує dist/, а рядок, що повідомляє про помилку, називає файл політики та ключ:
render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: servicesВоно повідомляє про одного порушника на файл. Ключ рішення збирає повідомлення, а вираз CEL не має способу об’єднати списки, які він будує для кожного файлу, в один список. Тож кожна умова CEL повідомляє про одного порушника в кожному файлі: перший контейнер шаблону pod або, серед сервісів, екземплярів і ресурсів, які файл задає за іменем, той, чиє ім’я йде першим під час сортування. Включення обходить відображення в довільному порядку, тож саме вибір за іменем зберігає повідомлення однаковим від збирання до збирання. Правило Rego повідомляє про кожного порушника. Якщо в одному файлі Compose є два незакріплені сервіси, рушій Rego зупиняється з двома повідомленнями, а рушій CEL — з одним, для сервісу, чиє ім’я йде першим під час сортування; якщо один, як у кожній сутності Release тут, обидва зупиняються з тим самим повідомленням.
Воно повторюється. CEL не дає змоги назвати підвираз, тож перевірку, використану двічі, написано двічі, а перевірку образу розписано в кожній умові, а не викликано, як unpinned у Rego.
Ці два файли — навмисний майже-дублікат: кожен написано самостійно за наведеним вище правилом, а не згенеровано один з одного, щоб збирання, у якому рушії розходяться, показало цю розбіжність.
Вердикт ніколи не змінює результат
Політика в ролі render-verdict приймає збирання або відхиляє його. Їй передають файли, записані збиранням, і вона повертає вердикти; ніщо з того, що вона повертає, до них не застосовується. Тож контрольне збирання створює ті самі файли, байт у байт, із прикріпленим правилом і без нього, а check.sh порівнює два дерева під час кожного запуску. Відхилене збирання взагалі не записує dist/. Щоб усунути відхилення, змінюється сутність Release — закріплений тег, ключ шифрування, — і наступне збирання оцінюється знову.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example policy-render-verdictПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd policy-render-verdictЗбирання
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1Замініть governance-rego.yaml на governance-cel.yaml, щоб запустити те саме правило на рушії CEL, а terraform в імені файлу сутності Release — на helm, compose або cloudformation, з їхніми сутностями Releases із закладеними порушеннями release-helm-unpinned.yaml, release-compose-unpinned.yaml і release-cloudformation-unencrypted.yaml.
Каталог стандартної бібліотеки надає кожну сутність Component, Recipe, Feature і FeatureRecipe тут і містить сутності Plugin обох рушіїв. Вони розв’язуються з hub.aggrega.ai — типового реєстру, який називає .aggrega-config.yaml. Якщо локальну копію каталогу (де її отримати) вказано через --catalog, нічого не завантажується з реєстру, тож збирання виконуються офлайн. --auto-pull заповнює файл блокування кожної сутності Release під час збирання; файли блокування та відрендерений результат генеруються, а не постачаються.
Контрольне збирання Terraform завершується. Сутність Release із закладеним порушенням зупиняється:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish][POLICY_ERROR E0005] policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted caused by: policy violationКожне повідомлення називає файл, який оцінило правило, його шляхом у dist/, і порушника в ньому. Інші сутності Releases із закладеними порушеннями зупиняються так само:
policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencryptedКожен рядок — це рядок після [POLICY_ERROR E0005] у виводі його збирання, показаний від лівого краю. Перший походить від рушія Rego, а два інші — від рушія CEL, і кожен називає рушій, який про нього повідомив; інший рушій виводить те саме повідомлення під своїм іменем.
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека Workspace ще не містить теки `policy-render-verdict`, викличте один раз інструмент `scaffold`, задавши для `example` значення `policy-render-verdict` і не задаючи `dir`: він запише приклад у нову теку `policy-render-verdict`. Потім викличте інструмент `cli-build`, який запускає `aggrega build` і приймає його прапорець `--config`, один раз для кожної сутності Release у такому порядку — `release-terraform.yaml` і `release-terraform-unencrypted.yaml` — щоразу задаючи для `workspace_root` значення `policy-render-verdict`, для `release` — цей файл, для `auto_pull` — true і для `config` — `governance-rego.yaml`. Другу збірку має бути відхилено, тож прочитайте мені відмову. Скажіть мені, які файли записала перша збірка; вони розташовані в `policy-render-verdict/dist/`.Перевірка кожної збірки
Ця самоперевірка виконується в робочій копії репозиторію документації, яка містить потрібний їй спільний допоміжний скрипт збирання; копія, записана aggrega scaffold --example, цього скрипту не містить.
./check.shcheck.sh через допоміжний скрипт build-release спершу збирає кожне контрольне збирання один раз без прикріпленої політики як еталон, а потім усі вісім сутностей Releases на кожному рушії. Контрольне збирання має завершитися й записати ті самі файли, байт у байт, що і його еталон; сутність Release із закладеним порушенням має зупинитися з E0005 та очікуваним для неї повідомленням, без жодного іншого відхилення поруч, і не записати dist/. Від обох рушіїв вимагається те саме повідомлення. Він виводить по одному рядку на збирання і завершується з кодом 1, якщо будь-який результат відрізняється, виводячи вивід цього збирання:
ENGINE RELEASE EXIT EXPECTED VERDICT--------------------------------------------------------------------------------------------------------------none release-helm.yaml 0 reference OKnone release-compose.yaml 0 reference OKnone release-terraform.yaml 0 reference OKnone release-cloudformation.yaml 0 reference OKrego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencerego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected.Він використовує бінарний файл, який знаходить ./build-release.sh, тож його вибирає AGGREGA_BIN, а аргументи після -- передаються кожному збиранню. Він відмовляється запускатися, поки в цьому каталозі є dist/, бо переміщує дерево кожного збирання, щоб порівняти його, і не залишає жодного після себе; збирання заповнюють файли блокування цього каталогу, як і будь-яке збирання. Його код завершення — це весь вердикт.
Де компілятор не інтерпретує
Компілятор рендерить файли кожної цілі, передає їх прикріпленому рушію як текст із форматом, оголошеним їхнім провайдером, і діє відповідно до рівня серйозності, який несе кожен вердикт. Він не знає, що таке тег образу, що latest змінюється або що екземпляр RDS має бути зашифровано: ці значення належать правилу. Про ролі, корисні навантаження та ключі рішень див. сокет врядування.
Файли
aggregate.yaml— база даних і підключене до неї завдання формування звітів.manifest-helm.yaml,manifest-compose.yaml,manifest-terraform.yaml,manifest-cloudformation.yaml— прив’язують кожен тип компонента та сутність Feature ручного запуску до їхніх Recipes на одній цілі.release-<target>.yaml,release-<target>-unpinned.yaml,release-<target>-unencrypted.yaml— контрольний варіант і навмисно закладене порушення для кожної цілі..aggrega-config.yaml— типовий реєстр; без під’єднання керування.governance-rego.yaml,governance-cel.yaml— правило, приєднане вrender-verdictчерез кожен рушій; кожен файл указується через--config.policies/house-rule.rego,policies/house-rule.cel— правило, по одному для кожного рушія.build-release.sh— збирає одну сутність Release і виводить еквівалентну командуaggrega build.check.sh— виконує двадцять збирань і перевіряє результат кожного.