Перейти к содержимому
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 разрешает и проверяет. Этот жизненный цикл описан в руководстве разработчика плагинов.