Сокет управления
Сокет целиком, а не одна его роль: четыре роли — две, которые оценивают сборку, и две, которые её формируют, — оба движка политик, поставляемых в компиляторе, и то, как оператор подключает плагин.
Оператор подключает 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 этого движка внутри себя. Если у движка есть собственный ABI для Wasm, собственные точки входа или собственный протокол обратных вызовов хоста, оборачивающий гостевой модуль создаёт экземпляр движка и управляет им внутри себя, а решение движка отображает обратно на структуру вердикта сокета. Хост компилятора видит только стандартный интерфейс вердиктов управления; он никогда не узнаёт, какой движок задействован, и не содержит кода, специфичного для движка. Перевод политики с одного движка на другой — это изменение подключения, а не изменение хоста.
В компилятор встроены два движка политик
В бинарный файл 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 в компиляторе — простой путь. Он содержит
вычислитель Rego, нативный для Wasm, поэтому оператору достаточно положить файл .rego в sources и
подключить плагин — без внешнего инструментария и без загрузки чего-либо во время сборки. Он
обслуживает все четыре роли: один и тот же плагин оценивает граф сборки, оценивает отрисованный
результат, формирует метки или внедряет аннотации — в зависимости от роли, к которой он
подключён. Его идентификатор в каталоге — просто имя rego при pluginType: governance,
то есть координата governance/rego, а его версия — это выпуск компилятора, в котором он
поставляется. Написанию политики для него посвящён
следующий раздел.
Вычислитель независимо реализует Rego, а не встраивает эталонную
реализацию, и реализует не все встроенные функции Rego. Если политика вызывает
встроенную функцию, которую вычислитель не реализует, подключение завершается явной ошибкой: оно
возвращает сбой, а не разрешение. Затем сборка останавливается со сбоем, в котором указан
плагин, — намеренно отличным от вердикта halt, чтобы «движок не может
вычислить эту политику» никогда не принималось за «политика разрешает сборку». Политика,
которую невозможно вычислить, останавливает сборку и никогда не проходит молча.
Запасной выход opa build -t wasm — полнофункциональный путь. Если
политике нужен полный набор встроенных функций или точная семантика эталонного движка,
скомпилируйте её собственным инструментарием OPA в модуль Wasm и запускайте этот модуль за
тонким гостевым адаптером. Адаптер полностью инкапсулирует ABI Wasm от OPA внутри себя
(см. ABI принадлежит самому Aggrega выше): он
создаёт экземпляр собранного OPA модуля, задаёт входные данные, запускает вычисление и отображает
решение обратно в форму вердикта. Хост видит только стандартный
интерфейс вердиктов управления.
В качестве рабочего примера поставляется эталонный гостевой адаптер. Он встраивает политику, написанную на Rego и заранее скомпилированную с помощью opa build -t wasm в модуль WebAssembly, — зафиксированный артефакт, хранящийся в репозитории, поэтому вычисление целиком выполняется в госте без процесса OPA и без загрузок. При каждой сборке адаптер создаёт экземпляр этого встроенного модуля внутри себя с помощью встроенного интерпретатора Wasm, удовлетворяет собственные импорты модуля (его линейную память и обратные вызовы встроенных функций), читает полезную нагрузку как документ 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 с ключами по идентификатору узла, рёбра в 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 — узлы сборки с ключами по идентификатору узла, каждый с 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.
Объект узла не содержит собственного идентификатора: идентификатор — это ключ, под которым он находится в input.graph.spec.nodes, поэтому правило выше переносит в своё сообщение идентификаторы, прочитанные из 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, …]) и индексирует маршрут по каждой из них, поэтому оно должно отсечь маршрут, более длинный, чем сам список, остановкой на нём, а не читать его частично. - Ключ решения собирает сообщения, а не их списки. Выражение, выдающее один список сообщений на маршрут, отклоняется под ключом решения (ошибка сообщает, что он собрал значение типа список, а не сообщение), поэтому правило выдаёт одну запись на маршрут и строит из неё сообщение. А сообщение, которое выражение выдаёт дважды, сообщается дважды: описанная ниже сортировка упорядочивает то, что собрал ключ, и не удаляет повторы.
../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. Полезная нагрузка рендеринга содержит сгенерированные артефакты — каждый с его выходным путём и отрендеренным содержимым, а там, где это применимо, с форматом, в котором он был отрендерен, и его разобранным структурированным представлением, — а также собственные источники и настройки подключения, каждое — если подключение его объявляет. Адаптер читает это содержимое для целевой формы вывода, вычисляет политику над структурированным результатом и сопоставляет итог с вердиктами halt / warn / info. Поскольку полезная нагрузка сама не называет никакой формы вывода, один шаблон адаптера подходит для любой цели рендеринга; новая форма вывода — это новый адаптер, а не изменение хоста.
Каждый адаптер стадии рендеринга является адаптером в описанном выше смысле: наружу он говорит на 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, а также над выводом Terraform в нативном HCL. Это рабочий пример формы стадии рендеринга: тот же нативный для 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 отклоняет любой сервис, образ которого не содержит префикса реестра.
Адаптер также рассуждает о выводе рендеринга Terraform в нативном HCL. Нативный файл .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.