Escribir tu propio plugin de gobernanza
Esta página lleva un plugin de gobernanza desde el esqueleto de adaptador del kit de desarrollo de plugins hasta una compilación que rechaza. Copias el esqueleto, escribes una regla en él, compilas el .wasm, llamas a mano a cada uno de sus exports sobre los archivos de carga útil que incluye el esqueleto, lo declaras como entidad Plugin en el catálogo propio de tu espacio de trabajo, lo vinculas a un rol y observas cómo detiene una compilación que infringe la regla.
Es el complemento práctico de dos páginas: el socket de gobernanza, que documenta los cuatro roles, la carga útil que lleva cada uno y los veredictos sobre los que actúa el host, y la guía para desarrolladores de plugins, que documenta la entidad Plugin y su ciclo de vida. Crear un proveedor es el mismo tipo de recorrido para un guest de proveedor.
Sobre los bloques de esta página. Cada bloque que muestra una salida se copió de una ejecución real de los pasos siguientes, en el orden en que aparecen, según la convención de salida: un bloque está completo, o es un extracto que marca dónde se omitieron líneas. Dos marcadores de posición representan rutas absolutas que difieren en cada máquina: <guest> es el directorio de tu copia del esqueleto, y <workspace> el directorio del espacio de trabajo en el que está vinculado el plugin.
Lo que necesitas
- La cadena de herramientas de Go, que compila a WebAssembly sin herramientas adicionales.
- Una copia local del kit de desarrollo de plugins, que contiene el esqueleto, y del paquete ABI sobre el que se construye el kit: el
go.modde tu copia apunta a ambos. - El binario
aggrega.
El kit incluye el mismo esqueleto para Rust, en rust/examples/governance-adapter-skeleton, y para TypeScript, en typescript/examples/governance-adapter-skeleton. Cada uno contiene los mismos cuatro archivos de carga útil, y una copia sin modificar de cada uno los responde de la misma forma; cada comando aggrega de esta página se aplica a cualquiera de ellos con su propio nombre de artefacto, y el README de cada uno indica cómo compilarlo.
La estructura del resultado final
Un plugin de gobernanza son dos artefactos, como cualquier plugin: un guest .wasm, y una entidad Plugin que lo lleva a un catálogo. Vincularlo es una entrada en la configuración del espacio de trabajo. En el compilador no cambia nada.
Los dos directorios con los que termina este recorrido, menos lo que una compilación escribe en el espacio de trabajo:
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.yamlLa regla que aplica el plugin es habitual: un espacio de trabajo nombra las categorías de componentes que no distribuye — aquí devtool, la categoría de una consola de administración — y una compilación que lleva un componente de una de ellas se detiene, nombrándolo.
1. Copiar el esqueleto
cp -r /path/to/aggrega-pdk/go/examples/governance-adapter-skeleton category-guardcd category-guardEl go.mod del esqueleto alcanza el kit y el paquete ABI mediante rutas relativas al lugar que ocupa dentro del kit, así que una copia fuera del kit debe nombrarlos por sí misma. Da al módulo una ruta propia y apunta las dos líneas replace a tus copias locales:
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/goEl go.sum del esqueleto se queda como está.
2. Compilarlo y llamar a mano a cada rol
Compila la copia antes de cambiar nada, para que lo primero que ejecutes sea un cableado que no escribiste tú:
./build.shWrote <guest>/dist/governance-adapter-skeleton-go.wasmaggrega plugin run-local carga un guest desde una ruta, comprueba que el export que nombras es uno de los que declara el autoinforme describe() del guest — y, con --type governance, que el guest se declara como plugin de gobernanza —, lo llama con una carga útil que aportas tú e imprime la respuesta. El esqueleto incluye un archivo de carga útil por rol, cada uno una entrada pequeña y válida para su export. La carga útil se escribe en JSON; el formato de transmisión de cada rol de gobernanza lleva una codificación binaria, así que el comando convierte la carga útil a esa codificación antes de llamar al export e imprime la respuesta del export como JSON.
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export transform_annotations --with @annotation-payload.json{ "injections": []}run-local lee su guest y su carga útil de las rutas que le das y no necesita ningún espacio de trabajo, así que se puede ejecutar desde cualquier directorio.
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" } ]}Cada respuesta tiene la forma que su rol puede devolver: anotaciones que añadir, cambios de etiquetas y veredictos. Los dos roles de transformación no devuelven nada, y cada rol de veredicto devuelve un veredicto info — una nota que registra una observación y deja sin cambios el resultado de una compilación. Esa nota es la prueba de cableado del esqueleto. Cada archivo de carga útil lleva las dos entradas de una vinculación tal como una compilación las entrega: un archivo de política, rules.policy, bajo sources, y un objeto settings. La nota dice que ambas llegaron al punto de unión — la única función a la que el resto del esqueleto llama con lo que haya recibido el rol.
Esta es la carga útil que leerá la regla de abajo, ir-verdict-payload.json, completa:
{ "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 }}Es la entrada del rol ir-verdict: un grafo de compilación con un solo componente, las rutas de enrutamiento enumeradas sobre el grafo, y los sources y settings de la vinculación. Cada campo se describe en la página de referencia del rol, el esquema del socket de políticas, y el propio grafo en el esquema del grafo de compilación; los otros tres archivos siguen el esquema annotation-transform, el esquema del mutador y, para verdict_render, el RenderPolicyInput del esquema del socket de políticas.
3. Escribir una regla
La regla vive en evaluator.go, el punto de unión del esqueleto. Cada rol decodifica su carga útil, la escribe como un documento JSON y llama a Evaluate con los archivos de política de la vinculación, sus ajustes, ese documento y el nombre de la decisión que quiere recibir. Los roles de veredicto piden tres decisiones por turno — deny, warn y audit — e informan las respuestas de cada una con la severidad halt, warn e info; los dos roles de transformación piden annotations y labels. Así que una regla que detiene una compilación responde a deny.
Sustituye evaluator.go por:
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 se queda, porque los archivos de rol construyen con él su lista de programas. El resto es la regla, y cuatro cosas de ella merecen una lectura atenta.
- Lee la carga útil con los nombres que le da el formato de transmisión. Los nodos están en
graph.spec.nodes, indexados por id de nodo, cada uno con suslabels— la misma ruta que Qué expone la carga útil de cada rol da a una política Rego comoinput.graph.spec.nodes. Una regla escrita para este rol no lee nada en los demás: la carga útil derender-verdictno lleva ningún grafo, así que allí el bucle no encuentra ningún nodo. - Lo que prohíbe corresponde al operador, no al plugin. Las categorías proceden de los
settingsde la vinculación, así que el mismo.wasmsirve a un espacio de trabajo que prohíbedevtooly a uno que no prohíbe nada. - Ordena antes de responder. La salida de una compilación es idéntica byte a byte entre ejecuciones con una entrada idéntica, y un guest que respondiera en el orden de un mapa de Go lo rompería desde dentro.
- Falla de forma visible. Unos ajustes o una carga útil que no puede leer devuelven un error en lugar de una lista vacía, y el rol convierte ese error en una llamada fallida. Una lista vacía es una política que no encontró nada que decir; una llamada fallida es una que no se ejecutó, y una compilación distingue ambas solo si el guest lo hace.
La regla nunca lee programs. La regla de este plugin está compilada en el guest, así que una vinculación aporta ajustes y ningún archivo de política — la misma forma que un guest construido alrededor de un motor precompilado, y lo contrario de uno que carga sus reglas desde sources.
Por último, di qué es el plugin. En main.go, cambia la descripción en descriptor():
Description: "Refuse a build that carries a component of a category the attachment forbids.",El generador de entidades de la sección 6 la copia en la entidad Plugin.
4. Volver a compilar y leer la respuesta de la regla
./build.shWrote <guest>/dist/governance-adapter-skeleton-go.wasmVuelve a llamar a los cuatro exports con los mismos archivos:
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": []}La nota provisional ha desaparecido de ambos roles de veredicto, y ninguno devuelve un veredicto: los settings de la carga útil incluida no prohíben ninguna categoría, así que la regla lo permite. Una lista results vacía es la forma en que un rol de veredicto dice que la compilación puede continuar.
Para ver la regla dispararse, dale ajustes que prohíban lo que lleva la carga útil. Copia ir-verdict-payload.json a my-payload.json y sustituye sus settings por:
"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" } ]}La decisión deny llega como un veredicto halt que lleva el mensaje propio de la regla. En una compilación, un halt la detiene con ese mensaje como motivo.
5. Cuando una carga útil no encaja
El comando convierte cada campo que lleva la carga útil al tipo que declara su forma, y rechaza un campo que no puede convertir antes de que se ejecute el guest. Escribe las labels de un nodo como lista en lugar de como objeto, en una copia llamada 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 [El comando termina con un código distinto de cero, y el guest nunca se llama.
La conversión comprueba el tipo de cada campo que lleva la carga útil; no comprueba que la carga útil lleve cada campo que exige la forma. Una carga útil a la que le falta uno se convierte y se entrega al guest de todos modos, y un guest cuya regla lee ese campo no encuentra nada en él. Así que comprueba una carga útil que escribas a mano contra la página de referencia de su esquema: el silencio del comando no dice que la carga útil esté completa.
6. Declararlo como entidad Plugin en el catálogo de tu espacio de trabajo
Los campos de contrato de la entidad se leen del guest en lugar de escribirse a mano, así que la entidad no puede declarar un export que el binario no tiene. Tú aportas la identidad en una pequeña superposición, 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.yamlLa entidad generada:
# 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 es la que el build.sh del esqueleto estampa en el guest, 0.1.0 salvo que AGGREGA_PLUGIN_VERSION nombre otra; pluginType y los cuatro exports son lo que informa describe(). Un plugin de gobernanza no declara capacidades: lo que puede devolver depende del rol en el que está vinculado, no de la entidad.
Mientras desarrollas un plugin no hay nada publicado que obtener, así que una compilación lo lee de un directorio de catálogo, con el .wasm junto a su entidad. El archivo junto a la entidad se nombra a partir del tipo de plugin y el nombre de la entidad, en el directorio en el que está el documento de la entidad — para 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.wasmCopia el archivo en lugar de enlazarlo. Un enlace en ese lugar solo se sigue hasta algún punto dentro del espacio de trabajo — o, para un directorio de catálogo listado fuera del espacio de trabajo, hasta algún punto dentro de ese directorio; uno que lleve más allá detiene la compilación y el pull nombrando el enlace, como expone el límite del workspace. Un pull que no encuentra ningún .wasm con ese nombre se detiene y nombra el archivo que esperaba, como describe A plugin’s .wasm is not on this machine (El archivo Wasm de un plugin no está en esta máquina).
7. El espacio de trabajo que protege el plugin
El espacio de trabajo es una pequeña tienda: una API y los documentos que la construyen con Docker Compose. Su catálogo también contiene la consola de administración que la regla rechazará, un Component cuya categoría es 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. Vincularlo y compilar
Un operador vincula un plugin de gobernanza en la configuración del espacio de trabajo, nombrando el rol y los ajustes de la vinculación. .aggrega-config.yaml:
workspace: catalog_dirs: - catalogauto_pull: trueplugins: governance: - uri: governance/category-guard:0.1.0 role: ir-verdict with: settings: forbidden_categories: - devtoolEl uri nombra la entidad por su tipo de plugin, nombre y versión. El rol es ir-verdict, así que el host llama a verdict_ir con el grafo de compilación una vez construido el grafo y antes de que se renderice nada. auto_pull permite que la compilación resuelva la Release por sí misma, así que la primera compilación no necesita ningún paso aparte.
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>/distLa tienda no contiene ningún componente devtool, así que la regla permite la compilación, y la salida de Compose queda en dist/compose/docker-compose.yaml.
La advertencia es esperada, y se mantiene mientras el plugin sea local. Dice que el guest se ejecutó sin ningún digest de contenido registrado con el que comprobarlo — lo cual es cierto para un guest compilado hace un minuto y leído desde junto a su entidad en cada compilación. Un plugin vinculado en un rol de veredicto no da forma a ninguna salida, así que un pull no registra ningún digest para él desde un directorio de catálogo; lo que registra uno es publicar el plugin y hacer referencia a la entidad publicada.
9. Introducir una infracción
Añade la consola de administración al Aggregate y colócala en la 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 violationLa compilación se detiene antes de renderizar nada y no escribe ningún dist/. El mensaje es la frase propia de la regla, encabezada con el nombre del plugin, así que un autor que lo lee sabe qué componente quitar y qué política lo pidió. El plugin no quitó la consola, ni la renombró, ni renderizó la compilación sin ella: un rol de veredicto acepta o rechaza, y el host nunca aplica su respuesta como un cambio.
Qué cambiar a continuación
- Más reglas, o un lenguaje de políticas. Una regla escrita en Go se compila en el guest. Para cargar en cambio reglas desde archivos, lee
programsenEvaluate— lossourcesde la vinculación, cada uno con su nombre base y su texto — y entrégalos a un motor. La ABI es propia de Aggrega describe un guest que envuelve un motor de políticas externo. - Otros roles. El mismo
Evaluatesirve a todos los roles; responder aannotationsolabelshace que el plugin dé forma a una compilación en un rol de transformación. Las formas de las decisiones están en el README del esqueleto, y lo que cada rol puede cambiar está en los cuatro roles. - Menos exports. Un plugin que solo sirve a
ir-verdictelimina los demás archivos de rol y sus entradas endescriptor(). Una vinculación que dirige un rol a un export que el guest no declara se rechaza entonces por su nombre, antes de que se ejecute el guest. - Ajustes tipados. Un guest puede declarar un JSON Schema para sus ajustes en
describe(), y el host valida entonces los ajustes de una vinculación contra él antes de que se ejecute el guest; consulta Ajustes tipados. - La publicación, que convierte la disposición en directorio de catálogo en un artefacto fijado por digest que una Release resuelve y verifica. La guía para desarrolladores de plugins cubre ese ciclo de vida.
Referencias relacionadas
- El socket de gobernanza — los cuatro roles, sus cargas útiles, las severidades de los veredictos y cómo un operador vincula un plugin.
- Contrato de los Plugins — las formas de entrada y salida de cada socket, y la codificación que lleva cada una.
- Guía para desarrolladores de plugins Wasm — la entidad
Plugin, la superficie de capacidades y el ciclo de vida de publicación. - Crear un proveedor — el mismo recorrido para un guest de proveedor.
- Leer la salida en estas páginas — la convención que siguen los bloques de salida anteriores.