Сокет керування
Увесь сокет, а не одна його роль: чотири ролі — дві, що оцінюють збірку, і дві, що її формують, — обидва рушії політик, що постачаються в складі компілятора, і те, як оператор підключає плагін.
Оператор підключає плагін керування Wasm, щоб перевірити збірку й діяти відповідно до знайденого. Хост компілятора залишається нейтральним щодо вмісту й без власної позиції: він передає корисне навантаження збірки гостю й діє відповідно до того, що повертає гість, і ніколи не інтерпретує саму політику. Уся предметна логіка політик — мова політик, її рушій і правила — міститься в гості.
Це той самий контракт чистоти ahead-of-time, за яким працює кожен сокет: гість обчислює передане йому корисне навантаження й повертає результат, який хост використовує дослівно (див. контракт пісочниці). Хост нічого не знає про мову політик, якою послуговується гість, і не містить власного коду рушія політик.
Плагін керування підключається рівно до однієї ролі, і саме роль — а не плагін — визначає і те, яке корисне навантаження надходить, і те, що підключення може з ним робити. Дві ролі є ролями вердикту: підключення оцінює збірку, а хост виконує рівно одну з трьох дій для кожного поверненого вердикту. Дві ролі є ролями трансформації: підключення повідомляє про зміну міток або анотацій збірки, а хост застосовує її. Плагін, що обслуговує кілька ролей, підключається один раз для кожної ролі, і він не оголошує власної ролі — її несе підключення.
Ця сторінка — вичерпний опис сокета керування: чотири ролі
й корисне навантаження кожної, рівні серйозності вердиктів, на які реагує хост,
незалежний від рушія вхідний канал, який надає оператор, як написати політику для будь-якого
з двох рушіїв політик, що постачаються в складі компілятора, — одного, що обчислює Rego, і другого,
що обчислює CEL, — як гість обгортає сторонній рушій політик, еталонні гості, що
постачаються, і як оператор підключає плагін до робочого простору. Про місце сокета в конвеєрі та його типізовані формати передавання див.
plugin-contract.md; про створення й публікацію
плагіна як сутності каталогу див.
посібник розробника плагінів Wasm.
Ментальна модель: хост маршрутизує, гість вирішує
Під час збирання хост формує корисне навантаження для ролі прикріплення, передає його через межу ABI і зчитує те, що повернув гість. У ролі вердикту це список вердиктів, кожен із яких містить рівень серйозності та зрозуміле людині повідомлення: хост зіставляє кожен рівень серйозності з дією збирання, не аналізує зміст повідомлення, не знає, що перевіряла політика, і не знає, який рушій ухвалив рішення. У ролі перетворення це зміна, яку слід внести, адресована міткам або анотаціям, якими керує ця роль, і нічому іншому.
Оскільки хост не інтерпретує вміст політики, уся поверхня політики належить гостю: якою мовою написано правила, який рушій їх обчислює і як спрацювання правила стає вердиктом або зміною. Контракт сокета навмисно вузький — роль, набір вхідних даних і результат, — щоб будь-яка технологія політик, яка компілюється у Wasm, могла його обслуговувати.
Роль вердикту приймає або відхиляє і нічого більше не робить: хост читає її вивід лише як рішення і ніколи не застосовує його як зміну, тож політика не може непомітно привести невідповідне збирання до відповідності. Роль перетворення — навмисний виняток, і робить її винятком те, що її прикріпив оператор: прикріплення плагіна для формування міток є заявою про те, що мітки слід формувати. Те, що таке прикріплення може змінювати, обмежено поверхнею його власної ролі, а на будь-що поза нею збирання гучно зупиняється.
Чотири ролі
Плагін приєднується рівно до однієї ролі, і роль визначає, у якому місці конвеєра хост його обчислює, яке корисне навантаження він отримує і що може повернути. Плагін, який має обслуговувати дві ролі, приєднується двічі — по одному разу для кожної ролі.
Ролі вердикту: ir-verdict і render-verdict
ir-verdict— гість аналізує граф проміжного представлення до рендерингу. Корисне навантаження містить повний граф IR, агностичний щодо можливостей (кожен вузол, ребро і приєднання, які має компілятор), а також шляхи маршрутизації, що їх перелічує аналізатор, тож політика може міркувати про топологію і досяжність, не обходячи граф повторно. Цей список шляхів обмежений для кожного початкового вузла — щільно зв’язана або циклічна топологія може містити більше різних маршрутів, ніж видає перелічення, і щойно межу досягнуто, решта маршрутів від цього початкового вузла не перелічується. Тож наявний шлях справжній, але відсутність шляху не доводить, що його немає: політика, вердикт якої залежить від того, що щось недосяжне, має встановлювати це за вузлами і ребрами, які корисне навантаження містить повністю, а не лише за списком шляхів. Одне в графі подано не так, як написано: кожне значення, яке автор оголосив чутливим, — уvaluesчиinfraприєднання, вinfraприєднання межі, у власнихvaluesчиinfraвузла або у власнихvaluesчиinfraз’єднання — надходить як маркер приховування{"aggrega_withheld": "declared"}, тоді як його ключ, позначка чутливості і кожне неоголошене значення поруч надходять як написано. Політика оцінює, куди переміщуються оголошено чутливі дані, і ніколи не отримує самих даних; див. факти приєднання, які читає політика управління. Політикаir-verdictвиконується на етапі статичного аналізу, до створення будь-яких артефактів. Використовуйте її для політик щодо архітектури і зв’язків — інваріантів топології, автентифікації через межі, форми потоків облікових даних, — які мають зупинити збірку, перш ніж вона щось відрендерить.render-verdict— гість аналізує відрендерений вивід після рендерингу. Корисне навантаження містить створені артефакти, відсортовані за шляхом, тож дані, що передаються, побайтово ідентичні між запусками з ідентичним входом. Кожен артефакт містить свій вихідний шлях і відрендерений текст; додатково він містить формат, у якому його відрендерено, якщо постачальник, що його створив, цей формат оголосив, і розібране структуроване подання його вмісту, якщо вміст має формат, який розібрано до запуску політики. Політикаrender-verdictбачить саме те, що створила збірка, і нічого в ньому не приховано: значення, яке Recipe відрендерив в артефакт, надходить у відрендереному вигляді, бо саме артефакт оцінює політика. Використовуйте її для політик щодо конкретного виводу — наприклад, правила, яке перевіряє відрендерені сервіси Docker Compose або об’єкти Kubernetes.
Ролі перетворення: annotation-transform і label-transform
-
annotation-transform— гість повідомляє, які анотації додати, під час розв’язання і до розгортання анотацій. Корисне навантаження містить кожен компонент, який приєднання може анотувати, разом з уже наявними в нього анотаціями, а також ключі анотацій, для яких Manifest реєструє прив’язку. Додана анотація з зареєстрованим ключем далі розгортається в приєднання Feature — так ця роль додає до збірки можливість, яку розробник не вписав.Компоненти, які він може анотувати, — це кожен компонент, який межа називає в
components:, і кожен компонент, який маршрутизує всередину запис маршрутизаціїaggregates:межі. Запис маршрутизації розміщує кожен компонент свого модуля, включно з компонентами вкладених у нього модулів, незалежно від того, чи називає його власнеcomponents:усі з них, деякі чи жодного, якdocuments: {}не називає жодного; корисне навантаження містить кожен із них. До маршрутизованого компонента звертаються за ідентифікатором, який він має в графі збірки, — назва модуля, крапка й назва компонента всередині модуля, як уdocuments.backend, з ще однією назвою модуля й крапкою для кожного вкладеного модуля, — саме так його записують граф збірки та його діагностика, тож рішення називає його так само. Компонент, який запис маршрутизації розміщує, не називаючи його, не має в корисному навантаженні власних анотацій, а анотація, впроваджена в нього, застосовується як записана на ньому під записом маршрутизації. -
label-transform— гість повідомляє, які зміни міток застосувати, під час побудови топології: після побудови графа і до його оцінювання. Корисне навантаження містить проєкцію вузлів збірки — для кожного вузла сутність Component, екземпляр якої він створює, версію, розв’язану для нього, мітки, які він має зараз, і значення, які оголошує його екземпляр, лише для читання та з утриманням кожного значення, яке його Component оголошує чутливим, так само як його утримує вердикт графа, — а також ім’я та середовище сутності Release. Використовуйте її для похідних метаданих, які розробнику ніколи не слід вписувати вручну (сфери відповідності вимогам, належності, розподілу витрат), і для мітки можливості, яку заслуговує оголошена розробником конфігурація.
Ролі несуть різні корисні навантаження, бо діють у різні моменти й відповідають на різні запитання. Усі чотири несуть той самий наданий оператором канал вводу, описаний нижче. Щоб побачити корисне навантаження, а не читати про нього, aggrega build --release <release> --policy-input <dir> записує корисне навантаження, яке кожна роль передає приєднаному до неї плагіну, — включно з роллю, до якої нічого не приєднано, — як один JSON-файл на роль або на приєднання, коли приєднання ролі отримують різні корисні навантаження, а в поєднанні з --dry-run записує ці файли й нічого більше. На annotation-transform, label-transform і ir-verdict файл є документом input, який читає політика. На render-verdict рушій політик перебудовує корисне навантаження, перш ніж його прочитає політика, — documents кожного артефакту розбираються з нього, — тож політику render-verdict на рушії, вбудованому в компілятор, тестують у збірці, приєднавши з warn або info, як показано в розділі Тестування політики до того, як вона контролюватиме збірку. Для плагіна, .wasm якого ви зібрали самі, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json запускає його на цьому файлі.
Вердикти та рівні серйозності
Наведені нижче рівні серйозності — це словник ролей вердиктів. Роль перетворення повідомляє про зміну, а не про вердикт, тому рівня серйозності не має.
Гість повертає список вердиктів. Кожен вердикт має рівень серйозності, який визначає дію збірки:
halt— зупиняє збірку; хост показує повідомлення вердикту як причину. Збірка не створює жодних артефактів.warn— позначає вердикт; збірка триває.info— записує вердикт; результат збірки не змінюється.
Ці три рівні становлять увесь набір, і це ті самі три рівні, які використовують діагностичні повідомлення всіх інших сокетів, тож рівень серйозності означає одне й те саме, де б ви його не зустріли.
Вердикт із будь-яким іншим значенням є порушенням контракту, а не четвертим шляхом. Збірка зупиняється, а повідомлення називає плагін, значення, яке мав вердикт, і три значення, які оголошує контракт, — тож рівень серйозності з помилкою в написанні повідомляється як помилка збірки, а не проходить як вердикт, на який ніщо не реагує. Гостя, який повідомляє одне з трьох значень, це не стосується.
Дозвільне обчислення нічого не повертає. Гість видає вердикт лише тоді, коли спрацьовує правило, тож порожній список вердиктів означає, що політика дозволила збірку. Вердикту «pass» для видачі не існує — мовчання і є дозволом.
Гість може повернути багато вердиктів за одне обчислення, змішуючи рівні серйозності. Хост
обробляє їх усі: будь-який halt зупиняє збірку (і показується кожне повідомлення
halt), тоді як вердикти warn та info повідомляються без блокування. Це
відображає поділ на зупинку й пораду, що відрізняє політику, яка зупиняє збірку, від
рекомендаційної перевірки лінтера.
Канал with: джерела та налаштування
Гість політики зазвичай є узагальненим щодо конкретних правил, які він застосовує, — рушій вбудовано в гостя, але правила надаються для кожного приєднання окремо. Канал
with передає ці вхідні дані для кожного приєднання. Він має два поля, незалежні від
рушія:
sources— файли визначень політики, які завантажує гість. Хост читає кожен названий файл під час збірки й передає його байти гостю непрозоро: він ніколи не розбирає джерело, а шлях, який він передає гостю, — це базова назва файлу, а не абсолютний шлях на хості. Що означають ці байти, повністю справа гостя: для одного гостя це файл.rego, для іншого — якийсь інший формат політики, а для гостя, який читає архів, — закодований у base64 архів цілого набору політик.settings— мапа конфігурації, яку гість відображає на свій рушій. Гість читає з цієї мапи свої параметри (верхню межу кількості реплік, обов’язковий ключ мітки). За замовчуванням хост передає її дослівно, нічого з нею не роблячи; гість може додатково оголосити для неї схему (див. нижче), і тоді хост перевіряє мапу за цією схемою перед запуском гостя.
Повністю готовий гість — той, чиї правила скомпільовано в нього, а не надано під час
приєднання, — зовсім не містить with. Канал необов’язковий для кожної ролі.
Типізовані налаштування
Гість може оголосити JSON Schema для очікуваних settings. Якщо він це робить,
хост перевіряє settings приєднання за цією схемою перед тим, як
запустити гостя. Налаштування, що не відповідають схемі, зупиняють збірку з повідомленням,
яке називає проблемний ключ і те, чого очікувала схема, — відсутній обов’язковий ключ,
значення неправильного типу, невідомий ключ або значення поза діапазоном виявляються
заздалегідь, а не проявляються як незрозуміла помилка гостя чи, що гірше,
неправильна, але успішна збірка.
Типізовані налаштування необов’язкові й оголошуються гостем, а не хостом. Гість, який
не оголошує схеми налаштувань, зберігає довільну поведінку: хост передає його
settings без перевірки. Хост виконує звичайну перевірку JSON Schema
за тією схемою, яку оголосив гість; він не тлумачить, що означають
налаштування. Так перевірка лишається нейтральною щодо рушія: кожен гість описує
форму налаштувань, які він читає, а хост забезпечує саме цю форму і
нічого більше.
Приєднання, яке не оголошує налаштувань, перевіряється як JSON null. Саме це дає змогу гостю зробити свої налаштування обов’язковими: схема, що допускає лише об’єкт, відхиляє приєднання, яке їх не надає, і збірка зупиняється. Цей наслідок діє й у зворотний бік, і саме його слід свідомо враховувати: гість, чиї налаштування справді необов’язкові, мусить оголосити схему, яка допускає null і об’єкт, інакше його взагалі неможливо приєднати без налаштувань. Два рушії політик, вбудовані в компілятор, оголошують "type": ["object", "null"] саме з цієї причини — приєднайте такий без блоку with:, і він працюватиме зі своїми значеннями за замовчуванням. Гість, який оголошує лише "type": "object", зробив свої налаштування обов’язковими, незалежно від того, чи це було задумано.
ABI належить самому Aggrega
Контракт сокета — це власний ABI Aggrega, а не ABI будь-якого рушія політик. Саме це дає змогу будь-якій технології політик, скомпільованій у Wasm, слугувати гостем, що підключається без змін: гість назовні використовує поверхню Aggrega — describe() плюс експорт, який викликає роль, що її він обслуговує, — а рушій, який він використовує, є деталлю реалізації за цією поверхнею.
Гість, що обгортає сторонній рушій політик, поглинає ABI цього рушія всередині себе. Якщо рушій має власний Wasm ABI, власні точки входу або власний протокол зворотних викликів хоста, гість-обгортка створює його екземпляр і керує ним усередині себе, а рішення рушія відображає назад у форму вердикту сокета. Хост компілятора бачить лише стандартну поверхню вердиктів керування; він ніколи не дізнається, який рушій задіяно, і не містить коду, специфічного для рушія. Перехід політики з одного рушія на інший — це зміна підключення, а не зміна хоста.
Два рушії політик постачаються всередині компілятора
Два рушії політик скомпільовано в бінарний файл CLI, і оператор підключає будь-який із них — або обидва — так само, як підключається будь-який плагін керування:
| Координата | Мова політик | Підключене джерело |
|---|---|---|
governance/rego | Rego | Файли .rego або закодований у base64 архів цілого набору політик |
governance/cel | Common Expression Language (CEL) | Файли виразів .cel або документи правил .yaml / .yml |
Усе довкола мови спільне. Обидва рушії обслуговують усі чотири ролі, обидва читають
однакове корисне навантаження для кожної ролі під тими самими назвами полів, обидва відображають свої рішення на
ті самі три рівні серйозності вердиктів через те саме налаштування translation, і обидва завершуються
помилкою явно, а не дозволяють збірку, яку не змогли оцінити. Кожен має версією
випуск компілятора, у якому він постачається, і жоден не потребує зовнішнього
інструментарію та нічого не завантажує під час збірки. Те, що кожна мова може виразити, не
є спільним: правило, яке в Rego складається з кількох допоміжних правил, у CEL може потребувати налаштувань і повторень
— див. Що може виразити вираз, перш ніж писати
правило, що обходить маршрут.
Відрізняється мова, якою написано правила, і саме на цьому повністю ґрунтується вибір. Середовище, що вже має корпус Rego — або команда, яка пише Rego для контролю допуску деінде, — підключає рушій Rego, і її політики працюють без змін. Команда, що виражає свої правила як окремі вирази над документом, як це робить політика validating admission у Kubernetes, підключає рушій CEL. Обидва підключаються для кожної ролі окремо, тож робочий простір може запускати Rego в одній ролі, а CEL в іншій, або обидва в одній ролі як два підключення.
Хост агностичний щодо того, від котрого з них надійшло рішення: він маршрутизує корисне навантаження, зчитує вердикт або зміну і діє відповідно. Перехід політики з однієї мови на іншу — це зміна підключення та переписування правил, а ніколи не зміна хоста.
Політики Rego: два шляхи
Rego — поширена мова політик, і запустити її можна двома шляхами: рушієм із мінімальними зусиллями, що постачається всередині компілятора, і запасним виходом із повною точністю.
Рушій Rego у компіляторі — шлях із мінімальними зусиллями. Він містить нативний для Wasm обчислювач Rego, тож оператор додає файл .rego до sources і підключає plugin — без зовнішнього інструментарію й без жодних завантажень під час збирання. Він обслуговує всі чотири ролі: той самий plugin оцінює граф збирання, оцінює відрендерений результат, формує мітки або додає анотації — залежно від ролі, у якій його підключено. Його ідентичність у каталозі — просте ім’я rego у pluginType: governance, тобто координата governance/rego, а його версія — це release компілятора, який його постачає. Написанню політики для нього присвячено наступний розділ.
Обчислювач є незалежною реалізацією Rego, а не вбудованою еталонною реалізацією, і реалізує не всі вбудовані функції Rego. Коли політика викликає вбудовану функцію, яку обчислювач не реалізує, підключення явно завершується помилкою: воно повертає збій, а не дозвіл. Тоді збирання зупиняється зі збоєм, що називає plugin, — навмисно відмінним від вердикту halt, щоб «рушій не може обчислити цю політику» ніколи не сприйняли як «політика дозволяє збирання». Політика, яку неможливо обчислити, зупиняє збирання; вона ніколи не проходить непомітно.
Запасний вихід opa build -t wasm — шлях із повною точністю. Коли політиці потрібен повний набір вбудованих функцій або точна семантика еталонного рушія, скомпілюйте її власним інструментарієм OPA у модуль Wasm і запускайте цей модуль за тонким гостьовим адаптером. Адаптер повністю поглинає Wasm ABI від OPA всередині себе (згідно з ABI належить Aggrega вище): він створює екземпляр модуля, зібраного OPA, задає вхідні дані, запускає обчислення й перетворює рішення назад на форму вердикту. Хост бачить лише стандартну поверхню вердиктів governance.
Як робочий приклад постачається еталонний гостьовий адаптер. Він вбудовує політику, написану на Rego й попередньо скомпільовану за допомогою opa build -t wasm у модуль WebAssembly, — зафіксований артефакт, збережений у репозиторії, тож обчислення повністю відбувається в гості, без процесу OPA й без жодних завантажень. Під час кожного збирання адаптер створює всередині себе екземпляр цього вбудованого модуля за допомогою вбудованого інтерпретатора Wasm, задовольняє власні імпорти модуля (його лінійну пам’ять і зворотні виклики вбудованих функцій), читає payload як документ OPA input, а settings підключення — як документ OPA data, обчислює кожну скомпільовану точку входу й зіставляє ім’я точки входу deny / warn / audit із рівнем серйозності вердикту — відповідно halt, warn і info. Якщо вбудованій політиці потрібна вбудована функція, що надається хостом, а адаптер її не реалізує, адаптер явно завершується помилкою — відхиляє модуль замість повернення дозволу, — тож політика, яку неможливо обчислити, зупиняє збирання, а не проходить непомітно. Повторне генерування вбудованого модуля з його вихідного коду Rego — це крок авторингу, що виконується через OPA CLI, а не залежність часу збирання. ../examples/policy-data-class-route/ збирає цей адаптер навколо власного модуля й наводить команди, що повторно генерують обидва.
Обидва шляхи мають спільний контракт із хостом, тож перенесення політики з рушія в компіляторі на повний рушій — це зміна підключення.
Написання політики для рушія Rego
Рушій обчислює написаний оператором Rego повністю всередині гостя, у тій із чотирьох ролей, у якій його підключено. Підключивши його двічі, у двох ролях, з двома різними файлами політик, один рушій охоплює два моменти однієї збірки.
Корисне навантаження для ролі підключення є документом input політики, а об’єкт settings підключення є документом data політики, тож політика читає надане оператором порогове значення як data.max_replicas. Кожен файл, який підключення оголошує в sources, стає модулем політики, і обчислюється кожен пакет, який ці файли оголошують.
Яким синтаксисом правил написано політику
Rego має два синтаксиси правил, і рушій приймає обидва, модуль за модулем. Тому набір політик, складений до появи поточного синтаксису, обчислюється поряд із написаним сьогодні, в тому самому підключенні.
У поточному синтаксисі тіло правила починається з if, правило, що збирає значення в множину, позначає це через contains, а модуль заявляє, яким синтаксисом його написано, оголошенням import rego.v1 в окремому рядку під оголошенням пакета:
package example
import rego.v1
deny contains msg if { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}У старішому синтаксисі з квадратними дужками в голові значення, яке збирає правило, стоїть у квадратних дужках у голові правила, а тіло йде одразу за нею. Модуль у цьому синтаксисі нічого не оголошує, бо його розпізнають за тим, що він не розбирається як поточний:
package example
deny[msg] { count(input.graph.spec.nodes) > 20 msg := "this build declares more than twenty nodes"}Модуль, який розбирається як поточний синтаксис, але нічого не оголошує, відхиляється з поясненням. Саме оголошення фіксує прочитання, і без нього той самий текст правила може дати протилежне рішення: тіло правила, яке ніколи не виконується, не дає рішення в поточному синтаксисі й дає його в старішому, тож політика, яка мала б мовчати, зупиняє збірку, а дзеркальний випадок пропускає збірку, яку правило мало зупинити. Замість того щоб обирати прочитання для такого модуля, рушій відхиляє його й повідомляє, що додати:
policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.Відхилення є збоєм збірки з назвою плагіна, а не вердиктом, тож воно зупиняє збірку так само, як політика, яку неможливо обчислити, і ніколи не читається як політика, що її дозволила.
Варто знати про два граничні випадки, перш ніж вони вас здивують. Модуль зовсім без тіл правил — той, що лише оголошує дані, — розбирається як поточний синтаксис, тож від нього теж вимагають оголошення, хоча два прочитання для нього не могли б відрізнятися. А модуль, написаний старішим синтаксисом, ніколи не відхиляється, бо він не розбирається як поточний: саме рушій розрізняє їх, тож навмисну політику з квадратними дужками ніколи не сплутають із політикою в поточному синтаксисі, яка забула це заявити.
Політика збирає свої рішення під ключем рішення
Кожна роль зчитує рішення політики з ключа рішення — іменованого правила, у яке збирає політика. Які ключі зчитуються і що означає рішення під ключем, визначає роль.
У ролі вердикту рішення — це повідомлення, а ключ, під яким його зібрано, визначає серйозність, з якою це повідомлення звітується. Типово ключами є загальноприйняті назви колекцій Rego:
| Зібрано під | Звітується як | Вплив на збірку |
|---|---|---|
deny | halt | зупиняє збірку |
warn | warn | з’являється поряд зі збіркою, яка завершується |
audit | info | записується; результат збірки не змінюється |
Розрізняйте два словники, бо їх справді два: deny, warn і audit — це назви у вашій політиці, а halt, warn і info — серйозності, з якими звітує сокет. Ліву колонку ви можете перейменувати; права колонка — закрита множина, спільна для всіх сокетів.
Політика, яка називає свої рішення інакше, оголошує відображення в налаштуваннях підключення:
with: settings: translation: - key: blocked severity: halt - key: advisory severity: warnОголошене відображення замінює типове, а не розширює його: ключі, які воно називає, — це саме ті ключі, що зчитуються, тож політика, яка й далі збирає в deny, не дає жодного вердикту, щойно оголошено наведене вище відображення. Порядок, у якому оголошено правила, є порядком, у якому звітуються вердикти. Ключ, який політика не оголошує, — це відсутнє рішення, а не збій, тож один файл політики може обслуговувати кілька підключень.
Серйозність поза цими трьома та відображення, оголошене порожнім, відхиляються схемою налаштувань, яку оголошує плагін, — хост перевіряє налаштування підключення за нею перед диспетчеризацією. Той самий ключ, відображений двічі, відхиляється під час зчитування відображення, що теж відбувається до запуску будь-якої політики. В обох випадках збірка зупиняється до ухвалення рішення, і ніколи з наполовину застосованим відображенням.
В іншому налаштування є власними даними політики: відображення зчитується з об’єкта, а об’єкт потрапляє в документ data політики без змін, тож політика, написана для типових ключів, бачить саме той документ даних, який бачила б без жодного налаштованого відображення.
У ролі перетворення рішення — це зміна, яку слід внести, а не повідомлення, тож серйозності, яку треба визначати, немає, і натомість фіксованим є ключ: labels у ролі формування міток, annotations у ролі впровадження анотацій. Налаштування translation зчитується лише там, де звітуються вердикти, тож підключення перетворення, яке його оголошує, несе налаштування, яке його роль не використовує.
Ключ рішення зчитується з кожного пакета, який завантажує підключення, тож набір політик може розподіляти свої правила між пакетами, і кожен додає те, що зібрав. Зворотний бік цього варто знати, перш ніж він дасться взнаки: у межах одного підключення ключ рішення є зарезервованою назвою правила в кожному пакеті, тож записи допоміжного пакета, який для власних потреб збирає в labels, зчитуються як рішення щодо міток. Це спричиняє явний, а не тихий збій — підключення повідомляє, що щось, зібране під ключем, не є рішенням такої форми, — але найшвидше читати таке повідомлення як конфлікт назв, тож залишайте ключ для рішення, а допоміжному правилу давайте іншу назву.
Що надає корисне навантаження кожної ролі
Корисне навантаження є документом input політики, тож політика читає його під тими іменами,
які дає йому протокол передавання.
Граф збірки розташований за різними шляхами у двох ролях, які його передають. Вердикт над графом отримує весь документ графа, тож його вузли розташовані за input.graph.spec.nodes; роль формування міток отримує проєкцію вузлів, тож її вузли розташовані за input.graph.nodes. Тому правило, перенесене між цими двома ролями, слід редагувати, а не копіювати, — і симптомом забування є правило, яке ніколи не спрацьовує, а не помилка, бо шлях, якого немає, просто не визначений.
| Роль | Що читає політика |
|---|---|
ir-verdict | input.graph — увесь документ графа збірки: вузли за input.graph.spec.nodes з ключами за id вузла, ребра за input.graph.spec.edges. Значення, яке автор оголосив чутливим, читається як {"aggrega_withheld": "declared"}. input.precalculated_paths — перелічені шляхи маршрутизації, кожен з упорядкованим списком nodes та attached_features, типами Feature, приєднаними будь-де на ньому (див. нижче). Список присутній завжди: збірка без маршруту між компонентами передає порожній список. |
render-verdict | input.artifacts — один запис на кожен згенерований файл, кожен з path, content, format і documents, розібраними документами файлу. format — це формат, який оголосив для файлу провайдер, що його відрендерив: провайдер Terraform оголошує hcl для кожного файлу .tf, який він генерує, і json для кожного файлу .tf.json, включно з файлами вендорного модуля, — або порожній рядок, якщо жоден провайдер його не оголосив, як для файлу, який сутність Recipe додає до спільного виводу межі. Такий файл однаково розбирається за розширенням, тож його documents присутні в будь-якому разі. Артефакт, який не вдалося прочитати структурно, передає parse_error і жодних документів, тож політика може відхилити саму помилку, а не пропустити нечитаний файл неперевіреним. |
label-transform | input.graph.nodes — вузли збірки з ключами за id вузла, кожен з component, resolved_version, labels і values: значеннями, які екземпляр вузла оголошує в сутності Aggregate, із шаблонами, обчисленими відносно його параметрів; поле відсутнє, якщо екземпляр нічого не оголошує. Значення, яке сутність Component вузла оголошує чутливим, читається як {"aggrega_withheld": "declared"}, як і в ir-verdict, а сусідні неоголошені значення читаються так, як записані. Правило читає input.graph.nodes[id].values, щоб ухвалити рішення щодо мітки; змінити значення воно не може. input.compilation_context — release_name і environment сутності Release, тож політика може ухвалювати різні рішення для різних середовищ. |
annotation-transform | input.targets — кожен компонент, який приєднання може анотувати, кожен з boundary_path, component_name — для компонента, який розміщує запис маршрутизації, це його ідентифікатор у графі збірки, як-от metrics.query, — і annotations, які сутність Release записує на самому компоненті, причому кожне значення — так, як записане: рядок, об’єкт підключів або null, якщо компонент відмовляється від анотації, яку успадкував би. Кожен ключ, який має компонент, присутній незалежно від значення, тож правило може не чіпати ключ, який хтось уже записав. input.binding_keys — ключі анотацій, для яких сутність Manifest реєструє прив’язку. |
Ресурс Terraform читається за різними шляхами в кожній із двох форм Terraform. У documents нативного файлу .tf блок вкладається під свій тип, а потім під кожну зі своїх міток, і остання мітка містить список блоків, бо блоки з однаковими типом і мітками збираються в один список у порядку вихідного тексту. Тому атрибут ресурсу читається за шляхом input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> — для екземпляра RDS з будь-яким іменем це input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage. Файл .tf.json читається так, як його записала сутність Recipe, тож його звична об’єктна форма, де ім’я містить сам блок, читається за шляхом resource.<type>.<name>.<attr>, і політика, призначена для обох форм, читає обидва шляхи. Це стосується обох рушіїв політик усередині компілятора. Для правила Rego, написаного для іншої форми, названий шлях невизначений: правило, що перевіряє там значення, ніколи не спрацьовує, а правило, що відхиляє за відсутності значення за допомогою not, спрацьовує на кожному ресурсі; вираз CEL, який індексує або вибирає в іншій формі, зупиняє збірку помилкою обчислення з назвою свого файлу політики. Еталонний адаптер рендерингу Rego, описаний нижче в розділі Адаптери політик етапу рендерингу, сам розбирає нативний файл .tf і читає одиничний блок як об’єкт, тож коли політика переходить між цим адаптером і рушієм усередині компілятора, шлях Terraform слід редагувати, а не копіювати.
Кожна роль додатково передає input.sources — власні файли приєднання, кожен зі своїм базовим іменем path і своїм content. Політика виконується лише як один із цих файлів, тож хоч би де правило читало цей список, у ньому є щонайменше цей файл.
input.settings — об’єкт налаштувань приєднання, той самий об’єкт, що й документ data політики; він присутній, коли приєднання оголошує налаштування. Якщо приєднання їх не оголошує, те, що знайде правило, залежить від ролі: в ir-verdict, label-transform і annotation-transform поле відсутнє, тож input.settings не визначене, як будь-який шлях, якого немає в корисному навантаженні, а в render-verdict це порожній об’єкт. Тому правило, що залежить від того, чи налаштування було задано, перевіряє саме налаштування, яке читає, а не об’єкт, і це поводиться однаково в кожній ролі: задане max_nodes читається, а незадане залишає input.settings.max_nodes невизначеним і правило мовчазним:
package example
import rego.v1
deny contains msg if { limit := input.settings.max_nodes count(input.graph.spec.nodes) > limit msg := sprintf("this build declares more than %v nodes", [limit])}Рушій CEL обробляє неоголошений об’єкт налаштувань інакше й описує це у власному розділі нижче.
attached_features і binding_keys є списками, а не об’єктами, тож політика
перевіряє належність за допомогою in:
package security
import rego.v1
deny contains msg if { some path in input.precalculated_paths some gateway in path.nodes input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"] not "core/data-masking" in path.attached_features msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])}attached_features — це об’єднання типів Feature усіх приєднань, які має
будь-який вузол на шляху, — зокрема приєднання, записаного на одному зі з’єднань цього вузла,
хоч на якому з’єднанні його записано, — тож правило задовольняє приєднання
core/data-masking на самому шлюзі, де ця Feature
і приєднується: вона обирає за можливістю маскування вмісту, яку оголошує шлюз. Маскує
приєднання текст чатів і доповнень, що проходить через цей шлюз;
правило перевіряє, що приєднання існує, а не що воно перелічує.
Оскільки це об’єднання за всім шляхом, список повідомляє, що Feature приєднано десь на маршруті, і ніколи — де саме. Правило, якому потрібно знати, чи розташована Feature між двома певними компонентами маршруту — тим, що містить дані з обмеженим доступом, і тим, до якого він звертається, — читає nodes маршруту по порядку та власні приєднання кожного вузла за input.graph.spec.feature_values_mapping[<node>]; якщо поставити те саме питання attached_features, воно пропустить маршрут, на якому Feature розташована за другим компонентом. ../examples/policy-data-class-route/ написано саме так — для рушія Rego, рушія CEL та OPA.
Об’єкт вузла не має власного id: id — це ключ, під яким він розташований у
input.graph.spec.nodes, тому правило вище переносить id, прочитані з
path.nodes, у своє повідомлення, а не читає поле id.
Порядок, у якому політика зустрічає ключі мапи
Граф зберігає порядок, у якому його написав автор: вузли — у порядку оголошення компонентів, а мітки кожного вузла — у порядку, в якому їх має вузол. Цей порядок без змін потрапляє в гостьовий модуль — корисне навантаження передає обидва як упорядковані записи (див. мапи, що зберігають свій порядок). Чи зустріне його політика, визначає те, як рушій, що обчислює політику, зберігає об’єкт, а не корисне навантаження:
- Рушій Rego зберігає ключі об’єкта відсортованими. Правило, що ітерує
input.graph.spec.nodes,labelsвузла чи будь-який інший об’єкт — зокрема написаний у самій політиці, — зустрічає ключі у відсортованому порядку: компоненти, оголошені якweb,api,metrics, зустрічаються якapi,metrics,web. - Рушій CEL не фіксує порядку для мапи. Comprehension над
input.graph.spec.nodesабо надlabelsвузла може зустріти ключі в різному порядку у двох збірках з ідентичними вхідними даними, а два обходи тієї самої мапи в межах одного виразу можуть відрізнятися між собою. Саме тому повідомлення під одним ключем рішення сортуються: пишіть правило, рішення якого не залежить від позиції ключа. - Гостьовий модуль, написаний із набором для плагінів, зустрічає авторський порядок. Після декодування через свій набір вузли та мітки кожного вузла потрапляють в упорядкований контейнер набору в тому порядку, в якому їх передає корисне навантаження, а каркас адаптера врядування, що постачається з кожним набором, передає своєму рушію документ JSON, записаний у тому самому порядку. Рушій, що перетворює цей документ на значення власного типу, натомість зустрічає порядок цього типу, як описано в мапах, що зберігають свій порядок.
Формування міток: політика називає мітку, а рушій її адресує
У ролі формування міток політика збирає одне рішення на мітку під labels,
називаючи вузол, ключ мітки та значення, якого мітка набуває:
package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/type"] == "stateful-server"}Встановлення ключа, який уже присутній, замінює його значення. Натомість рішення може вимагати видалити ключ:
labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if { some id, node in input.graph.nodes node.labels["draft.example.com/scratch"]}Політика називає мітку, а не пише інструкцію редагування, яку застосовує збірка,
і причину варто знати: інструкція адресує мітку за шляхом, а ключ мітки
Aggrega зазвичай містить /, який є роздільником шляху, — тож написаний вручну шлях
адресував би вкладене розташування замість однієї мітки. Рушій
адресує мітку, яку називає рішення, тож екранування написано один раз, а не в
кожній політиці, і політика залишається зрозумілою як твердження про мітки, а не
про шляхи.
Рішення може змінювати лише мітку. Кожна інструкція, яку генерує рушій, адресує одну мітку на одному вузлі, тож політика не може виразити зміну сутності Component вузла, його розв’язаної версії, набору вузлів чи значення мітки, яке не є рядком. Рішення, що називає вузол, якого збірка не має, або видаляє мітку, якої вузол не має, збірка відхиляє з повідомленням, що називає інструкцію, — і ніколи мовчки не ігнорує.
../examples/policy-label-transform/ приєднує таку політику поруч із двома вбудованими плагінами тегування, а також вердикт над графом, який читає мітки, що їх вони записують. Що читає і записує кожен із цих плагінів, описано на сторінці Вбудовані плагіни тегування.
Додавання анотацій
У ролі додавання анотацій політика збирає одне рішення на анотацію під
annotations, називаючи ціль за координатою, яку має сама ціль, а також
ключ і його значення:
package tagging
import rego.v1
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly",} if { some target in input.targets not target.annotations["backup.example.com/schedule"]}Імена полів, які пише рішення, — це імена полів, під якими воно прочитало свої цілі, тож цю домовленість можна засвоїти лише з корисного навантаження. Читання input.binding_keys дає політиці змогу додавати лише ключі, для яких сутність Manifest зареєструвала значення, — саме вони розгортаються в приєднання Feature.
Значення рішення — це те, що ви могли б самі записати в цю анотацію: рядок або об’єкт підключів. Прив’язка, що маршрутизує один підключ, приймає рядок; прив’язка, що маршрутизує кілька, приймає об’єкт, який називає кожен із них, — саме так, як оператор записує його в сутності Release:
annotations contains { "boundary_path": target.boundary_path, "component_name": target.component_name, "annotation_key": "feature.aggrega.ai/monitoring", "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { some target in input.targets not target.annotations["feature.aggrega.ai/monitoring"]}Збірка читає додане значення точно так само, як те саме значення, записане в сутності Release, тож воно розгортається так само і так само перевіряється щодо прив’язаної сутності Feature. Рушій зберігає ключі об’єкта відсортованими, тож підключі надходять до збірки у відсортованому порядку. Значення будь-якої іншої форми — null, список, число, булеве значення або об’єкт без підключів — збірка відхиляє, називаючи додавання: роль додає анотації, а null або порожній об’єкт читається як відмова, яку автор пише, щоб вилучити анотацію. Рішення, що називає компонент, якого немає в корисному навантаженні, відхиляється так само, із зазначенням координати й анотації.
Коли збірка відхиляє додану анотацію через те, як вона маршрутизується або що містить, — рядок, переданий прив’язці, що маршрутизує кілька підключів, значення підключа, якого не допускає схема прив’язаної сутності Feature, або підключ, маршрутизований через опору values, якою анотація на боці сутності Release користуватися не може, — відмова називає плагін, що її додав, і роль управління, до якої його приєднано, тож значення простежується до політики, яка його визначила, а не до рядка в сутності Release, якого ніхто не писав.
../examples/policy-annotation-transform/ приєднує таку політику, додаючи рядок під однією прив’язкою та об’єкт підключів під іншою, і збирає ті самі файли, що й сутність Release, у якій ці анотації записано вручну.
Підключення цілого набору політик одним архівом
Набір політик підключають пофайлово або одним архівом, що містить разом його файли політик і документи даних, — у тій формі, яку збирає інструментарій Rego. Вміст підключеного файлу передається гостю як текст, а стиснений архів є довільними байтами, а не текстом, тож архів підключають у кодуванні base64, з назвою, що закінчується на .base64:
tar czf bundle.tar.gz policy.rego data.jsonbase64 -w0 bundle.tar.gz > bundle.tar.gz.base64with: sources: - ./policies/bundle.tar.gz.base64Саме назва позначає файл як архів, а не як текст політики, і завдяки цьому вибір лишається явним рішенням оператора: пошкоджений архів тоді повідомляється як пошкоджений архів, із назвою файлу та кроку, що завершився невдачею, а не читається як файл політики, який не вдається розібрати. Кодування архіву — це крок, який оператор додає після того, як його інструментарій зібрав архів.
Усередині архіву кожен елемент .rego є модулем політики, а кожен елемент data.json або data.yaml є документом даних, вкладеним під каталог, у якому він лежить: limits/data.json із вмістом {"max": 3} політика читає як data.limits.max. Елементи будь-якого іншого типу архів містить для власного інструментарію, і вони не є вхідними даними політики.
Архів, який не вдається відкрити, — це збій із назвою підключеного файлу: кодування, яке не декодується, потік, який не розпаковується, обрізаний архів, файл даних, який не читається, або архів, що взагалі не містить політики. Жоден із цих випадків не дає порожнього набору політик, бо порожній набір політик не доходить до жодного рішення, — а «архів не вдалося прочитати» ніколи не повинно бути неможливо відрізнити від «політика дозволила збірку».
Написання політики для рушія CEL
Рушій обчислює написаний оператором CEL повністю всередині гостя, у тій із чотирьох ролей, до якої його під’єднано. Його ідентичність у каталозі — просте ім’я cel
під pluginType: governance — координата governance/cel, — а його версія —
це реліз компілятора, що його постачає. Під’єднавши його двічі, у двох ролях, із двома
різними файлами політик, один рушій охоплює два моменти однієї збірки.
plugins: governance: - uri: governance/cel:<version> role: ir-verdict with: sources: - ./policies/topology.cel settings: max_nodes: 20Політика звертається до всього корисного навантаження через одне ім’я, input, тож імена, які вона читає,
— це імена, які їм дає дріт: граф збірки в input.graph, перелічені
шляхи маршрутизації в input.precalculated_paths, відрендерені файли в
input.artifacts, цілі анотацій в input.targets. Ці шляхи для кожної ролі —
ті самі, що наведені в таблиці Що відкриває корисне навантаження кожної ролі
вище, і вони однакові для обох рушіїв — один дріт, що читається під одним кореневим ім’ям.
Власні файли під’єднання розташовані в input.sources, а його налаштування — в input.settings, тож наданий оператором поріг читається як input.settings.max_nodes. Другого документа вивчати не треба: налаштування є частиною input, як і все інше. Обидва завжди присутні як значення — коли під’єднання їх не оголошує, налаштування є порожнім об’єктом у кожній ролі, — тож виразу, що до них звертається, не потрібно перевіряти їхню відсутність, а чи було задано окреме налаштування, перевіряється за його ключем: has(input.settings.max_nodes).
Дві форми написання та ім’я файлу, яке обирає між ними
Політику під’єднують в одній із двох форм, і ім’я файлу вказує, в якій:
| Ім’я файлу закінчується на | Читається як |
|---|---|
.cel | один вираз, що обчислюється як є |
.yaml або .yml | документ правил — список правил |
| будь-що інше | один вираз |
Ім’я — це все правило. Жодне налаштування не обирає форму, і текст файлу не аналізується, щоб її вгадати, — він і не зміг би відповісти на це питання, бо зовнішнє значення виразу є мапою, як і в документа правил, що робить дві форми нерозрізненними за формою.
Тож правило діє в обидва боки, і обидві помилки відхиляються, а не
хибно читаються. Документ правил з ім’ям policy.cel відхиляється, бо список правил YAML
не є виразом; вираз з ім’ям policy.yaml відхиляється, бо
вираз не є списком правил. Кожна відмова називає файл. Перейменування файлу —
виправлення в обох напрямках.
Набір політик складається з такої кількості файлів, яка йому потрібна, і дві форми вільно змішуються в межах одного під’єднання.
Вираз у файлі з іменем .cel
Мова виразів не має імен правил, під якими збирати рішення, тож рішення і є значенням, яке створює вираз: мапою від ключа рішення до того, що цей ключ збирає. У ролі вердикту ключ збирає повідомлення, досягнуті під ним; у ролі, що формує збірку, він збирає рішення, які слід застосувати.
{ "deny": input.graph.spec.nodes .filter(n, input.graph.spec.nodes[n].resolved_version == "latest") .map(n, "component " + n + " tracks the latest version; pin it"), "warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],}Ключ, який файл пропускає, не досяг там жодного рішення, тож файлу не потрібно називати кожен ключ — а кожна роль читає лише ключ, що її стосується, тож один набір політик може обслуговувати роль вердикту й роль, що формує збірку, з тих самих файлів. Ключ містить список того, що він збирає, один такий елемент або значення null, якщо нічого.
Вираз, що обчислюється в будь-що, крім мапи, відхиляється з указанням форми,
яку слід написати. Простий size(input.graph.spec.nodes) <= 5 — це помилка, на яку варто очікувати:
це булеве значення, і читання false як зупинки означало б вигадування повідомлення, якого
автор ніколи не писав.
Документ правил у файлі з іменем .yaml або .yml
Документ правил — це список правил, кожне з яких називає ключ рішення, якого досягає, вираз, що визначає, чи його досягнуто, і те, що повідомляється, коли так:
- key: deny expression: size(input.graph.spec.nodes) > 20 message: this build declares a lot of components- key: warn expression: has(input.settings.max_nodes) message: a component ceiling is configured for this environmentТе, що повідомляє правило, залежить від ключа рішення, якого воно досягає, точно так само, як у виразі. Текст — це повідомлення, яке несе вердикт. Відображення — це поля єдиного рішення, яке читає роль, що формує збірку:
- key: labels expression: input.compilation_context.environment == "production" message: node: app key: compliance.example.com/tier value: goldЩо з двох пише правило, вирішує лише саме правило — немає налаштування, яке це обирає, — а правило, що пише не те для свого ключа, відхиляється з указанням імені.
Одна деталь YAML, про яку варто знати, перш ніж вона дасться взнаки: вираз, що починається з подвійної
лапки, треба взяти в лапки для читача документа, бо значення, що відкривається ",
читається як скаляр у лапках, а не як текст, що починається з лапки.
- key: annotations expression: '"backup.example.com/schedule" in input.binding_keys' message: boundary_path: main component_name: app annotation_key: backup.example.com/schedule annotation_value: nightlyДокумент правил читається як вираз, який він представляє, ще до будь-якого обчислення. Кожне правило стає своїм ключем рішення, що несе його повідомлення, коли вираз істинний, і нічого, коли ні, а правила зі спільним ключем об’єднуються. Тож один обчислювач виконує обидві форми, і документ правил вирішує саме те, що вирішує вираз, який він представляє, — у кожній ролі, як для вердиктів, так і для рішень, що формують збірку. Звідси два наслідки. Документ і написаний вручну вираз, який він представляє, досягають тих самих рішень, бо це одне й те саме обчислення. А правила впорядкування нижче належать обчисленій формі, а не документу, — правила документа не повідомляються в тому порядку, в якому їх написано.
Яка форма підходить — вони не взаємозамінні
Обидві форми виконуються одним обчислювачем, тож жодна не швидша й не надійніша за іншу. Відрізняється те, що кожна може сказати, і оскільки дві форми — це дві речі, які треба вивчити, розподіл варто сформулювати прямо, а не залишати на смак. Обирайте за тим, що повідомляє правило.
- Документ правил, коли повідомлення фіксоване. Повідомлення або рішення пишеться один раз, поруч із виразом, що його досягає, і файл читається як список перевірок. Це коротша форма для «якщо це істинно, скажи саме це».
- Вираз, коли повідомлення називає те, що знайдено. Один вираз фільтрує
компоненти збірки й створює повідомлення — або рішення — для кожного компонента, тож
читач отримує
component payments tracks the latest version; pin itдля кожного порушника, а не одне речення про кількість.
Це друге завдання документ правил виконати не може: кожне його правило несе одне повідомлення, написане заздалегідь, тож воно нічого не може сказати про те, який компонент його спрацював. Обрати форму документа, а потім захотіти ім’я порушника в повідомленні — це шлях, що закінчується переписуванням правила як виразу, тож варто вирішити це питання заздалегідь.
Що може сказати вираз
Вирази, які обчислює цей рушій, використовують включення filter, map і exists,
+ для рядків і списків, size, in, startsWith, string(),
умовний оператор і список, індексований обчисленим цілим числом. Вони не
пропонують функцій розширень, які додають деякі середовища CEL: join, split,
substring, indexOf, flatten, cel.bind і lists.range відхиляються як
неоголошене посилання, а включення приймає одну змінну, тож форма з двома змінними,
як-от exists(i, v, …), відхиляється так само. Відмова — це збій збірки з указанням
файлу й посилання:
policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'Три наслідки формують правило, що обходить маршрут:
- Немає способу назвати проміжне значення. Підвираз, використаний двічі,
пишеться двічі або зв’язується через відображення списку з одного елемента:
[value].map(name, …)[0]обчислює своє тіло один раз ізname, зв’язаним ізvalue. - Немає способу обійти позиції списку. Правило, що порівнює компоненти маршруту
за позицією, бере позиції зі своїх налаштувань — список
positions, як-от[0, 1, 2, …], — і індексує маршрут у кожній, тож воно має перевіряти маршрут, довший за сам список, зупиняючись на такому, а не читати його частково. - Ключ рішення збирає повідомлення, а не їхні списки. Вираз, що створює один список повідомлень для кожного маршруту, відхиляється під ключем рішення — збій повідомляє, що зібрано значення типу list, а не повідомлення, — тож правило створює один запис для кожного маршруту й будує з нього повідомлення. А повідомлення, яке вираз створює двічі, повідомляється двічі: описане нижче сортування впорядковує те, що зібрав ключ, і не видаляє повторів.
../examples/policy-data-class-route/ містить правило CEL, написане з урахуванням усіх трьох, поруч із тим самим правилом для рушія Rego.
Ключі рішень і рівні серйозності
Ключі рішень, типове зіставлення з рівнями серйозності та налаштування translation, яке їх перейменовує, такі самі, як і для рушія Rego, — див.
Політика збирає свої рішення під ключем рішення
вище. Типово deny звітує на рівні halt, warn — на рівні warn, а audit — на рівні info; оголошене translation замінює це типове зіставлення, а не розширює його, і порядок, який воно оголошує, є порядком, у якому звітуються вердикти.
Обидва рушії оголошують для нього однакову схему налаштувань, тож блок translation означає те саме незалежно від того, якою мовою виражено рішення, а неправильно сформований блок відхиляється ще до запуску будь-якої політики.
У ролі, що формує збірку, ключ фіксований, а не зіставлений: labels у ролі формування міток, annotations у ролі впровадження анотацій.
Упорядкування: сортування в межах ключа та повний порядок над рішеннями
Повідомлення під одним ключем рішення звітуються у відсортованому порядку. Це частина контракту, а не вибір способу подання, і причину варто пам’ятати: обхід мапи — .filter(...) і .map(...) над input.graph.spec.nodes, що є найприроднішим способом написати правило для кожного компонента, — проходить цю мапу в порядку, який обчислювач не фіксує. Без сортування ідентичні вхідні дані звітували б ті самі повідомлення в різній послідовності під час кожної збірки. Сортування це усуває.
З цього випливають дві речі, які легко сприйняти як помилки, хоча вони ними не є:
- Правила документа правил також звітуються відсортованими, а не в тому порядку, у якому їх написано, — бо документ обчислюється як вираз, який він представляє, а сортування застосовується до того, що зібрав ключ.
- Написаний вручну список також сортується. Ключ, що містить
["second", "first"], звітуєfirstпередsecond. Ніщо в обчисленому результаті не відрізняє список, набраний автором, від списку, створеного обходом, тож немає авторського порядку, який слід було б зберегти.
Між ключами порядок визначається оголошеним порядком translation. Між файлами це порядок імен файлів, бо джерела прикріплення надходять відсортованими за іменем, а не в порядку, у якому їх перелічує прикріплення.
У ролі, що формує збірку, те саме міркування стосується самих рішень, і порядок суворіший: рішення звітуються в порядку зростання всього, що вони називають, а це повний порядок над тим, що може виразити рішення: вузол, потім ключ мітки, потім те, чи мітку додано або вилучено, потім значення; а для впровадження — межа, потім компонент, потім ключ анотації, потім її значення. Зміна міток або анотацій потрапляє у відрендерений вивід, тож довільний порядок означав би, що ідентичні вхідні дані рендеряться по-різному від збірки до збірки.
Формування міток
У ролі формування міток політика збирає одне рішення на мітку під labels,
називаючи вузол, ключ мітки та значення, якого мітка набуває:
{ "labels": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server") .map(n, { "node": n, "key": "compliance.example.com/tier", "value": input.compilation_context.environment == "production" ? "gold" : "bronze", }),}Встановлення ключа, який уже присутній, замінює його значення. Натомість рішення може вимагати вилучення ключа, якщо вказати op як remove:
{ "labels": input.graph.nodes .filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels) .map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),}Одне рішення не потребує списку довкола себе, а файл без ключа labels не ухвалює рішень щодо міток.
Політика називає мітку, а не пише інструкцію редагування, яку застосовує збірка, з причини, наведеної в
розділі про формування міток рушія Rego:
ключ мітки Aggrega зазвичай містить /, і написаний вручну шлях адресував би вкладене розташування замість однієї мітки. Рушій адресує мітку, яку називає рішення.
Читання мітки, якої вузол може не мати, є збоєм, а не порожнім значенням, саме тому другий приклад перевіряє наявність ключа перед його читанням. Це власне правило мови виразів щодо читання відсутнього ключа, і воно гучне: політика, що звертається до мітки, якої не має жоден вузол, повідомляє, що її не вдалося обчислити, замість того щоб тихо нічого не вирішити.
Рішення може змінювати лише мітку. Рішення, що називає вузол, якого немає у збірці, або вилучає мітку, якої вузол не має, збірка відхиляє з повідомленням, що називає інструкцію, — і ніколи не ігнорує мовчки.
Ухвалюйте одне рішення на вузол і ключ мітки. Правило, яке може дати два різні значення для тієї самої мітки на тому самому вузлі, недовизначене: визначайте значення всередині виразу — умовним оператором або фільтром, що пропускає одну гілку, — а не видавайте обидва рішення.
../examples/policy-label-transform/ показує роль формування міток від початку до кінця, з політикою, написаною для рушія Rego.
Впровадження анотацій під зареєстрованим ключем
У ролі впровадження анотацій політика збирає одне рішення на анотацію під
annotations, називаючи ціль за координатою, яку несе сама ціль, а також ключ і його значення:
{ "annotations": input.targets .filter(t, "backup.example.com/schedule" in input.binding_keys) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "backup.example.com/schedule", "annotation_value": "nightly", }),}Імена полів, які записує рішення, — це імена полів, під якими воно прочитало свої цілі, тож цю домовленість можна засвоїти лише з корисного навантаження. Читання input.binding_keys дає політиці змогу впроваджувати лише ключі, для яких Manifest зареєстрував значення, — саме вони розгортаються в прикріплення Feature. Кожне поле обов’язкове: анотація з порожнім ключем або порожнім іменем компонента — це не те, що політика мала намір запросити. Межу, під якою розташований компонент, цілком законно може позначати порожній рядок, тож це поле має бути присутнім, але може бути порожнім.
Значення — це те, що ви могли б самі записати в цю анотацію: рядок або мапа підключів, яка й живить прив’язку, що маршрутизує кілька підключів одночасно, — "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}. Рушій записує підключі мапи у відсортованому порядку, оскільки мова виразів не фіксує порядку для мапи, і передає значення далі таким, яким його створив вираз; значення, якого модель JSON не може містити, — байти, позначка часу, тривалість — відхиляється, а не перетворюється на текст. Потім збірка читає значення точно так само, як те саме значення, записане в сутності Release, і відхиляє null, список, число, булеве значення або порожню мапу, називаючи додавання. Два рішення для одного компонента й ключа з різними значеннями впорядковуються за JSON значення. annotations цілі містять кожне наявне значення так, як його записано, — рядок, мапу або null для відмови, — тож перевірка "feature.aggrega.ai/monitoring" in t.annotations знаходить ключ незалежно від його значення.
Рішення, що називає компонент, якого немає в корисному навантаженні, збірка відхиляє, називаючи координату й анотацію. Коли збірка відхиляє додану анотацію через її маршрутизацію, значення її підключів або її опору, відмова називає плагін, що її додав, і роль, до якої його приєднано. Як і з мітками, ухвалюйте одне рішення на компонент і ключ анотації, визначаючи значення всередині виразу, а не видаючи два рішення для одного ключа.
../examples/policy-annotation-transform/ показує роль додавання анотацій від початку до кінця, з політикою, написаною для обох рушіїв.
Коли політику або рішення неможливо прочитати
Політика, яку рушій не може прочитати, не може обчислити або яка дає щось інше, ніж рішення в задокументованій формі, призводить до збою збірки, а не до повернення вердикту чи зміни. Про збій повідомляється як про помилку збірки, що називає файл і, якщо помилка стосується однієї частини файлу, позицію в ньому, — свідомо відмінно від вердикту halt, щоб «цю політику не вдалося обчислити» ніколи не сплутали з «ця політика дозволяє збірку».
Для виразу це охоплює джерело, яке не розбирається, — про що повідомляється з власними рядком і стовпцем парсера та кареткою під проблемною позицією, — і джерело, яке обчислюється в щось інше, ніж мапа від ключа рішення до того, що цей ключ збирає.
Для документа правил це охоплює текст, що не є списком правил, список без правил, правило без поля або з порожнім полем, поле, яке форма не визначає, звіт, що не є ні текстом, ні мапою тексту на текст, і вираз, який неможливо прочитати. Помилка, що стосується одного правила, називає позицію цього правила — рахуючи від одиниці, як автор рахує у власному файлі, — і його ключ рішення. Правило, вираз якого не розбирається, відхиляється до обчислення, тож каретка вказує всередину виразу, написаного автором, а не на позицію в перекладеному тексті, якого він ніколи не бачив.
Для рішення в ролі, що формує збірку, це охоплює повідомлення там, де має бути рішення, відсутню координату та поле, яке форма рішення цього рушія не визначає. Останнє варто зазначити окремо: поле з помилкою в написанні annotation_valu відхиляється, а не ігнорується, тож про помилку повідомляється, а не тихо впроваджується порожнє значення, залишаючи збірку, яка завершується без зміни. Кожне таке відхилення називає файл і завершується переліком того, що має називати рішення такого типу.
Адаптери політик етапу рендерингу
Адаптер етапу рендерингу аналізує відрендерений вивід збірки, а не її граф IR. Payload рендерингу містить згенеровані артефакти — кожен зі своїм шляхом виводу та відрендереним вмістом, а також, де це застосовно, форматом, у якому його відрендерено, і розібраним структурованим поданням — плюс власні джерела та налаштування прикріплення, кожне — там, де прикріплення його оголошує. Адаптер читає цей вміст відповідно до форми виводу, на яку він орієнтований, обчислює політику над структурованим результатом і зіставляє підсумок із вердиктами halt / warn / info. Оскільки payload не називає жодної власної форми виводу, один шаблон адаптера обслуговує будь-яку ціль рендерингу; нова форма виводу — це новий адаптер, а не зміна хоста.
Кожен адаптер етапу рендерингу є адаптером у наведеному вище сенсі: назовні він говорить мовою ABI Aggrega, а всередину поглинає специфічний для цілі формат або контракт стороннього рушія політик, тож компілятор залишається вільним від будь-якої логіки форматів виводу чи політик. Рушії Rego та CEL у компіляторі безпосередньо обслуговують роль render-verdict; окрім них, серед прикладів на Rust із комплекту розробки плагінів як робочі приклади постачаються два еталонні адаптери етапу рендерингу, по одному на кожну поширену форму виводу.
../examples/policy-render-verdict/ приєднує одне правило в render-verdict до виводу чотирьох цілей — об’єктів Kubernetes, файлу Docker Compose, кореневої конфігурації Terraform і шаблону CloudFormation, — написане по одному разу для кожного рушія в компіляторі, і перевіряє, що закладене в кожну ціль порушення зупиняє збірку, а контрольний варіант проходить.
Щоб написати власний адаптер — для цієї ролі чи будь-якої іншої, — почніть зі скелета адаптера управління, який постачається з кожним комплектом розробки плагінів: Написання власного плагіна управління веде від цього скелета до збірки, яку адаптер відхиляє.
Вивід YAML, JSON і Terraform HCL — еталонний адаптер рендерингу Rego
Еталонний адаптер рендерингу Rego виконує надані оператором політики Rego над будь-яким виводом рендерингу YAML або
JSON, а також над нативним виводом HCL для Terraform. Це робочий приклад
форми етапу рендерингу: той самий нативний для Wasm обчислювач Rego, що й рушій у
компіляторі, і та сама домовленість про збирання deny / warn / audit, зіставлена з
тими самими трьома рівнями серйозності вердиктів, але з аналізом відрендерених файлів, а не
графа збірки.
Він незалежний від форми виводу для цілей YAML/JSON. Адаптер розбирає
вміст кожного артефакту як один або кілька документів YAML чи JSON — YAML є
надмножиною JSON, тож шаблон JSON, як-от стек CloudFormation, розбирається
тим самим парсером — і надає політиці розібрані документи
поряд із сирим вмістом. Політика аналізує структурований вивід рендерингу
будь-якої такої цілі звичайним Rego: input.artifacts[_].documents[_] дає
розібрані документи (services файлу Docker Compose, Resources шаблону CloudFormation),
input.artifacts[_].content дає сирий текст, а об’єкт settings
прикріплення є документом Rego data. Наприклад, політика вимоги схваленого
реєстру над виводом Docker Compose відхиляє будь-який сервіс,
образ якого не має префікса реєстру.
Адаптер також аналізує нативний HCL-вивід рендерингу Terraform. Нативний
файл .tf не є ні YAML, ні JSON, тому адаптер проєктує його в той самий
канонічний об’єкт, у який уже розбирається файл Terraform-JSON (.tf.json): політика
читає атрибут ресурсу за шляхом
input.artifacts[_].documents[_].resource.<type>.<name>.<attr> — для екземпляра RDS
це input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage
— однаково, хоч би яку форму Terraform згенерував компілятор. Типи атрибутів
зберігаються (число лишається числом, булеве значення — булевим), а нерозв’язаний
вираз Terraform лишається рядком у формі ${ ... }. Тіла Terraform-JSON
(.tf.json, .auto.tfvars.json) розбираються шляхом YAML/JSON без змін, а
файл шаблону Terraform (.tftpl) — текст шаблону, а не самостійна
конфігурація — не проєктується і, як будь-який
неструктурований вміст, видає parse_error.
Цей перелік описує, що приймає парсер адаптера, а не що генерує компілятор. Це не одна й та сама множина, і автоматично завантажуваний файл змінних — саме той випадок, де вони розходяться: компілятор не генерує такого накладання на жодному шляху — вхідні дані модуля з джерела є аргументами блоку module цього компонента в кореневій конфігурації межі — тож ця форма потрапляє в поле зору політики лише тоді, коли вендорований модуль постачає власний такий файл, який шлях джерела копіює у вивід дослівно. Політика, написана з розрахунку на те, що компілятор його створить, ніколи не спрацює.
Коли вміст артефакту не розбирається, адаптер не пропускає його мовчки: він зберігає сирий вміст, не надає для цього артефакту розібраних документів і записує повідомлення парсера в input.artifacts[_].parse_error, тож політика може явно зупинити збірку на некоректному артефакті. Як і з рушієм Rego в компіляторі, політика, що викликає вбудовану функцію, якої вбудований обчислювач не реалізує, завершується гучною помилкою — збоєм із назвою плагіна, а ніколи не мовчазним дозволом.
Вивід Kubernetes — адаптер рендерингу Kubewarden
Адаптер рендерингу Kubewarden виконує політики допуску в стилі Kubewarden над
відрендереними маніфестами Kubernetes. Він поглинає всередину контракт admission-review
Kubernetes: політика Kubewarden отримує запит, що обгортає один об’єкт,
і повертає відповідь «прийняти або відхилити». На етапі рендерингу вивід збірки
вже є набором ресурсів Kubernetes, що робить цей етап природним
місцем для виконання політики у формі допуску. Для кожного відрендереного об’єкта адаптер
виводить поля допуску з самого розібраного об’єкта, обгортає об’єкт у
запит у формі admission-review всередині гостя, виконує політику і зіставляє
відповідь із вердиктом: відхилення стає одним вердиктом; прийняття не породжує
нічого. Еталонна політика в комплекті — правило обов’язкової мітки: кожен об’єкт має
мати ключ мітки, названий у settings, — поширений шаблон Kubewarden.
Спільна сфера застосування адаптерів етапу рендерингу
- Етап рендерингу, одна форма виводу на адаптер. Адаптер етапу рендерингу аналізує відрендерені артефакти, а не граф IR, і орієнтується на форму виводу, яку він розбирає: YAML/JSON і нативний HCL Terraform для еталонного адаптера рендерингу Rego, об’єкти Kubernetes для адаптера Kubewarden. Політика етапу графа або політика над формою виводу, яку не розбирає жоден постачений адаптер, — це інший гість.
- Лише валідація. Адаптер етапу рендерингу приймає або відхиляє; він ніколи не повертає змінений об’єкт. Змінений об’єкт мутувальної політики ігнорується — компілятор ніколи не переписує відрендерений вивід на підставі вердикту політики. Політика вирішує; вона не редагує.
Підключення політики
Оператор підключає плагін керування через список plugins.governance у
конфігурації робочого простору (.aggrega-config.yaml). Кожен запис називає плагін,
role, на якій його підключено, і, за потреби, канал with, що постачає його
правила й параметри налаштування:
plugins: governance: - uri: <resolvable-plugin-reference> role: ir-verdict with: sources: - ./policies/replicas.rego settings: max_replicas: 3uri вказує на плагін. Хост під час збирання читає кожен файл sources
і передає його байти гостю, а settings передає без змін. Збирання
без жодного підключеного плагіна керування виконує сокет як порожню операцію, тож підключення
лише доповнює робочий простір.
Плагін, що обслуговує кілька ролей, підключається окремо для кожної ролі, і кожне підключення має власні правила та власні налаштування:
plugins: governance: - uri: governance/rego:<version> role: label-transform with: sources: - ./policies/tagging.rego - uri: governance/rego:<version> role: ir-verdict with: sources: - ./policies/topology.rego settings: translation: - key: blocked severity: haltЯку версію називає приєднання. uri називає сутність Plugin — координату <pluginType>/<name> і, після двокрапки, версію, — і версія бере участь у розв’язанні. Для двох рушіїв, скомпільованих у CLI, сутність походить з одного з двох місць. Кожен випуск компілятора публікує сутності Plugin для governance/rego і governance/cel зі своєю версією, а каталог стандартної бібліотеки містить їх, кожну — з версією випуску, що її опублікував; робочий простір читає їх із каталогів, які він перелічує. Двійковий файл aggrega містить по одній сутності кожного рушія, з версією власного випуску й жодною іншою. Приєднання, що називає версію, якої немає ні там, ні там і яку жоден pull не завантажив до кешу вмісту, зупиняє збірку з E0137, називаючи посилання.
Тож приєднання називає версію, яку містить каталог, що його читає робочий простір. Така версія розв’язується з каталогу й за випуску aggrega, відмінного від її власного, тоді як версія, яку містить лише двійковий файл, — версія його власного випуску — розв’язується лише з цим випуском, як у ролі вердикту, так і в ролі перетворення. У ролі перетворення pull закріплює розв’язану версію у файлі блокування й відхиляє з E0103 версію, якої не містить ні каталог, що його читає робочий простір, ні двійковий файл. Версія вибирає сутність Plugin, яка фіксує експорти плагіна та обмеження часу виконання, а не рушій: щойно посилання розв’язано, виконується рушій, скомпільований у двійковий файл, що виконує збірку, бо вбудовані в двійковий файл плагіни — перше місце, звідки читається модуль плагіна. Плагін управління, який робочий простір оголошує сам, — сутність Plugin у власному каталозі з її .wasm поруч — називається з версією, яку фіксує ця сутність.
Кожна роль обирає типову вхідну функцію — verdict_ir для ролі, що оцінює
граф, verdict_render для ролі, що оцінює відрендерені артефакти,
mutate для ролі, що формує мітки, transform_annotations для
ролі, що додає анотації, — а підключення може спрямувати роль на інший експорт
за допомогою function:. Хост відмовляє у виклику експорту, який гість не оголосив
у своєму самозвіті describe(), тож про підключення, що називає роль, якої гість не
обслуговує, повідомляється за назвою ще до запуску гостя, а не мовчки нічого не відбувається.
function: називає експорт плагіна, який називає uri. Підключення в ролі вердикту — ir-verdict або render-verdict, — що називає function:, але не uri:, називає функцію, яка не належить жодному плагіну, тож конфігурація відхиляється вже під час читання з кодом E0224 із зазначенням файлу та місця запису в його списку: додайте uri плагіна, який експортує цю функцію.
Список plugins.governance має доповнювальний супутній список, plugins.governance_append:
записи супутнього списку приєднуються до розв’язаного списку governance на кожному
рівні конфігурації, тож конфігурація робочого простору чи глобальна конфігурація складає підключення
політик, а не затіняє базовий список.
Накладка, якою володіє CI
Поруч із написаним вручну .aggrega-config.yaml автоматизований конвеєр може володіти
окремим файлом накладки, .aggrega-config-append-ci.yaml. Він існує для того, щоб конвеєр
міг підключати політики (або іншу конфігурацію зі списковими значеннями), якими керує, ніколи не
редагуючи написану розробником вручну базову конфігурацію, — конвеєр може повністю перезаписувати
власний файл накладки.
Накладка суто доповнювальна. Вона перевіряється за тією самою схемою
конфігурації, що й базовий файл, і для кожного поля зі списковим значенням її записи
приєднуються до розв’язаного списку. Вона може лише додавати: вона не може вилучити базовий
запис і не може перевизначити скалярне базове значення — скалярний ключ чи ключ відображення, який вона містить,
не має доповнювального сенсу й ігнорується (і називається в попередженні розв’язання),
а не застосовується. І вона ніколи не закріплює корінь робочого простору: це робить лише
.aggrega-config.yaml із блоком workspace:, тож додавання
накладки до каталогу додає підключення, не змінюючи місця, де починається
робочий простір.
Це дає конвеєру чисту точку стику для застосування політики всієї організації:
конвеєр додає .aggrega-config-append-ci.yaml, що називає обов’язкові плагіни
політик, і ці підключення зливаються поверх того, що написав розробник,
ніколи не замінюючи його.
# .aggrega-config-append-ci.yaml — owned by the pipeline, additive onlyplugins: governance_append: - uri: <organization-policy-plugin-reference> role: render-verdict with: settings: required_label: app.kubernetes.io/nameexamples/policy-org-overlay/ збирає один робочий простір із приєднанням команди, приєднанням організації, доданим через governance_append глобального файлу конфігурації, і приєднанням конвеєра, доданим через цей оверлей, і перевіряє, що виводить кожна комбінація та чи завершується вона.
Тестування політики, перш ніж вона почне контролювати збірку
Правило Rego, що називає шлях, якого немає в корисному навантаженні його ролі, не є помилкою: шлях невизначений, правило ніколи не виконується, і збірка завершується так, ніби політика її дозволила. Тому нова політика заслуговує на halt за три кроки: приєднайте її з рівнем серйозності, що повідомляє без зупинки, звірте кожен названий нею шлях із корисним навантаженням, яке отримує її роль, і прочитайте, що вона повідомляє на збірках, які оцінюватиме.
Наведені нижче команди виконуються в копії examples/policy-org-overlay/, чий .aggrega-config.yaml приєднує одну нову політику замість політики команди. Вона має відхиляти сховище даних, що працює з вимкненою високою доступністю, а її правило скопійовано з політики формування міток:
package datastores
import rego.v1
deny contains msg if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v is a datastore running with high availability off", [id])}Приєднайте її так, щоб вона повідомляла. Політика збирає рішення під deny, що за замовчуванням зупиняє збірку. translation, що називає лише deny на рівні warn, повідомляє про кожне її рішення як про попередження й дає збірці завершитися; info натомість записує їх. Сама політика залишається такою, якою її буде застосовано:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policies/datastore-ha.rego settings: translation: - key: deny severity: warnЗапишіть корисне навантаження й знайдіть у ньому шляхи. Щойно збірка заповнила файл блокування сутності Release,
aggrega build --release release.yaml --dry-run --policy-input payloadsзаписує корисне навантаження, яке кожна роль передає своїм приєднанням, у payloads/ і більше нічого, повідомляючи таке (<workspace> позначає каталог, у якому виконувалася збірка):
policy input: 4 file(s) written to <workspace>/payloads[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]Ці чотири файли — annotation-transform.json, ir-verdict.json, label-transform.json і render-verdict.json; роль, до якої нічого не приєднано, теж записується, тож політику можна перевірити щодо її ролі ще до того, як її десь приєднано. В ir-verdict, label-transform і annotation-transform файл є документом input, який читає політика, тож кожен шлях, названий правилом, можна прочитати з нього будь-яким інструментом JSON, перш ніж довіряти правилу:
jq '.graph.nodes' payloads/ir-verdict.json# nulljq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json# ["db","web"]jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json# {"enabled":false,"read_replicas":0}Вузлів правила там немає: input.graph.nodes — це місце, де їх передає роль формування міток, а в ir-verdict вони розташовані за input.graph.spec.nodes (див. Що надає корисне навантаження кожної ролі). Файл також показує, що має вирішити виправлене правило: db — сховище даних, його висока доступність вимкнена, і про нього слід повідомити.
Якщо встановлено OPA, політика Rego обчислюється безпосередньо щодо того самого файлу: opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'. Рушій Rego в компіляторі — незалежна реалізація, тож вирішальним і далі є обчислення у збірці: вбудована функція, якої він не реалізує, зупиняє збірку, а не обчислюється.
В render-verdict файл не є input політики. Кожен артефакт у ньому містить свої path, content і format; documents, які читає правило, розбирає зі вмісту рушій політик, щойно отримує корисне навантаження, тож правило над documents нічого не знаходить у файлі. Політику в цій ролі тестують там, де рушій їх розбирає: у збірці, як показує наступний крок.
Виконайте збірку й порівняйте те, про що вона повідомляє, з тим, що каже корисне навантаження. Зі скопійованим шляхом
aggrega build --release release.yaml --auto-pullзавершується й ні про що не повідомляє:
Pull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0) notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: the build's time and the line naming the dist/ directory it wrote]Корисне навантаження містить сховище даних із вимкненою високою доступністю, а політика нічого про нього не сказала: ця мовчанка і є помилкою, і ніщо інше у збірці на неї не вказує. Коли правило читає input.graph.spec.nodes, та сама команда повідомляє про db і завершується:
policy plugin "rego" warning: db is a datastore running with high availability offPull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0) notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: the build's time and the line naming the dist/ directory it wrote]Додавання --dry-run повідомляє ті самі вердикти й не записує dist/, тож цикл виконується над робочим простором, не порушуючи його вивід.
Те саме правило, написане для рушія CEL, не завершується мовчки. Читання ключа, якого немає в корисному навантаженні, там є помилкою обчислення, тож зі скопійованим шляхом у policies/datastore-ha.cel, приєднаному з тим самим translation,
{ "deny": input.graph.nodes .filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore" && input.graph.spec.infra_mapping[n].ha.enabled == false) .map(n, n + " is a datastore running with high availability off"),}зупиняє збірку навіть на рівні warn. Вона завершується з кодом 1, а її останній рядок називає файл політики та ключ:
ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodesПолітику render-verdict тестують так само. Правило, приєднане в render-verdict у тому самому робочому просторі з тим самим translation, яке відхиляє сервіс Compose, що публікує порт на хості,
package published
import rego.v1
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services count(service.ports) > 0 msg := sprintf("%v publishes a port on the host", [name])}повідомляє про єдиний сервіс, який це робить:
policy plugin "rego" warning: web publishes a port on the host[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]Потім застосуйте її. Вилучення translation повертає deny до halt, і збірка, що повідомила про db, тепер зупиняється на ньому, завершується з кодом 1 і не записує dist/:
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: db is a datastore running with high availability off caused by: policy violationПриєднання, що лише повідомляє, не обов’язково вилучати всюди одразу. Один файл конфігурації може залишити translation свого приєднання на warn, тоді як оверлей конвеєра приєднує ту саму політику з deny на halt, — саме так examples/policy-org-overlay/ запроваджує правило організації: попередження у збірці розробника й причина, через яку зупиняється збірка конвеєра.
Запуск політик у CI над результатом збірки
Усе описане вище підключає політику всередині збірки. Є й другий шлях, якому від сокета нічого не потрібно: запустіть власний інструмент у конвеєрі над файлами, які записала збірка.
Це працює завдяки тому, що видає збірка. Цілі Kubernetes і Compose записують YAML; ціль Terraform записує нативний HCL або JSON у формі .tf.json.
Саме ці формати вже читають інструменти конфігурації екосистеми, а
aggrega build записує звичайні файли в каталог, без формату-обгортки, без індексу і без потреби щось розпаковувати. Тож інструмент, що читає YAML, JSON або HCL, працює над результатом збірки так само, як над конфігурацією, написаною людиною вручну, і Aggrega не потребує для цього ні сокета, ні виду плагіна, ні ключа конфігурації.
Тож наявний набір правил не потрібно переносити. Якщо ви вже зберігаєте правила в Conftest, Kyverno CLI, kubeconform, Checkov або OPA, ці правила працюють над результатом збірки Aggrega без змін, а інструмент, що їх обчислює, — той самий, який ваш конвеєр уже встановлює.
Два готові до використання скрипти з правилами, кожен із кроком конвеєра, що його викликає, і обома відмовами, які вони видали на реальних збірках, лежать у examples/policy-in-ci/. Вони використовують yq і нічого більше, тож працюють без встановленого інструментарію політик; показана ними схема — прочитати вихідний каталог, ухвалити рішення, завершитися з ненульовим кодом, назвавши проблемні артефакти, — це схема, якої набуває будь-який інструмент у цій позиції.
Якому шляху належить правило
Обидва шляхи повноцінні, і робочий простір зазвичай використовує обидва. Вирішує те, що правилу потрібно бачити і коли йому потрібно діяти.
Підключайте правило до сокета, коли:
- збірка взагалі не повинна створювати артефакт. Політика
ir-verdictвиконується на етапі статичного аналізу, до того як щось буде відрендерено, тож зупинка там не залишає нічого записаного — жодного вихідного файлу, який треба переглядати, ізолювати чи випадково застосувати. Перевірка в конвеєрі неминуче виконується після того, як файли вже існують. - правилу потрібні факти, які має лише збірка. Роль
ir-verdictчитає зібраний граф: вузли, ребра та їхні сокети, кожне підключення зі слотом, який воно заповнило, які значення автор оголосив чутливими, шляхи маршрутизації. Ніщо з цього не потрапляє у відрендерений результат — маніфест Kubernetes не фіксує, який сокет доставив значення чи яка сутність Feature додала ресурс, — тож правило про топологію чи походження має одне місце, і це сокет. - правило має діяти скрізь, де виконується збірка. Підключення governance міститься в конфігурації робочого простору, тож воно застосовується до локальної збірки розробника так само, як і до збірки в конвеєрі. Перевірка в конвеєрі діє там, де працює конвеєр.
- правило має формувати збірку, а не оцінювати її. Це робить лише роль трансформації, і лише тому, що її підключив оператор.
Запускайте правило в CI, коли:
- правило вже існує в інструменті, який ваша команда запускає й переглядає, над форматом, який цей інструмент уже розбирає. Переписування його як вмісту політики сокета — це робота, яка зрештою не дає нового покриття.
- правило стосується артефактів у тому вигляді, в якому їх отримає ціль — остаточного
набору файлів після всіх трансформацій, у формі, що застосовується. Це також
предмет ролі
render-verdict, тож лише в цьому пункті обидва шляхи бачать одне й те саме, і вибір залежить від інших пунктів. - результат перевірки призначений для рецензента, а не для збірки. Конвеєр, який публікує артефакти та результати перевірки поруч, дає рецензентові і те, і інше; зупинена збірка дає йому лише повідомлення.
- перевірка виходить за межі однієї збірки — порівнює результат цієї збірки з попередньою, з живим станом кластера чи з інвентарем, якого не містить жодне корисне навантаження збірки. Політика в будь-якій із ролей вердикту бачить збірку, до якої вона підключена, і більше нічого.
Шляхи доповнюють, а не конкурують: інваріант топології зупиняє збірку з
ir-verdict, а той самий конвеєр потім запускає наявні правила артефактів інфраструктури над тим, що записала ця збірка.
Перехресні посилання
plugin-contract.md— місце сокета в конвеєрі, типізовані форми даних, які він передає, і пісочниця, у якій виконується кожен плагін.plugin-developer-guide.md— створення плагіна, самоописdescribe()і життєвий цикл публікація → отримання → збирання.../entities/plugin.md— сутністьPlugin, яка вносить плагін до каталогу.../cli/aggrega-build.md— команда збирання, яка викликає сокет.../schema/other/aggrega-config.md— схема конфігурації робочого простору, зокрема поверхня підключенняplugins.governance.../examples/policy-in-ci/— два готові до запуску скрипти правил над результатом збирання, кожен із кроком конвеєра для нього.../examples/policy-data-class-route/— одне правилоir-verdictнад маршрутами, написане для рушія Rego, рушія CEL та OPA за еталонним гостьовим адаптером, що підключається для кожного збирання окремим файлом--configдля кожного рушія, зі скриптом, який перевіряє, що всі три дають однаковий результат для кожної сутності Release.