Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Політика над відрендереним результатом: одне внутрішнє правило, чотири цілі, два рушії

Одне внутрішнє правило, прикріплене в ролі 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

ваша політика

підключена до компілятора

пройдено

файли записано

готові до перегляду й розгортання

не пройдено

збірку зупинено

policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted

Політика може зупинити збірку й сказати, що виправити. Вона ніколи не змінює ваші файли, щоб вони пройшли перевірку.

Що він збирає

екземплярComponent із каталогущо це тут
dbcore/datastore/postgresбаза даних замовлень
reportcore/compute/taskзавдання звітів, що читає db і запускається вручну: воно містить core/manual-trigger, тож під час розгортання сутності Release жоден запуск не починається

report читає адресу, порт та ім’я бази даних через своє з’єднання database як DB_HOST, DB_PORT і DB_NAME. Aggregate — той самий файл для кожного збирання; кожна сутність Release називає Manifest, який вибирає ціль:

Manifestdbreport
manifest-helm.yamlhelm/postgres, StatefulSethelm/task, CronJob, що утримується призупиненим
manifest-compose.yamlcompose/postgres, сервісcompose/task, сервіс за профілем
manifest-terraform.yamlterraform/postgres-rds, екземпляр RDSterraform/task-ecs, визначення завдання Amazon ECS
manifest-cloudformation.yamlcloudformation/postgres-rds, екземпляр RDScloudformation/task-ecs, визначення завдання Amazon ECS

Кожен Recipe тут рендерить лише з каталогу: базу даних Kubernetes синтезовано, а не завантажено як чарт, тіло бази даних Terraform пише її Recipe, а модуль завдання Terraform зберігається поруч із його Recipe. Тож кожне збирання виконується офлайн.

Вісім сутностей Releases

Releaseцільщо знаходить правилозбирання
release-helm.yamlKubernetesreport запускає registry.example.com/orders-report:1.4.2завершується
release-helm-unpinned.yamlKubernetesreport запускає той самий образ із тегом latestзупиняється
release-compose.yamlDocker Composereport запускає registry.example.com/orders-report:1.4.2завершується
release-compose-unpinned.yamlDocker Composereport запускає образ без тегузупиняється
release-terraform.yamlTerraformекземпляр зашифровано ключем, який називає сутність Releaseзавершується
release-terraform-unencrypted.yamlTerraformсутність Release не називає ключа, тож екземпляр не зашифрованозупиняється
release-cloudformation.yamlCloudFormationсутність Release вмикає StorageEncryptedзавершується
release-cloudformation-unencrypted.yamlCloudFormationсутність 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 заповнило свій файл блокування:

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -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 — закріплений тег, ключ шифрування, — і наступне збирання оцінюється знову.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

Terminal window
aggrega scaffold --example policy-render-verdict

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd policy-render-verdict

Збирання

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pull
aggrega 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 latest
policy 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 latest
policy 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, цього скрипту не містить.

Terminal window
./check.sh

check.sh через допоміжний скрипт build-release спершу збирає кожне контрольне збирання один раз без прикріпленої політики як еталон, а потім усі вісім сутностей Releases на кожному рушії. Контрольне збирання має завершитися й записати ті самі файли, байт у байт, що і його еталон; сутність Release із закладеним порушенням має зупинитися з E0005 та очікуваним для неї повідомленням, без жодного іншого відхилення поруч, і не записати dist/. Від обох рушіїв вимагається те саме повідомлення. Він виводить по одному рядку на збирання і завершується з кодом 1, якщо будь-який результат відрізняється, виводячи вивід цього збирання:

ENGINE RELEASE EXIT EXPECTED VERDICT
--------------------------------------------------------------------------------------------------------------
none release-helm.yaml 0 reference OK
none release-compose.yaml 0 reference OK
none release-terraform.yaml 0 reference OK
none release-cloudformation.yaml 0 reference OK
rego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
rego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel 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 — виконує двадцять збирань і перевіряє результат кожного.