Управление и соответствие требованиям
В этой главе определяется, как команды платформы обеспечивают корпоративное соответствие требованиям в каждой сборке — через сокет управления, базовые линии и схемы каталога и соглашения, которым следуют авторы каталога, — не зашивая политику в компилятор. Событиям жизненного цикла Day-2 посвящена глава Жизненные циклы Day-2.
Шаблоны корпоративного управления и соответствия требованиям
Ключевая задача платформенной инженерии — обеспечить корпоративное управление (например, соответствие SOC 2, отслеживание центров затрат FinOps и строгое сопоставление ответственности), не засоряя каталог с открытым исходным кодом.
Если бы Aggrega жёстко встроил предметно-специфическую логику в свои официальные компоненты, он перестал бы быть компилятором без собственного мнения и выродился бы в фреймворк, навязывающий собственное мнение. И наоборот, если соответствие требованиям целиком оставить разработчику, критически важные теги будут написаны с ошибками, забыты или обойдены.
Чтобы решить эту задачу, Aggrega предоставляет механизмы сокетов Wasm для соответствия требованиям, а предприятие определяет политику. Предприятия достигают управления по принципу нулевого доверия, принимая в своей экосистеме два отдельных общественных договора.
1. «Bring Your Own Baseline» (BYOB) + шлюз валидации Wasm
Для статических данных, предоставляемых разработчиком (например, команды-владельца или классификации данных), предприятиям никогда не следует полагаться непосредственно на сырой каталог с открытым исходным кодом. Вместо этого архитектор платформы пишет корпоративную базовую линию — поля, которые должен нести каждый внутренний компонент, объявленные один раз в записи SchemaLibrary, — и использует роль вердикта управления, чтобы принудить к её использованию.
Контракт каталога: Предприятие создаёт базовую линию, которая требует определённых тегов, но не создаёт никакой инфраструктуры.
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: CorporateBaseline version: 1.0.0spec: schemas: Ownership: type: object properties: owner: { type: string } cost_center: { type: string } # The developer MUST provide these, or the schema validator halts the build required: [owner, cost_center]Каждый внутренний компонент (например, acme/datastore/postgres) ссылается на эту запись из собственного schema: и добавляет собственные значения, так что общие поля и собственные поля компонента валидируются вместе:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: acme/datastore/postgres version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: schema: values: $ref: "CorporateBaseline#/schemas/Ownership" properties: database: { type: string } required: [database]Базовая линия — это запись библиотеки, а не базовая сущность Component, потому что сущность Component, которая пишет extends:, получает schema: своей базы целиком и не объявляет собственных значений (см. Наследование и дисциплина публикации).
Предохранитель валидации Wasm: Чтобы разработчик не мог обойти внутренний каталог и взять голый компонент core/postgres напрямую из публичного хаба, предприятие регистрирует плагин топологической валидации. Он вычисляется во время статического анализа — после сборки графа и до рендеринга любого артефакта, — поэтому он видит всю топологию, а не по одному компоненту за раз.
# Evaluated by the governance ir-verdict role over the assembled graphpackage acme.governance
import rego.v1
deny contains msg if { some id, _ in input.graph.spec.nodes not input.graph.spec.values_mapping[id].owner msg := sprintf("node %v declares no owner; use a component whose schema references 'CorporateBaseline#/schemas/Ownership'.", [id])}Решение, которое политика собирает под своим ключом запрета, является отклонением, и сборка на нём останавливается.
Запрет произвольных соединений: Разработчик может провести ребро через сокет, который каталог не объявлял, — ad hoc сокет (см. dependency-resolution). Эта открытость намеренна, как и то, что у компилятора нет на этот счёт никакого мнения: организация, которая хочет, чтобы каждое соединение проходило через сокет, объявленный её архитекторами, выражает это как политику, а не полагается на компилятор. Каждое ребро графа несёт socket_declaration со значением declared или ad-hoc, так что правило занимает одну строку:
# Evaluated by the governance ir-verdict role over the assembled graphpackage acme.governance
import rego.v1
deny contains msg if { some e in input.graph.spec.edges e.socket_declaration == "ad-hoc" msg := sprintf("%v connects to %v through the free-form socket %v; declare the socket in the component type's usesSchema.", [e.source, e.target, e.socket])}Значение всегда присутствует на каждом ребре, каким бы способом ребро ни было написано, поэтому политике никогда не приходится читать отсутствующее поле как «declared». И это отдельная ось: она говорит, откуда взялся сокет, а не кто провёл ребро, поэтому она сочетается с origin_feature и origin_release, а не пересекается с ними, — политика может запретить произвольные соединения и при этом разрешить сущности Release соединять объявленные.
Централизованное корпоративное управление (оценка полной реальности): внеполосные механизмы (например, CODEOWNERS в git-репозитории) проверяют изменяемые файлы, а не архитектуру, в которую они компилируются. Роли вердикта управления оценивают саму архитектуру. Поскольку AOT-компилятор строит граф IR, сплющивая как Aggregate разработчика, так и Release оператора платформы, политика в роли ir-verdict оценивает полную реальность до того, как будут сгенерированы физические артефакты, а политика в роли render-verdict оценивает сами артефакты. Политики могут фатально остановить сборку, если разработчик запрашивает неутверждённую сущность Component или — читая происхождение aggrega.ai/recipe-uri, проставленное на каждом отрендеренном объекте, — если сущность Manifest сопоставляет компонент с неутверждённой сущностью Recipe.
2. Мутирующий шлюз Wasm (динамическое соответствие требованиям)
Разработчиков не следует заставлять вручную вписывать теги соответствия окружению (например, environment: production или soc2_in_scope: true) в свой Aggregate, поскольку они меняются в зависимости от цели GitOps.
Для динамических метаданных предприятия используют Mutation Gate — роль label-transform сокета управления, которая выполняется во время построения топологии. После раскрытия графа и до того, как статический анализ его оценит, компилятор выполняет плагин Wasm, присоединённый предприятием. Этот плагин читает окружение сущности Release, метки, которые узлы уже объявляют, и значения, объявленные экземпляром каждого узла, и называет метки, которые должны нести узлы сборки, — так нужные метаданные попадают в компонент без того, чтобы разработчик их вписывал (например, метка compliance.aggrega.ai/data-class: restricted, определённая по окружению сущности Release, или datastore.aggrega.ai/engine: vector, определённая по объявленным расширениям базы данных). Значения доступны только для чтения: плагин решает только метки и ничего больше.
Политика в этой роли называет метку — узел, ключ и принимаемое значение, — а не пишет инструкцию редактирования, которую применяет сборка. Причина важна для каждого, кто пишет такую политику: инструкция адресует метку путём, а ключ метки Aggrega обычно содержит /, который является разделителем пути, поэтому написанный вручную путь адресовал бы вложенное расположение вместо одной метки. Сборка адресует метку, которую называет решение, а проекция узлов, которую получает эта роль, располагает их на один уровень менее глубоко, чем вердикт по всему графу.
# Evaluated by the governance label-transform role, during topology constructionpackage acme.tagging
import rego.v1
labels contains {"node": id, "key": "acme.com/soc2-scope", "value": "true"} if { input.compilation_context.environment == "production" some id, node in input.graph.nodes node.labels["component.aggrega.ai/type"] == "stateful-server"}Поскольку эти теги внедряются в памяти в стандартный словарь метаданных до начала рендеринга, плагины рендеринга Wasm могут читать их, чтобы условно генерировать определённые физические конфигурации — например, усиленные ресурсы AWS или Kubernetes — по мере рендеринга артефактов.
Правило формулируется один раз: присоединения управления действуют в области рабочего пространства. Два приведённых выше шаблона пишутся для каждого компонента и каждой сущности Feature, но присоединение управления, которое их обеспечивает, — нет. Плагин управления присоединяется к ключу plugins.governance конфигурации рабочего пространства, и это присоединение связывает каждую сборку в рабочем пространстве. Поэтому корпоративное правило формулируется ровно в одном месте: платформенная команда присоединяет плагин один раз, и ни один компонент, сущность Aggregate или Release не обязаны подключаться к нему, упоминать его или изменяться, чтобы оно действовало. Именно это делает предохранитель валидации из шаблона 1 полным ответом, а не соглашением отдельного проекта, — разработчик, который обходит внутренний каталог и запрашивает голый core/postgres, оценивается той же присоединённой политикой, что и все остальные, потому что политика является свойством рабочего пространства, а не выбранного им компонента.
Правило рабочего пространства отклоняет; оно не переписывает контракт разработчика. Область действия универсальна, а эффект намеренно ограничен вердиктом. Правило, действующее везде, останавливает нарушающую его сборку, называя, что нужно исправить, и не может вместо этого изменить компонент-нарушитель, чтобы привести его в соответствие. Эта граница и сохраняет механизм пригодным для отладки в масштабе всей инфраструктуры: сборка либо соответствует правилам, которые объявляет рабочее пространство, либо останавливается с сообщением, указывающим на написанную строку, а отрендеренный вывод никогда не содержит ограничения или ресурса, которых не запрашивал ни один написанный файл. Там, где предприятие действительно хочет, чтобы граф изменили, а не оценили, оно присоединяет роль преобразования — шаблон 2 выше, — и это изменение ограничено тем, для чего оператор её присоединил, поэтому оно является явным действием платформенной команды, а не невидимым переписыванием.
Практическое следствие для платформенной команды, замыкающей круг соответствия требованиям: форму, которую должна иметь полезная нагрузка, следует выражать как ограничения схемы на корпоративной базовой линии, межсущностные правила, которых требует инфраструктура, — как присоединённую роль вердикта, а производные метаданные, которые разработчик никогда не должен вписывать, — как присоединённую роль преобразования. Все три объявляются один раз и применяются к каждой сборке, и ни одно из них не требует, чтобы разработчик знал об их существовании.
3. Сохранение предметных знаний (конфигурации и безопасность)
Поскольку компилятор Aggrega без собственного мнения, он не обладает никакими жёстко закодированными знаниями о фреймворках ИИ, бюджетах токенов или разбиении памяти. Вместо этого общие cloud-native схемы служат пустым сосудом. Вместо того чтобы быть жёстко закодированными в ядре компилятора, узкоспециализированные предметные знания распределены по всей расширяемой экосистеме Aggrega. Они инкапсулированы в каталоге платформы через специализированные components, features и recipes. Разработчики сохраняют своё конкретное прикладное намерение в блоках values и uses — строго управляемых объявлениями schema: архитектора (компактная форма или полная JSON Schema 2020-12) и сокетами usesSchema, — тогда как физический перевод этих знаний выполняют плагины WebAssembly, специфичные для цели.
A. Моделирование предметно-специфических реализаций (валидируемых через разделённые схемы)
Архитекторы платформы могут использовать конвейер разделённых схем, чтобы моделировать любую сложную архитектуру полностью независимо от ядра компилятора:
- Непрозрачная логика выполнения (
values): Если предприятие развёртывает AI Gateway, разработчик настраивает собственное поведение шлюза — для ИИ-шлюза стандартной библиотеки это словарьmodels, публикующий каждый псевдоним, который может запросить вызывающая сторона, и upstream, в который разрешается каждый из них. Ядро компилятора не разбирает эти понятия. Они безопасно находятся в непрозрачной полезной нагрузкеvalues, строго валидируемой объявлениемschema:компонента. Компилятор просто передаёт эту нагрузку плагину Wasm, чтобы сгенерировать конфигурацию шлюза. Средства управления, общие для нескольких шлюзовых продуктов, например цепочка резервных вариантов, число повторных попыток или выбор между записями, публикующими один и тот же псевдоним, — это сущности Features, присоединённые к шлюзу, а не значения на нём, и каждая реализуется для шлюза в собственных терминах этого шлюза. - Отображение топологических зависимостей (
uses): Когда фреймворк ИИ связывает агента с его инструментами или с векторным хранилищем данных, эта связь определяет, кто с кем общается, поэтому она объявляется в опореuses; список имён, хранящийся вvalues, напримерtools_allowedиз стандартной библиотеки, — это соглашение, которое не проводит ребра. Компилятор дословно проводит эти явные рёбра в графе IR. Это позволяет нижестоящим плагинам рендеринга Wasm программно генерировать сетевые политики и физические границы, необходимые для защиты соединений, без того чтобы компилятор понимал лежащий в основе фреймворк ИИ. - Сложные структуры данных (например, CoALA): Вместо того чтобы ограничиваться одним плоским списком целей, архитекторы объявляют в
usesSchemaстолько сокетов, сколько нужно структуре, каждый со своим селектором и своейvalueSchemaдля каждого ребра. Например, чтобы реализовать фреймворк CoALA, архитектор может объявитьsemantic_memory,episodic_memoryиworking_memoryкак отдельные сокеты, так что каждое хранилище памяти становится отдельной топологической целью. Общие движки политик оценивают эти структурированные рёбра, чтобы сделать обязательными детальные ограничители контроля доступа для каждой отдельной когнитивной доли.
B. Базовые механизмы безопасности и косвенности
Хотя полезная нагрузка остаётся без собственного мнения, общая схема обеспечивает строгие структурные механизмы, которые поддерживают безопасную генерацию артефактов:
- Шаблон «присоединение, а не значение»: соглашение стандартной библиотеки состоит в том, что учётные данные запрашиваются как присоединение и никогда не записываются в блок
values, где они были бы встроенным литералом, который компилятор переносит дословно. Присоединение учётных данных называетtypeсущности Feature учётных данных (помеченной меткойfeature.aggrega.ai/kind: secret) и использует собственныеvalues, чтобы описать запрос к хранилищу секретов. Маршрутизация учётных данных тогда является поздним связыванием, не зависящим от возможностей, и ядро компилятора никогда не разрешает и не раскрывает сам материал — оно передаёт указатель, который предоставила сущность Recipe от Ops. Это соглашение, которое поощряют каталог и схемы, а не проверка компилятора: компилятор не интерпретирует, что означает листvalues, поэтому автор, который встраивает материал, его и встраивает. То, что схема действительно гарантирует, — это существование и типизированность поверхности присоединений. - Абстрактная проверка доверия: Поскольку блок
valuesшироко расширяем, архитекторы могут сделать обязательными абстрактные директивы, напримерtls_pinningилиrequired_signatures: 2(для консенсуса кворума). Ядро компилятора дословно передаёт эти валидированные схемой объекты в плоский граф IR. Собственный плагин рендеринга Wasm может затем прочитать эти значения, чтобы сгенерировать артефакты для аппаратных шлюзов утверждения Human-in-the-Loop (HITL). Если приложение пытается обойти правила консенсуса, физически развёрнутый прокси блокирует выполнение, пока не получит утверждение через вебхук.
C. Расширенная эксплуатационная безопасность (spec.interoperability)
Чтобы защитить уязвимые рабочие нагрузки от конфликтующих мутаций инфраструктуры, общая схема Feature определяет средство управления совместимостью:
spec.interoperability.conflictsWith— список сущностей Features, которые не могут попасть в тот же компонент, что и эта. Компилятор останавливает сборку перед рендерингом, когда присоединения, с которыми в итоге оказывается компонент, — собранные из каждой области, которая его достигает: самого компонента, содержащей его подсистемы или границы, его записи компонента в сущности Release и раскрытия, управляемого аннотациями, — содержат эту сущность Feature и одну из тех, которые она называет. Это сравнение имён, объявленных автором сущности Feature, с сущностями Features, которые несёт компонент, без вкладывания какого-либо смысла в те или другие: несовместимость — это суждение автора, а компилятор удерживает сборку в его рамках. Достаточно одного объявления, имена сопоставляются независимо от их версий, а две сущности Features, присоединённые к соседним границам без общего компонента, никогда не встречаются.
4. Управление сетевыми границами (соглашение о запрете по умолчанию)
Разработчики не пишут сетевые политики напрямую; необходимые сетевые границы отображаются графом промежуточного представления (IR) компилятора, который содержит каждое топологическое ребро между компонентами, объявленными в сущности Aggregate.
- Внутренние границы. Компилятор строит плоский граф IR и сам ничего не ограничивает: без политики каждое соединение, которое разрешает сеть кластера, остаётся достижимым. Соглашение состоит в том, что политика, написанная для компонента, разрешает соединение только там, где сущность Aggregate объявляет для него ребро, помимо того, что называет собственное присоединение политики, и запрещает любое другое соединение в направлении, которым управляет политика.
- Реализация в стандартной библиотеке. Каталог стандартной библиотеки реализует это соглашение в виде двух сущностей Features, которые оператор присоединяет к компоненту в сущности Release, по одной для каждого направления соединения:
core/caller-allowlistдопускает соединения только от компонентов, чьи рёбраusesуказывают на него, аcore/egress-allowlistпозволяет компоненту соединяться только с компонентами, на которые указывают его собственные рёбра, и с DNS кластера. На цели helm каждая из них реализуется сущностью FeatureRecipe, которая записывает Kubernetes NetworkPolicy по рёбрам, переданным ей компилятором, определяя поды каждого компонента по тому, что вывел собственный рендеринг этого компонента, — селекторам и меткам, которые несут его рабочие нагрузки, пространству имён, в которое они выводятся, и портам, которые объявляют их контейнеры, — так что ни одна метка и ни один порт не повторяются вручную. Каждая также допускает собственные поды компонента и то, что сущность Release называет в присоединении: источники вне сущности Aggregate на входящей стороне, а на исходящей — диапазоны адресов для цели, которую кластер не запускает, которая не рендерит подов для выбора и допускается только по диапазону, на любом порту. Компилятор не может проверить кластер, поэтому каждая из них останавливает сборку, пока сущность Release не подтвердит, что сетевой плагин кластера применяет сетевые политики; у compose нет сетевых политик, и сборка, присоединяющая там любую из них, останавливается. - Публичный ingress (агностичный контроль периметра). Публичный ingress регулируется собственными правилами предприятия в роли вердикта управления. Корпоративная команда безопасности может написать политику, которая оценивает тип онтологии cloud-native узла и отклоняет сборку, если разработчик пытается присоединить функцию
public-ingressк узлуworkerилиtask. Компилятор не интерпретирует, что означает «публичный»; он применяет булев результат шлюза валидации Wasm.
5. Штамп происхождения на этапе компиляции
Во время компиляции компилятор формирует запись о происхождении, фиксирующую версию компилятора и версии скомпилированных им сущностей Aggregate, Manifest и Release, — и никакой метки времени, так что запись никогда не нарушает побайтно идентичный вывод. Рендерер helm выводит версию компилятора в виде метки aggrega.ai/compiler-version на сгенерированных манифестах Kubernetes, а рендерер helm-chart — в файлах шаблонов, которые сущность Recipe добавляет в чарт, поскольку собственные шаблоны чарта он копирует без изменений; корпоративные команды безопасности используют её, чтобы определить, какие отрендеренные артефакты были собраны какой версией компилятора, — это важно, когда в конкретном выпуске компилятора обнаружена уязвимость и затронутые артефакты нужно проверить.
Провайдер compose проставляет те же ключи происхождения как метки сервисов, провайдер terraform — как файл происхождения в каждом собираемом им модуле, а провайдер cloudformation — в Metadata каждого ресурса; запись о происхождении в памяти существует для каждой компиляции.
6. Метаданные и аннотации как поверхность расширения
Компилятор Go агностичен по отношению к предметно-специфическим концепциям — фреймворкам ИИ, движкам баз данных, идиомам Kubernetes — и работает только с плоскими операциями уровня графа над IR. Чтобы управлять экосистемой, не зашивая предметно-специфическую логику в двоичный файл Go, платформа использует стандартные метки и аннотации метаданных как поверхность расширения для предметных знаний.
Компилятор не читает никаких предметно-специфических аннотаций. Он собирает все предоставленные разработчиками аннотации и метки утиной типизации в плоский граф IR и передаёт эти метаданные дословно плагинам управления и рендеринга. Экосистема WebAssembly интерпретирует метаданные и выполняет нужную логику — оценивает политики соответствия, внедряет теги в cloud-native артефакты или запускает развёртывание функций — независимо от ядра компилятора.
Это сохраняет поверхность расширяемости широкой (любой может написать плагин Wasm, читающий новый префикс аннотаций) и при этом сохраняет ядро компилятора стабильным: чтобы экосистема добавила новую предметно-специфическую аннотацию, не требуется никакого выпуска ядра.
Что политика читает о присоединении
Роль вердикта, оценивающая граф IR, получает граф целиком — с удержанием каждого значения, которое автор объявил чувствительным, как описано ниже, — и это включает каждое присоединение, которое несёт каждый узел, с ключом по имени, которое дал ему автор, — или, для присоединения, записанного на одном из соединений узла, по псевдониму соединения и слоту, соединённым точкой. Смысл передавать детали присоединений, а не сводку, в том, что у Aggrega нет мнения, которое можно было бы свести: компилятор маршрутизирует присоединения, не оценивая их содержимое, поэтому факты, нужные политике для их оценки, — это те факты, которые политика получает.
Для каждого присоединения граф содержит:
- Тип Feature, который оно запрашивает, и версию каталога, разрешённую для него. Тип — это строка, которую написал автор, дословно — ссылка с закреплённой версией и ссылка без неё являются разными строками для одного объекта, поэтому политика, сравнивающая типы, должна ожидать любое из написаний.
- Метки каталога присоединённой сущности Feature, дословно. Без фильтрации, без нормализации, в порядке, в котором их объявляет сущность каталога. Политика читает ровно то, что написал автор каталога, включая метки собственного изобретения автора, о которых Aggrega ничего не знает.
- Аннотации каталога присоединённой сущности Feature, дословно. Собственные
metadata.annotationsсущности Feature, передаваемые точно на тех же условиях, что и её метки, — без фильтрации, без нормализации, в объявленном сущностью порядке, — так что ключ аннотации в собственном пространстве имён автора приходит в том виде, в каком он написан. Это иной предмет, нежели аннотация, из-за которой вообще появилось присоединение, развёрнутое из аннотации: граф сообщает об этом происхождении отдельно, а присоединение, записанное в блокеfeatures:, несёт аннотации сущности, вообще не сообщая о происхождении из развёртывания. - Какой объявленный слот присоединения оно заполняет. Слот
featuresSchemaзаполняется присоединением сущности Feature под именем слота, поэтому присоединение, называющее слот, объявленный его сущностью Component, сообщает имя этого слота, а то, которое не заполняет ни одного, сообщаетfree. Присоединение, записанное на соединении, заполняет слот, который объявляет сокет соединения, и сообщает имя этого слота; поскольку сокет не допускает иного имени, оно никогда не сообщаетfree. Значением является имя слота, а не флаг, потому что то, какая точка привязки заполнена, обычно является более полезной половиной ответа. - На каком соединении оно записано, если на каком-либо. Присоединение, записанное на одном из соединений компонента, несёт сокет и псевдоним этого соединения, которые называют ребро графа, на котором оно предъявляется, — а через это ребро и компонент, которому оно предъявляется. Присоединение из собственного блока компонента не несёт ни того, ни другого. Соединение передаётся как данные, а не оставляется для извлечения из имени присоединения, которое содержит псевдоним, а не сокет.
- Обрабатывает ли оно материал, который автор объявил чувствительным, и какие из его ключей доставки несут этот материал. И то и другое выводится из объявлений — листа
sensitiveв схеме сущности Feature, слотаsensitiveв потребляющей сущности Component, будь то слот, который она объявляет для собственных присоединений, или слот на сокете, через который подключено соединение, — и никогда из проверки значения. - Его
values, егоinfraи его сопоставление доставки, а также то, записано ли присоединение в блокеfeatures:или добавлено развёртыванием на основе аннотаций, — с удержанием каждого значения, которое автор объявил чувствительным, как описывает следующий абзац.
Политике сообщают, где находится материал, объявленный чувствительным, но сам материал ей никогда не передают. Каждый лист, который граф помечает как объявленный чувствительным, — в values или infra любого присоединения, в какой бы области или на каком бы соединении оно ни было записано, в infra присоединения границы, в собственных values и infra узла и в собственных values и infra соединения — поступает в политику как маркер с одним ключом, {"aggrega_withheld": "declared"}, вместо значения. Ключ сохраняется, поэтому политика по-прежнему видит, какие листья несёт полезная нагрузка; пометка, называющая эти листья, сохраняется, поэтому политика по-прежнему видит, какие из них несут объявленный материал; и каждый перечисленный выше факт поступает, как и прежде, вместе с каждым значением, которое не помечено ни одним объявлением. Ни один из фактов, на которых строятся рассуждения политики, — что представляет собой присоединение, что оно заполняет, кому оно предъявляется, что о нём говорит его сущность каталога и куда перемещается его секретный материал, — не является значением, которое автор может объявить чувствительным, а сам материал — единственное, что не нужно политике, чтобы оценить, куда он направляется. Это то же самое удержание, которое применяет командная строка, когда печатает граф, и демон, когда отвечает на запрос редактора о нём. Эти поверхности возвращают значения человеку, который явно о них просит; копия политики такого запроса не предлагает. Удержание применяется только к копии политики: граф, из которого выполняет рендеринг сборка, остаётся нетронутым, поэтому ни один отрендеренный байт не меняется.
Метки присоединения связывают компилятор ровно в одном месте, и это не решение политики: слот может объявить selector, и заполнение, метки которого ему не удовлетворяют, останавливает сборку. За пределами этой проверки метки ничем не управляют — то, как значение маршрутизируется и доставляется, одинаково, какие бы метки ни несла сущность Feature. Поэтому политика, читающая метку, читает метаданные, которые компилятор перенёс без интерпретации, а не оспаривает ветвление внутри него.
Аннотации каталога сущности Feature не связывают её ни в одном месте: никакое поведение компилятора не ветвится в зависимости от них, и слот не объявляет для них никаких ограничений, как он может это сделать для меток. Их переносят, и ничего более.
Правила, которые это позволяет записать и ни одно из которых компилятор не устанавливает за вас:
- Запрет свободного присоединения. Организация, требующая, чтобы каждое присоединение заполняло объявленную точку привязки, отклоняет любое присоединение, сообщающее
free. Это оборотная сторона того, что поверхность присоединения остаётся открытой: композиция по умолчанию свободна, и оператор, который не хочет, чтобы она была свободной, так и заявляет. - Отказ в доставке чувствительного материала по значению. Aggrega выдаёт предупреждение, когда объявленные чувствительными данные передаются через ключ доставки как литерал, и никогда не останавливает сборку — семейство учётных данных по значению задумано намеренно. Оператор, который хочет, чтобы это предупреждение стало отказом, выражает это здесь.
- Самостоятельное решение о том, что считать учётными данными. Стандартная библиотека помечает свои сущности Features учётных данных меткой семейства, и чтение этой метки — один из способов рассуждать о них. Более широкий или более узкий предикат — внутренняя метка, правило именования, набор одобренных типов — так же доступен, потому что поступают метки, а не вердикт о них.
- Проверки на основе всего, что ваш каталог фиксирует в собственных метаданных. Организация, которая хранит статус проверки, резидентность данных или принадлежность в виде аннотаций на своих сущностях Feature, может требовать их от каждого присоединения. Правило, опирающееся на аннотацию, о которой Aggrega никогда не слышала, работает ровно так же хорошо, как правило, опирающееся на поставляемый ею ключ, потому что аннотации приходят в том виде, в каком написаны, — а это также означает, что сущность Feature и сущность Component оцениваются на равных основаниях, каждая по метаданным каталога, которые объявляет её собственная сущность.
- Управление тем, что компонент предъявляет и кому. Учётные данные, записанные на соединении, называют это соединение, а ребро соединения называет его цель, поэтому организация может отклонить учётные данные, предъявляемые компоненту вне зоны доверия, которую она помечает собственной меткой, — это суждение, которому нужны оба конца соединения и которое не может дать ни один факт только о потребляющем компоненте.
Роль вердикта принимает или отклоняет; она никогда не переписывает. Сборка либо продолжается без изменений, либо останавливается с сообщением вердикта, поэтому политика не может незаметно привести несоответствующий граф в соответствие.
Детали присоединений поступают в политику, оценивающую граф IR. Политика, оценивающая отрендеренные артефакты, получает эти артефакты и никакого графа, и это свойство этих входных данных, а не наложенное на них ограничение: два этапа отвечают на разные вопросы, и топология присоединений не входит в число вопросов, которые можно задать отрендеренному результату.
Выражение правил организации на языке политик
Приведённые выше шаблоны описывают, что делает присоединение управления; этот раздел о том, что пишет предприятие, чтобы его получить. Команда платформы, которой нужно сформулировать пятьдесят правил, не хочет пятидесяти плагинов. Она хочет иметь свои правила как содержимое — файлы, которые она проверяет, версионирует и поставляет, как любой другой артефакт, — с одним присоединённым движком, который их оценивает.
Именно это обеспечивает движок языка политик, присоединённый к сокету, и два таких движка поставляются внутри компилятора именно для этой цели: движок Rego и движок CEL. Оператор присоединяет один из них, объявляет файлы политик, которые он должен загрузить, и правила работают: никакого внешнего инструментария, ничего не загружается во время сборки и никакой логики политик в компиляторе. Оценка происходит внутри гостя WebAssembly, где и находятся все предметные знания.
Один и тот же движок обслуживает каждую роль управления, поэтому организация покрывает всю свою поверхность одним присоединённым плагином и несколькими его присоединениями:
- Оценка архитектуры. Будучи присоединённой к графу сборки, политика читает каждый узел, ребро и присоединение, которые содержит компилятор, а также перечисленные рядом с ними пути маршрутизации, и сообщает, что должно остановить сборку. Именно здесь находятся инвариант топологии, правило авторизации между границами или правило потока учётных данных.
- Оценка результата. Будучи присоединённой к отрендеренным артефактам, политика читает файлы, созданные сборкой, — как текст и как разобранные документы там, где формат был разобран до политики, — и сообщает о конкретном результате.
- Предоставление производных метаданных. Будучи присоединённой для формирования меток, политика решает, какие метки несут узлы сборки, исходя из окружения сущности Release и того, что узлы уже объявляют. Это механизм, который описывает шаблон 2 выше, с правилом, выраженным как содержимое политики, а не как специально созданный плагин.
- Добавление возможности, которую разработчик не написал. Будучи присоединённой для внедрения аннотаций, политика добавляет аннотации к компонентам сборки; аннотация под ключом, для которого сущность Manifest регистрирует привязку, разворачивается в присоединение сущности Feature, поэтому корпоративное правило может предоставить обёртку, нужную компоненту, а не просто отклонить её отсутствие. Решение записывает любое значение, которое оператор мог бы записать в эту аннотацию, — строку или объект подключей для привязки, маршрутизирующей несколько значений, — и сборка читает его ровно так же, как читает то же значение, записанное в сущности Release. Решение может только добавлять: значение, которое удалило бы аннотацию или отказалось бы от неё, отклоняется, а внедрённое значение, которое сборка не может маршрутизировать или которое не принимает привязанная сущность Feature, отклоняется с указанием плагина, который его внедрил.
Правило читает то, что несёт полезная нагрузка, и сообщает своё решение под именованным ключом:
# Evaluated by a governance verdict role over the assembled graphpackage acme.security
import rego.v1
deny contains msg if { some id, node in input.graph.spec.nodes node.labels["compliance.aggrega.ai/data-class"] == "restricted" not node.labels["acme.com/owner"] msg := sprintf("node %v holds restricted data and declares no owner.", [id])}Правило, которое следует за данными вдоль графа, читает маршруты, которые перечисляет полезная нагрузка. language-reference/examples/policy-data-class-route/ — одно такое правило, от начала до конца: оно останавливает сборку, в которой компонент, хранящий данные одного класса, достигает компонента другого класса по маршруту, на котором не присоединена ни одна понижающая класс сущность Feature, а та же сущность Aggregate завершается успешно, когда сущность Release направляет этот трафик через шлюз, несущий core/data-masking. Компилятор переносит метку класса как строку и ничего не ранжирует — классы, их порядок и сущности Features, которые считаются понижающими класс, являются настройками присоединения. Правило написано по одному разу для каждого из трёх движков — двух, скомпилированных в CLI, и OPA за эталонным гостем-адаптером, — каждая копия отдельно, поэтому сборка, по которой два движка расходятся, показывает это расхождение.
Собственный словарь политики сохраняется. Уровни серьёзности, на которые реагирует сокет, образуют закрытое множество, но имена, под которыми политика собирает свои решения, принадлежат политике. Имена по умолчанию — общепринятые, которые уже использует корпус Rego, а оператор, чьи политики называют свои решения иначе, объявляет сопоставление в настройках присоединения, — так что организация, уже поддерживающая библиотеку политик, принимает сокет, не переписывая её. Сопоставление типизировано схемой, которую плагин объявляет для своих настроек, поэтому некорректно сформированное сопоставление останавливает сборку до запуска какой-либо политики, а не маршрутизирует вердикт неверно.
Целая библиотека политик перемещается как одно присоединение. Набор политик можно присоединить файл за файлом или как единый архив, содержащий вместе его файлы политик и документы данных, который открывает гость. Архив, который не удаётся прочитать, сообщается именно как таковой, с указанием файла, — и никогда как набор политик, не пришедший ни к какому решению, потому что «библиотека была нечитаемой» никогда не должно быть неотличимо от «библиотека разрешила сборку».
Политика, которую невозможно оценить, останавливает сборку. Когда политику невозможно оценить, присоединение завершается сбоем, и сборка останавливается с ошибкой, называющей плагин, — намеренно отличной от вердикта, который останавливает сборку. Эти два случая нельзя путать, и ни один из них не является разрешением.
Полная поверхность создания — полезная нагрузка, которую предоставляет каждая роль, ключи решений, сопоставление с уровнями серьёзности и способ присоединения архива — описана в language-reference/plugins/policy-socket.md.
Наследование и дисциплина публикации
Наследование через extends: — это механизм каталога, который позволяет архитекторам платформы строить специализированные дочерние сущности на основе общих базовых линий. Два вида каталога расходятся в своих столпах данных. Родительская и дочерняя схемы сущности Feature компонуются во время загрузки рабочего пространства, образуя единую схему с происхождением для каждого листа. Расширяющая сущность Component не пишет содержимого столпа: она записывает литеральный маркер schema: inherited и получает блок schema: своей базы ровно таким, каким его написала база, на любой глубине цепочки.
Именно это решает вопрос управления, который ставит общая базовая линия, — какие ограничения дочерняя сущность может объявлять относительно своей базы. Для сущности Component ответ структурный, а не надзорный: объявленный контракт дочерней сущности просто является контрактом базы, поэтому дочерняя сущность не может ослабить, удалить или изменить тип ограничения базы, и для сохранения базовой линии не нужна никакая проверка во время публикации. Дочерняя сущность, которой обоснованно требуется более строгое правило, чем объявляет её база, выражает его как добавленную запись в своём блоке assertions:, которая компонуется рядом с правилами базы, а не заменяет их.
Что дочерняя сущность Component действительно компонует, так это структуру: её слоты присоединений (featuresSchema), сокеты топологии (usesSchema), список разрешённых самовнедрений (inject) и именованные assertions сливаются вдоль цепочки, причём повторно объявленная запись полностью заменяет запись базы.
Размещение правил: какие правила находятся в плагине политик, а какие — в схеме каждой сущности Component
Плагин дисциплины публикации — это место для сквозных правил, действующих во всём каталоге: правил цепочки поставок (например, «каждая сущность Recipe должна через implements: реализовывать сущность Component, существующую в каталоге»), корпоративных правил соответствия (например, «каждая сущность Component с compliance.aggrega.ai/scope: pci-dss должна через extends: расширять корпоративную базовую линию pci»). Эти правила охватывают несколько сущностей, оценивают рабочее пространство как единое целое или применяют соглашения во время публикации, а не во время сборки.
Объявление schema: каждой сущности Component / каждой сущности Feature — это место для ограничений отдельной сущности: типов, диапазонов, шаблонов и перечислений для каждого поля; межполевых правил, выраженных в отдельном блоке assertions:. Эти ограничения локальны для одной сущности и перемещаются вместе с ней по каталогу.
Это разделение не произвольно. Правило вроде «каждое обязательное поле должно присутствовать» — это ограничение отдельной сущности, место которому в массивах required:. Правило вроде «каждая дочерняя сущность, расширяющая родителя pci-dss, должна объявить метку управления на уровне рабочего пространства» — это межсущностное правило, которое применяет плагин политик. Эти два класса правил никогда не пересекаются, потому что отвечают на разные вопросы: схема проверяет «соответствует ли этот экземпляр своему контракту»; плагин политик проверяет «удовлетворяет ли этот каталог сквозным правилам, которых требует рабочее пространство».
При написании нового правила управления вопрос размещения таков: зависит ли правило только от содержимого одной сущности (→ схема или блок assertions) или от отношений между несколькими сущностями либо от конфигурации на уровне рабочего пространства (→ плагин политик). Шаблон Wasm-линтера — канонический механизм для сквозного случая; корпоративные каталоги могут распространять собственные плагины политик, которые используют тот же интерфейс контракта плагинов, что и стандартный плагин дисциплины публикации.
Дисциплина префиксов аннотаций
Пространство имён аннотаций несёт семантику происхождения — разные префиксы обозначают разные аудитории и разные органы управления. Авторы каталогов, корпоративные платформенные команды и сама платформа Aggrega записывают аннотации в один и тот же плоский словарь; именно префикс разделяет аудитории.
| Префикс | Происхождение | Аудитория | Изменяемость |
|---|---|---|---|
aggrega.ai/ (без поддомена) | Зарезервирован: выводится только компилятором Aggrega | Внутренние инструменты, отметки о происхождении | Пользователь не может записывать; аннотации с префиксом без поддомена, объявленные в пользовательском содержимом, отклоняются во время публикации |
<sub-domain>.aggrega.ai/ (например, component.aggrega.ai/, feature.aggrega.ai/, compliance.aggrega.ai/) | Соглашение каталога | Архитекторы, создающие сущности каталога; Wasm-плагины политик, потребляющие метки | Издатели каталога записывают; потребители читают |
<enterprise-domain>/ (например, acme.com/, my-org.io/) | Корпоративное наложение | Корпоративные платформенные команды; корпоративные Wasm-плагины | Корпоративные авторы записывают; компилятор платформы игнорирует их как непрозрачные метаданные |
<community-domain>/ (например, cncf.io/, kubernetes.io/) | Внешняя экосистема | Межэкосистемные инструменты, читающие общеизвестные метки | Управляется сообществом |
Префикс aggrega.ai/ без поддомена подчиняется самой строгой дисциплине: он зарезервирован исключительно для аннотаций, выводимых платформой. Компилятор выводит в отрендеренный результат aggrega.ai/compiler-version, aggrega.ai/component-id, aggrega.ai/recipe-uri, aggrega.ai/boundary-path и связанные ключи происхождения; пользовательское содержимое, которое напрямую объявляет аннотацию aggrega.ai/<key>, отклоняется во время публикации. Эта дисциплина не позволяет аннотациям, написанным пользователем, конфликтовать со сведениями о происхождении, которые выводит платформа.
Префиксы поддоменов под <sub-domain>.aggrega.ai/ образуют пространство соглашений каталога. Стандартная библиотека использует component.aggrega.ai/type (метку облачной нативной онтологии), feature.aggrega.ai/kind (разделение сущностей Feature на операционные и учётные), compliance.aggrega.ai/* (метки оси соответствия) и аналогичные ограниченные подпространства имён. Каждым поддоменом управляет определённая аудитория каталога: component.aggrega.ai/* — авторы сущностей Component, feature.aggrega.ai/* — авторы сущностей Feature, compliance.aggrega.ai/* — аудитория политик соответствия. Чтение из разных поддоменов (Wasm-плагин, читающий из нескольких подпространств имён) разрешено, но встречается редко; каждый плагин обычно ограничивается одним подпространством имён.
Префиксы корпоративных доменов (acme.com/..., my-org.io/...) образуют поверхность расширения платформы. Компилятор Aggrega рассматривает их как непрозрачные метаданные; их потребляют корпоративные Wasm-плагины. Предприятия создают любую структуру префиксов, подходящую для их управления, — плоскую (acme.com/owner: team-payments), поддоменную (security.acme.com/scope: pii) или иерархическую (org.acme.com/billing-center: finance). Платформа не ограничивает компоновку корпоративных префиксов; единственное правило — корпоративные префиксы не должны конфликтовать с aggrega.ai/ или его поддоменами.
Эта дисциплина важна, потому что аннотации распространяются каскадно — аннотации, записанные на подсистеме сущности Aggregate, распространяются на каждый компонент подсистемы, собственные аннотации экземпляра компонента переопределяют аннотации его подсистемы, а аннотации модуля доходят до собственных компонентов модуля; аннотации на границе сущности Release распространяются на каждый компонент границы. Аннотация провайдера попадает в отрендеренный вывод с любой из сторон, а если обе стороны записывают один и тот же ключ, применяется значение сущности Release. Без дисциплины префиксов аннотация на стороне сущности Aggregate могла бы незаметно перезаписать ключ происхождения, выводимый платформой, или корпоративная аннотация могла бы конфликтовать с ключом соглашения каталога. Таблица префиксов делает аудитории явными, а правило предотвращения конфликтов — применимым во время публикации.
Перечень поверхностей аннотаций для каждой сущности и семантику каскада из трёх корзин (.context.annotations.release / .context.annotations.catalog / .context.annotations.aggregate) см. в language-reference/vocabulary/labels-and-annotations.md.