Написание собственного плагина управления
Эта страница проводит плагин управления от каркаса адаптера из набора для разработки плагинов до сборки, которую он отклоняет. Вы копируете каркас, пишете в нём одно правило, собираете .wasm, вручную вызываете каждый его экспорт на файлах полезной нагрузки, поставляемых с каркасом, объявляете его как сущность Plugin в собственном каталоге рабочего пространства, подключаете к роли и наблюдаете, как он останавливает сборку, нарушающую правило.
Это практическое дополнение к сокету управления, где описаны четыре роли, полезная нагрузка каждой и вердикты, по которым действует хост, и к руководству разработчика плагинов, где описаны сущность Plugin и её жизненный цикл. Создание провайдера — такое же пошаговое руководство для гостевого модуля провайдера.
О блоках на этой странице. Каждый блок с выводом скопирован из реального выполнения шагов ниже в порядке их следования и соответствует соглашению о выводе: блок либо полный, либо является фрагментом с отметкой о пропущенных строках. Два заполнителя обозначают абсолютные пути, различающиеся на каждой машине: <guest> — каталог вашей копии каркаса, а <workspace> — каталог рабочего пространства, в котором подключён плагин.
Что понадобится
- Набор инструментов Go, который компилирует в WebAssembly без дополнительных средств.
- Локальная копия набора для разработки плагинов, содержащего каркас, и пакета ABI, на котором основан набор:
go.modвашей копии указывает на оба. - Исполняемый файл
aggrega.
Набор поставляет тот же каркас для Rust в rust/examples/governance-adapter-skeleton и для TypeScript в typescript/examples/governance-adapter-skeleton. Каждый содержит те же четыре файла полезной нагрузки, и неизменённая копия каждого отвечает на них одинаково; каждая команда aggrega на этой странице применима к любому из них с собственным именем артефакта, а README каждого описывает его сборку.
Как выглядит готовый результат
Плагин управления, как и любой плагин, состоит из двух артефактов: гостевого модуля .wasm и сущности Plugin, которая вносит его в каталог. Подключение — это одна запись в конфигурации рабочего пространства. В компиляторе ничего не меняется.
Два каталога, которыми завершается это руководство, без того, что сборка записывает в рабочее пространство:
category-guard/ your copy of the skeleton: the Go module that compiles to the .wasm .gitignore README.md the skeleton's own guide go.mod go.sum main.go the describe() self-report and the shared plumbing evaluator.go the seam, where the rule goes annotations.go the annotation-transform role labels.go the label-transform role verdicts.go the ir-verdict and render-verdict roles build.sh annotation-payload.json label-payload.json ir-verdict-payload.json render-verdict-payload.json my-payload.json a copy you edit in section 4 wrong-payload.json a copy you break in section 5 overlay.yaml the identity you supply to the entity generator dist/governance-adapter-skeleton-go.wasm the compiled guestshop/ the workspace the plugin is attached in catalog/component/example/compute/api/1.0.0/component.yaml catalog/component/example/devtool/db-console/1.0.0/component.yaml catalog/recipe/compose/api/1.0.0/recipe.yaml catalog/recipe/compose/db-console/1.0.0/recipe.yaml catalog/plugin/governance/category-guard/0.1.0/plugin.yaml catalog/plugin/governance/category-guard/0.1.0/governance--category-guard.wasm aggregate.yaml manifest.yaml release.yaml .aggrega-config.yamlПравило, которое применяет плагин, распространённое: рабочее пространство называет категории компонентов, которые оно не поставляет, — здесь devtool, категория консоли администрирования, — и сборка, содержащая компонент одной из них, останавливается с его указанием.
1. Скопируйте каркас
cp -r /path/to/aggrega-pdk/go/examples/governance-adapter-skeleton category-guardcd category-guardgo.mod каркаса ссылается на набор и пакет ABI по путям относительно своего расположения внутри набора, поэтому копия вне набора указывает их сама. Дайте модулю собственный путь и направьте две строки replace на ваши локальные копии:
module example.com/category-guard
go 1.26.0
require ( github.com/aggrega-ai/aggrega-abi/go v0.0.0 github.com/aggrega-ai/aggrega-pdk/go v0.0.0 github.com/extism/go-pdk v1.1.3)
replace github.com/aggrega-ai/aggrega-pdk/go => /path/to/aggrega-pdk/go
replace github.com/aggrega-ai/aggrega-abi/go => /path/to/aggrega-abi/gogo.sum каркаса остаётся без изменений.
2. Соберите его и вызовите каждую роль вручную
Соберите копию, ничего не меняя, чтобы первым запущенным кодом была связующая логика, которую писали не вы:
./build.shWrote <guest>/dist/governance-adapter-skeleton-go.wasmaggrega plugin run-local загружает гостевой модуль по пути, проверяет, что указанный вами экспорт объявлен в самоописании describe() модуля, а при --type governance — что модуль сообщает о себе как о плагине управления, вызывает его с переданной вами полезной нагрузкой и выводит ответ. Каркас поставляет по одному файлу полезной нагрузки на роль, каждый — небольшой корректный вход для своего экспорта. Полезная нагрузка пишется в JSON; протокол каждой роли управления использует двоичную кодировку, поэтому команда преобразует полезную нагрузку в неё перед вызовом экспорта и выводит ответ экспорта в JSON.
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export transform_annotations --with @annotation-payload.json{ "injections": []}run-local читает гостевой модуль и полезную нагрузку по указанным вами путям и не нуждается в рабочем пространстве, поэтому его можно запускать из любого каталога.
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export mutate --with @label-payload.json{ "patches": []}aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_ir --with @ir-verdict-payload.json{ "results": [ { "severity": "info", "message": "this adapter has no policy engine yet: the seam received rules.policy (43 bytes) and some settings" } ]}aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_render --with @render-verdict-payload.json{ "results": [ { "severity": "info", "message": "this adapter has no policy engine yet: the seam received rules.policy (43 bytes) and some settings" } ]}Каждый ответ имеет форму, которую разрешено возвращать его роли: добавляемые аннотации, изменения меток и вердикты. Две роли преобразования ничего не возвращают, а каждая роль вердикта возвращает один вердикт info — примечание, которое фиксирует наблюдение и не меняет исход сборки. Это примечание — доказательство того, что связующая логика каркаса работает. Каждый файл полезной нагрузки содержит два входа подключения в том виде, в каком их передаёт сборка: один файл политики, rules.policy, в sources и объект settings. Примечание говорит, что оба дошли до шва — единственной функции, которую остальной каркас вызывает со всем, что получила роль.
Вот полезная нагрузка, которую прочитает правило ниже, ir-verdict-payload.json, целиком:
{ "graph": { "apiVersion": "aggrega.ai/v1beta1", "kind": "IR", "metadata": { "aggregate_name": "shop" }, "spec": { "nodes": { "api": { "component": "example/compute/api", "resolved_version": "1.0.0", "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "compute" } } }, "edges": [], "values_mapping": {}, "infra_mapping": {}, "feature_values_mapping": {}, "provenance": { "schema_version": "aggrega.ai/v1beta1", "compiler_version": "0.0.0", "aggregate_version": "1.0.0", "manifest_version": "1.0.0", "release_version": "1.0.0" } } }, "precalculated_paths": [], "sources": [ { "path": "rules.policy", "content": "policy text, handed to the engine verbatim\n" } ], "settings": { "max_nodes": 50 }}Это вход роли ir-verdict: граф сборки с одним компонентом, пути маршрутизации, перечисленные по графу, а также sources и settings подключения. Каждое поле описано на справочной странице роли, схеме сокета политик, а сам граф — на схеме графа сборки; остальные три файла следуют схеме annotation-transform, схеме mutator и, для verdict_render, RenderPolicyInput схемы сокета политик.
3. Напишите одно правило
Правило находится в evaluator.go — шве каркаса. Каждая роль декодирует свою полезную нагрузку, записывает её как JSON-документ и вызывает Evaluate с файлами политик подключения, его настройками, этим документом и именем решения, которое она хочет получить. Роли вердикта по очереди запрашивают три решения — deny, warn и audit — и сообщают ответы каждого с уровнем серьёзности halt, warn и info; две роли преобразования запрашивают annotations и labels. Поэтому правило, останавливающее сборку, отвечает на deny.
Замените evaluator.go на:
package main
import ( "encoding/json" "fmt" "slices" "sort")
// Program is one policy program the attachment carried.type Program struct { Path string Text string}
// categoryLabel is the label a catalog Component states its category in.const categoryLabel = "component.aggrega.ai/category"
// Evaluate refuses every component whose category the attachment's settings// list under forbidden_categories.func Evaluate(programs []Program, settings json.RawMessage, payload json.RawMessage, decision string) ([]json.RawMessage, error) { if decision != denyDecision { return nil, nil }
var config struct { ForbiddenCategories []string `json:"forbidden_categories"` } if len(settings) > 0 { if err := json.Unmarshal(settings, &config); err != nil { return nil, fmt.Errorf("reading the settings: %w", err) } }
var input struct { Graph struct { Spec struct { Nodes map[string]struct { Labels map[string]string `json:"labels"` } `json:"nodes"` } `json:"spec"` } `json:"graph"` } if err := json.Unmarshal(payload, &input); err != nil { return nil, fmt.Errorf("reading the build graph: %w", err) }
// A Go map has no order, so the node ids are sorted: identical input must // yield an identical sequence of decisions. ids := make([]string, 0, len(input.Graph.Spec.Nodes)) for id := range input.Graph.Spec.Nodes { ids = append(ids, id) } sort.Strings(ids)
var decisions []json.RawMessage for _, id := range ids { category := input.Graph.Spec.Nodes[id].Labels[categoryLabel] if !slices.Contains(config.ForbiddenCategories, category) { continue } message, err := json.Marshal(fmt.Sprintf( "component %q is a %s component, and this workspace ships none", id, category)) if err != nil { return nil, err } decisions = append(decisions, message) } return decisions, nil}Program остаётся, потому что файлы ролей строят с его помощью свой список программ. Остальное — правило, и в нём стоит внимательно прочитать четыре вещи.
- Оно читает полезную нагрузку под именами, которые даёт ей протокол. Узлы находятся в
graph.spec.nodes, с ключом по id узла, каждый со своимиlabels, — тот же путь, который Что раскрывает полезная нагрузка каждой роли даёт политике Rego какinput.graph.spec.nodes. Правило, написанное для этой роли, ничего не читает в других: полезная нагрузкаrender-verdictне содержит графа, поэтому там цикл не находит ни одного узла. - Что запрещать, решает оператор, а не плагин. Категории берутся из
settingsподключения, поэтому один и тот же.wasmобслуживает рабочее пространство, запрещающееdevtool, и то, которое не запрещает ничего. - Оно сортирует, прежде чем ответить. Вывод сборки побайтово идентичен между запусками с идентичным входом, и гостевой модуль, отвечающий в порядке Go map, нарушил бы это изнутри.
- Оно завершается с явной ошибкой. Настройки или полезная нагрузка, которые не удаётся прочитать, возвращают ошибку, а не пустой список, и роль превращает эту ошибку в неудачный вызов. Пустой список — это политика, которой нечего сказать; неудачный вызов — это политика, которая не выполнилась, и сборка различает их, только если их различает гостевой модуль.
Правило никогда не читает programs. Правило этого плагина скомпилировано в гостевой модуль, поэтому подключение передаёт настройки и не передаёт файл политики — та же форма, что у гостевого модуля, построенного вокруг предварительно скомпилированного движка, и противоположная той, что у модуля, загружающего правила из sources.
Наконец, опишите, что представляет собой плагин. В main.go измените описание в descriptor():
Description: "Refuse a build that carries a component of a category the attachment forbids.",Генератор сущностей в разделе 6 копирует его в сущность Plugin.
4. Соберите снова и прочитайте ответ правила
./build.shWrote <guest>/dist/governance-adapter-skeleton-go.wasmСнова вызовите четыре экспорта на тех же файлах:
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export transform_annotations --with @annotation-payload.jsonaggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export mutate --with @label-payload.jsonaggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_ir --with @ir-verdict-payload.jsonaggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_render --with @render-verdict-payload.json{ "injections": []}{ "patches": []}{ "results": []}{ "results": []}Примечание-заполнитель исчезло из обеих ролей вердикта, и ни одна не возвращает вердикт: settings поставляемой полезной нагрузки не запрещают ни одной категории, поэтому правило её пропускает. Пустой список results — это то, как роль вердикта сообщает, что сборка может продолжаться.
Чтобы увидеть срабатывание правила, задайте ему настройки, запрещающие то, что содержит полезная нагрузка. Скопируйте ir-verdict-payload.json в my-payload.json и замените его settings на:
"settings": { "forbidden_categories": [ "compute" ] }aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_ir --with @my-payload.json{ "results": [ { "severity": "halt", "message": "component \"api\" is a compute component, and this workspace ships none" } ]}Решение deny приходит как вердикт halt с собственным сообщением правила. В сборке halt останавливает её с этим сообщением в качестве причины.
5. Когда полезная нагрузка не подходит
Команда преобразует каждое поле полезной нагрузки в тип, объявленный его формой, и отклоняет поле, которое не может преобразовать, до запуска гостевого модуля. Запишите labels узла как список, а не объект, в копии с именем wrong-payload.json:
"labels": [ "server", "compute" ]aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_ir --with @wrong-payload.jsonunder key "api": expected JSON object, found [Команда завершается с ненулевым кодом, и гостевой модуль не вызывается.
Преобразование проверяет тип каждого поля, которое содержит полезная нагрузка; оно не проверяет, что полезная нагрузка содержит каждое поле, требуемое формой. Полезная нагрузка без одного из полей всё равно преобразуется и передаётся гостевому модулю, а модуль, чьё правило читает это поле, ничего там не находит. Поэтому проверяйте написанную вручную полезную нагрузку по справочной странице её схемы: молчание команды не означает, что полезная нагрузка полна.
6. Объявите его как сущность Plugin в каталоге вашего рабочего пространства
Поля контракта сущности считываются из гостевого модуля, а не пишутся вручную, поэтому сущность не может заявить экспорт, которого нет в бинарном файле. Идентификационные данные вы задаёте в небольшом оверлее, overlay.yaml:
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: category-guardaggrega plugin gen-catalog --plugin dist/governance-adapter-skeleton-go.wasm \ --overlay overlay.yaml --output-dir ../shop/catalog/plugingenerated ../shop/catalog/plugin/governance/category-guard/0.1.0/plugin.yamlСгенерированная сущность:
# Generated from the plugin by `aggrega plugin gen-catalog`. You may narrow its capability lists; edit nothing else here.apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: category-guard version: 0.1.0 pluginType: governance description: Refuse a build that carries a component of a category the attachment forbids.spec: abiVersion: v1beta1 exports: - name: transform_annotations - name: mutate - name: verdict_ir - name: verdict_renderversion — это версия, которую build.sh каркаса вписывает в гостевой модуль, 0.1.0, если AGGREGA_PLUGIN_VERSION не задаёт другую; pluginType и четыре экспорта — то, что сообщает describe(). Плагин управления не объявляет возможностей: то, что он может возвращать, определяется ролью, к которой он подключён, а не сущностью.
Пока вы разрабатываете плагин, опубликованного ничего нет, поэтому сборка читает его из каталога-директории, где .wasm лежит рядом с его сущностью. Файл рядом с сущностью именуется по типу плагина и имени сущности, в директории, где находится документ сущности, — для governance/category-guard это governance--category-guard.wasm:
cp dist/governance-adapter-skeleton-go.wasm \ ../shop/catalog/plugin/governance/category-guard/0.1.0/governance--category-guard.wasmКопируйте файл, а не создавайте ссылку на него. Ссылка в этом месте разрешается только в пределах рабочего пространства — или, для каталога-директории, указанной вне рабочего пространства, в пределах этой директории; ссылка, ведущая дальше, останавливает сборку и pull с указанием ссылки, как описано в разделе граница рабочего пространства. Pull, который не находит .wasm под этим именем, останавливается и называет ожидаемый файл, как описано в A plugin’s .wasm is not on this machine (Файла плагина нет на этой машине).
7. Рабочее пространство, которое охраняет плагин
Рабочее пространство — небольшой магазин: API и документы, которые собирают его с помощью Docker Compose. Его каталог также содержит консоль администрирования, которую правило отклонит, — сущность Component с категорией devtool.
catalog/component/example/compute/api/1.0.0/component.yaml:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: example/compute/api version: 1.0.0 description: The shop's HTTP API. labels: component.aggrega.ai/type: server component.aggrega.ai/category: computespec: schema: infra: port: type: integer default: 8080 description: The port the API listens on.catalog/component/example/devtool/db-console/1.0.0/component.yaml:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: example/devtool/db-console version: 1.0.0 description: A database administration console in the browser. labels: component.aggrega.ai/type: server component.aggrega.ai/category: devtoolspec: schema: infra: port: type: integer default: 8081 description: The port the console listens on.catalog/recipe/compose/api/1.0.0/recipe.yaml:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api version: 1.0.0 description: Runs the API as a Docker Compose service.spec: capability: compose implements: example/compute/api:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: "registry.example.com/shop/api:1.0.0" ports: http: {{ .infra.port }}catalog/recipe/compose/db-console/1.0.0/recipe.yaml:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: db-console version: 1.0.0 description: Runs the database console as a Docker Compose service.spec: capability: compose implements: example/devtool/db-console:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: "adminer:4" ports: http: {{ .infra.port }}aggregate.yaml:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: shop version: "1.0.0" description: The shop's API.spec: components: api: type: example/compute/apimanifest.yaml:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: shop-manifest version: "1.0.0" description: Binds each component type to its Docker Compose recipe.spec: mappings: components: type: example/compute/api:1.0.0: api:1.0.0 example/devtool/db-console:1.0.0: db-console:1.0.0release.yaml:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: shop-staging environment: staging version: "1.0.0"spec: aggregate: shop manifest: shop-manifest components: api: {}8. Подключите его и выполните сборку
Оператор подключает плагин управления в конфигурации рабочего пространства, указывая роль и настройки подключения. .aggrega-config.yaml:
workspace: catalog_dirs: - catalogauto_pull: trueplugins: governance: - uri: governance/category-guard:0.1.0 role: ir-verdict with: settings: forbidden_categories: - devtooluri указывает сущность по типу плагина, имени и версии. Роль — ir-verdict, поэтому хост вызывает verdict_ir с графом сборки после того, как граф построен, и до того, как что-либо отрендерено. auto_pull позволяет сборке самой разрешить сущность Release, поэтому первой сборке не нужен отдельный шаг.
cd ../shopaggrega build --release release.yaml warning: plugin "governance/category-guard" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recordedPull complete: release.lock (entities=7, source_artifacts=0, external_inputs=0)[… omitted: a line reporting total build time, which differs on every run]Build completed: 1 file written to <workspace>/distВ магазине нет компонента devtool, поэтому правило пропускает сборку, и вывод Compose попадает в dist/compose/docker-compose.yaml.
Предупреждение ожидаемо и сохраняется, пока плагин локальный. Оно говорит, что гостевой модуль запущен без записанного дайджеста содержимого, с которым его можно сверить, — что верно для модуля, собранного минуту назад и читаемого рядом с его сущностью при каждой сборке. Плагин, подключённый к роли вердикта, не формирует вывода, поэтому pull не записывает для него дайджест из каталога-директории; дайджест записывается, когда плагин опубликован и указана ссылка на опубликованную сущность.
9. Внесите нарушение
Добавьте консоль администрирования в сущность Aggregate и разместите её в сущности Release:
spec: components: api: type: example/compute/api console: type: example/devtool/db-console components: api: {} console: {}aggrega build --release release.yaml[… omitted: the unverified-plugin warning, and the pull's lines saying the Release could not be rendered to discover its external inputs, which carry the refusal below][POLICY_ERROR E0005] policy plugin "category-guard" rejected the build: component "console" is a devtool component, and this workspace ships none caused by: policy violationСборка останавливается до рендеринга чего-либо и не записывает dist/. Сообщение — собственное предложение правила, предварённое именем плагина, поэтому автор, читающий его, знает, какой компонент убрать и какая политика этого потребовала. Плагин не удалил консоль, не переименовал её и не отрендерил сборку без неё: роль вердикта принимает или отклоняет, и хост никогда не применяет её ответ как изменение.
Что изменить дальше
- Больше правил или язык политик. Правило, написанное на Go, компилируется в гостевой модуль. Чтобы вместо этого загружать правила из файлов, читайте
programsвEvaluate—sourcesподключения, каждый со своим базовым именем и текстом — и передавайте их движку. ABI принадлежит Aggrega описывает гостевой модуль, оборачивающий сторонний движок политик. - Другие роли. Один и тот же
Evaluateобслуживает каждую роль; ответ наannotationsилиlabelsзаставляет плагин формировать сборку в роли преобразования. Формы решений описаны в README каркаса, а что может изменять каждая роль — в разделе четыре роли. - Меньше экспортов. Плагин, обслуживающий только
ir-verdict, удаляет файлы других ролей и их записи вdescriptor(). Подключение, направляющее роль на экспорт, который гостевой модуль не объявляет, тогда отклоняется по имени до запуска модуля. - Типизированные настройки. Гостевой модуль может объявить JSON Schema для своих настроек в
describe(), и тогда хост проверяет по ней настройки подключения до запуска модуля; см. Типизированные настройки. - Публикация, которая превращает схему с каталогом-директорией в артефакт, закреплённый по дайджесту, который сущность Release разрешает и проверяет. Этот жизненный цикл описан в руководстве разработчика плагинов.
Связанные справочные материалы
- Сокет управления — четыре роли, их полезные нагрузки, уровни серьёзности вердиктов и то, как оператор подключает плагин.
- Контракт Plugin — формы входных и выходных данных каждого сокета и кодировка, которую несёт каждая из них.
- Руководство разработчика плагинов Wasm — сущность
Plugin, поверхность возможностей и жизненный цикл публикации. - Создание провайдера — такое же пошаговое руководство для гостевого модуля провайдера.
- Как читать вывод на этих страницах — соглашение, которому следуют приведённые выше блоки вывода.