Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Написання власного плагіна керування

Ця сторінка проводить плагін керування від каркаса адаптера з набору для розробки плагінів до збірки, яку він відхиляє. Ви копіюєте каркас, пишете в ньому одне правило, збираєте .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 guest
shop/ 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. Скопіюйте каркас

Terminal window
cp -r /path/to/aggrega-pdk/go/examples/governance-adapter-skeleton category-guard
cd category-guard

go.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/go

go.sum каркаса лишається без змін.

2. Зберіть його та викличте кожну роль вручну

Зберіть копію, нічого не змінюючи, щоб першим запущеним кодом була сполучна логіка, яку писали не ви:

Terminal window
./build.sh
Wrote <guest>/dist/governance-adapter-skeleton-go.wasm

aggrega plugin run-local завантажує гостьовий модуль за шляхом, перевіряє, що вказаний вами експорт оголошено в самоописі describe() модуля, а з --type governance — що модуль повідомляє про себе як про плагін керування, викликає його з переданим вами корисним навантаженням і виводить відповідь. Каркас постачає по одному файлу корисного навантаження на роль, кожен — невеликий коректний вхід для свого експорту. Корисне навантаження пишеться в JSON; протокол кожної ролі керування використовує двійкове кодування, тож команда перетворює корисне навантаження на нього перед викликом експорту й виводить відповідь експорту в JSON.

Terminal window
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \
--type governance --export transform_annotations --with @annotation-payload.json
{
"injections": []
}

run-local читає гостьовий модуль і корисне навантаження за вказаними вами шляхами й не потребує робочого простору, тож його можна запускати з будь-якого каталогу.

Terminal window
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \
--type governance --export mutate --with @label-payload.json
{
"patches": []
}
Terminal window
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"
}
]
}
Terminal window
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. Зберіть знову й прочитайте відповідь правила

Terminal window
./build.sh
Wrote <guest>/dist/governance-adapter-skeleton-go.wasm

Знову викличте чотири експорти на тих самих файлах:

Terminal window
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \
--type governance --export transform_annotations --with @annotation-payload.json
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \
--type governance --export mutate --with @label-payload.json
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \
--type governance --export verdict_ir --with @ir-verdict-payload.json
aggrega 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"
]
}
Terminal window
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"
]
Terminal window
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \
--type governance --export verdict_ir --with @wrong-payload.json
under key "api": expected JSON object, found [

Команда завершується з ненульовим кодом, і гостьовий модуль не викликається.

Перетворення перевіряє тип кожного поля, яке містить корисне навантаження; воно не перевіряє, що корисне навантаження містить кожне поле, якого вимагає форма. Корисне навантаження без одного з полів однаково перетворюється й передається гостьовому модулю, а модуль, чиє правило читає це поле, нічого там не знаходить. Тож перевіряйте написане вручну корисне навантаження за довідковою сторінкою його схеми: мовчання команди не означає, що корисне навантаження повне.

6. Оголосіть його як сутність Plugin у каталозі вашого робочого простору

Поля контракту сутності зчитуються з гостьового модуля, а не пишуться вручну, тож сутність не може заявити експорт, якого немає у двійковому файлі. Ідентифікаційні дані ви задаєте в невеликому оверлеї, overlay.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: category-guard
Terminal window
aggrega plugin gen-catalog --plugin dist/governance-adapter-skeleton-go.wasm \
--overlay overlay.yaml --output-dir ../shop/catalog/plugin
generated ../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/v1beta1
kind: Plugin
metadata:
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_render

version — це версія, яку build.sh каркаса вписує в гостьовий модуль, 0.1.0, якщо AGGREGA_PLUGIN_VERSION не задає іншої; pluginType і чотири експорти — те, що повідомляє describe(). Плагін керування не оголошує можливостей: те, що він може повертати, визначається роллю, до якої його підключено, а не сутністю.

Поки ви розробляєте плагін, нічого опублікованого немає, тож збірка читає його з каталогу-директорії, де .wasm лежить поряд із його сутністю. Файл поряд із сутністю називається за типом плагіна та іменем сутності, у директорії, де розташовано документ сутності, — для governance/category-guard це governance--category-guard.wasm:

Terminal window
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/v1beta1
kind: Component
metadata:
name: example/compute/api
version: 1.0.0
description: The shop's HTTP API.
labels:
component.aggrega.ai/type: server
component.aggrega.ai/category: compute
spec:
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/v1beta1
kind: Component
metadata:
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: devtool
spec:
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/v1beta1
kind: Recipe
metadata:
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/v1beta1
kind: Recipe
metadata:
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/v1beta1
kind: Aggregate
metadata:
name: shop
version: "1.0.0"
description: The shop's API.
spec:
components:
api:
type: example/compute/api

manifest.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
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.0

release.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: shop-staging
environment: staging
version: "1.0.0"
spec:
aggregate: shop
manifest: shop-manifest
components:
api: {}

8. Підключіть його та виконайте збірку

Оператор підключає плагін керування в конфігурації робочого простору, зазначаючи роль і налаштування підключення. .aggrega-config.yaml:

workspace:
catalog_dirs:
- catalog
auto_pull: true
plugins:
governance:
- uri: governance/category-guard:0.1.0
role: ir-verdict
with:
settings:
forbidden_categories:
- devtool

uri вказує сутність за типом плагіна, іменем і версією. Роль — ir-verdict, тож хост викликає verdict_ir з графом збірки після того, як граф побудовано, і до того, як щось відрендерено. auto_pull дає змогу збірці самій розв’язати сутність Release, тож першій збірці не потрібен окремий крок.

Terminal window
cd ../shop
aggrega 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 recorded
Pull 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: {}
Terminal window
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 розв’язує й перевіряє. Цей життєвий цикл описано в посібнику розробника плагінів.