Написання власного плагіна керування
Ця сторінка проводить плагін керування від каркаса адаптера з набору для розробки плагінів до збірки, яку він відхиляє. Ви копіюєте каркас, пишете в ньому одне правило, збираєте .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, поверхня можливостей і життєвий цикл публікації. - Створення провайдера — такий самий покроковий посібник для гостьового модуля провайдера.
- Як читати вивід на цих сторінках — домовленість, якої дотримуються наведені вище блоки виводу.