Escrever seu próprio plugin de governança
Esta página acompanha um plugin de governança desde o esqueleto de adaptador do kit de desenvolvimento de plugins até um build que ele recusa. Você copia o esqueleto, escreve uma regra nele, compila o .wasm, chama à mão cada um dos seus exports sobre os arquivos de payload que acompanham o esqueleto, declara-o como uma entidade Plugin no catálogo do seu próprio espaço de trabalho, vincula-o a um papel e o vê interromper um build que viola a regra.
É o complemento prático de duas páginas: o socket de governança, que documenta os quatro papéis, o payload que cada um carrega e os vereditos com base nos quais o host age, e o guia do desenvolvedor de plugins, que documenta a entidade Plugin e o seu ciclo de vida. Criar um provedor é o mesmo tipo de percurso para um guest de provedor.
Sobre os blocos desta página. Cada bloco que mostra uma saída foi copiado de uma execução real dos passos abaixo, na ordem em que aparecem, seguindo a convenção de saída: um bloco está completo, ou é um trecho que marca onde linhas foram omitidas. Dois marcadores de posição representam caminhos absolutos que diferem em cada máquina: <guest> é o diretório da sua cópia do esqueleto, e <workspace> o diretório do espaço de trabalho em que o plugin está vinculado.
Do que você precisa
- A toolchain do Go, que compila para WebAssembly sem ferramentas extras.
- Uma cópia local do kit de desenvolvimento de plugins, que contém o esqueleto, e do pacote ABI sobre o qual o kit é construído: o
go.modda sua cópia aponta para ambos. - O binário
aggrega.
O kit traz o mesmo esqueleto para Rust, em rust/examples/governance-adapter-skeleton, e para TypeScript, em typescript/examples/governance-adapter-skeleton. Cada um contém os mesmos quatro arquivos de payload, e uma cópia não modificada de cada um os responde da mesma forma; todo comando aggrega desta página se aplica a qualquer um deles com o seu próprio nome de artefato, e o README de cada um indica como compilá-lo.
A estrutura do resultado final
Um plugin de governança são dois artefatos, como qualquer plugin: um guest .wasm, e uma entidade Plugin que o leva a um catálogo. Vinculá-lo é uma entrada na configuração do espaço de trabalho. Nada no compilador muda.
Os dois diretórios com que este percurso termina, menos o que um build escreve no espaço de trabalho:
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.yamlA regra que o plugin aplica é comum: um espaço de trabalho nomeia as categorias de componentes que não distribui — aqui devtool, a categoria de um console de administração — e um build que carrega um componente de uma delas é interrompido, nomeando-o.
1. Copiar o esqueleto
cp -r /path/to/aggrega-pdk/go/examples/governance-adapter-skeleton category-guardcd category-guardO go.mod do esqueleto alcança o kit e o pacote ABI por caminhos relativos ao local onde fica dentro do kit, então uma cópia fora do kit precisa nomeá-los por conta própria. Dê ao módulo um caminho seu e aponte as duas linhas replace para as suas cópias locais:
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/goO go.sum do esqueleto permanece como está.
2. Compilá-lo e chamar cada papel à mão
Compile a cópia antes de mudar qualquer coisa, para que a primeira coisa que você executa seja uma fiação que você não escreveu:
./build.shWrote <guest>/dist/governance-adapter-skeleton-go.wasmaggrega plugin run-local carrega um guest a partir de um caminho, verifica que o export que você nomeia é um dos que o autorrelato describe() do guest declara — e, com --type governance, que o guest se declara um plugin de governança —, chama-o com um payload que você fornece e imprime a resposta. O esqueleto inclui um arquivo de payload por papel, cada um uma entrada pequena e válida para o seu export. O payload é escrito em JSON; o formato de transmissão de cada papel de governança carrega uma codificação binária, então o comando converte o payload para essa codificação antes de chamar o export e imprime a resposta do 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 lê seu guest e seu payload dos caminhos que você lhe dá e não precisa de nenhum espaço de trabalho, então pode ser executado a partir de qualquer diretório.
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 resposta tem a forma que seu papel pode retornar: anotações a adicionar, alterações de rótulos e vereditos. Os dois papéis de transformação não retornam nada, e cada papel de veredito retorna um veredito info — uma nota que registra uma observação e deixa inalterado o resultado de um build. Essa nota é a prova de fiação do esqueleto. Cada arquivo de payload traz as duas entradas de uma vinculação como um build as entrega: um arquivo de política, rules.policy, em sources, e um objeto settings. A nota diz que ambas chegaram ao ponto de junção — a única função que o resto do esqueleto chama com o que quer que o papel tenha recebido.
Aqui está o payload que a regra abaixo vai ler, ir-verdict-payload.json, completo:
{ "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 }}É a entrada do papel ir-verdict: um grafo de build com um único componente, os caminhos de roteamento enumerados sobre o grafo, e os sources e settings da vinculação. Cada campo é descrito na página de referência do papel, o schema do socket de políticas, e o próprio grafo na página schema do grafo de build; os outros três arquivos seguem o schema annotation-transform, o schema do mutador e, para verdict_render, o RenderPolicyInput do schema do socket de políticas.
3. Escrever uma regra
A regra fica em evaluator.go, o ponto de junção do esqueleto. Cada papel decodifica seu payload, escreve-o como um documento JSON e chama Evaluate com os arquivos de política da vinculação, suas configurações, esse documento e o nome da decisão que quer receber de volta. Os papéis de veredito pedem três decisões, uma de cada vez — deny, warn e audit — e relatam as respostas de cada uma com a severidade halt, warn e info; os dois papéis de transformação pedem annotations e labels. Então uma regra que interrompe um build responde a deny.
Substitua 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 permanece, porque os arquivos de papel constroem com ele sua lista de programas. O resto é a regra, e quatro coisas nela merecem uma leitura atenta.
- Ela lê o payload sob os nomes que o formato de transmissão lhe dá. Os nós ficam em
graph.spec.nodes, indexados por id de nó, cada um com seuslabels— o mesmo caminho que O que o payload de cada papel expõe dá a uma política Rego comoinput.graph.spec.nodes. Uma regra escrita para este papel não lê nada nos outros: o payload derender-verdictnão traz nenhum grafo, então lá o laço não encontra nenhum nó. - O que ela proíbe cabe ao operador, não ao plugin. As categorias vêm dos
settingsda vinculação, então o mesmo.wasmatende a um espaço de trabalho que proíbedevtoole a um que não proíbe nada. - Ela ordena antes de responder. A saída de um build é idêntica byte a byte entre execuções com entrada idêntica, e um guest que respondesse na ordem de um mapa Go quebraria isso por dentro.
- Ela falha de forma explícita. Configurações ou um payload que ela não consegue ler retornam um erro em vez de uma lista vazia, e o papel transforma esse erro em uma chamada com falha. Uma lista vazia é uma política que não encontrou nada a dizer; uma chamada com falha é uma que não foi executada, e um build só distingue as duas se o guest o fizer.
A regra nunca lê programs. A regra deste plugin é compilada no guest, então uma vinculação fornece configurações e nenhum arquivo de política — a mesma forma de um guest construído em torno de um mecanismo pré-compilado, e o oposto de um que carrega suas regras de sources.
Por último, diga o que o plugin é. Em main.go, altere a descrição em descriptor():
Description: "Refuse a build that carries a component of a category the attachment forbids.",O gerador de entidades da seção 6 a copia para a entidade Plugin.
4. Compilar de novo e ler a resposta da regra
./build.shWrote <guest>/dist/governance-adapter-skeleton-go.wasmChame os quatro exports de novo com os mesmos arquivos:
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": []}A nota provisória sumiu dos dois papéis de veredito, e nenhum deles retorna um veredito: os settings do payload incluído não proíbem nenhuma categoria, então a regra o permite. Uma lista results vazia é como um papel de veredito diz que o build pode prosseguir.
Para ver a regra disparar, dê a ela configurações que proíbam o que o payload traz. Copie ir-verdict-payload.json para my-payload.json e substitua seus 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" } ]}A decisão deny chega como um veredito halt que traz a mensagem própria da regra. Em um build, um halt o interrompe com essa mensagem como motivo.
5. Quando um payload não se encaixa
O comando converte cada campo que o payload traz para o tipo que sua forma declara, e recusa um campo que não consegue converter antes de o guest ser executado. Escreva os labels de um nó como uma lista em vez de um objeto, em uma cópia chamada 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 [O comando termina com código diferente de zero, e o guest nunca é chamado.
A conversão verifica o tipo de cada campo que o payload traz; ela não verifica se o payload traz cada campo que a forma exige. Um payload ao qual falta um é convertido e entregue ao guest mesmo assim, e um guest cuja regra lê esse campo não encontra nada ali. Então verifique um payload que você escreve à mão em relação à página de referência do seu schema: o silêncio do comando não diz que o payload está completo.
6. Declará-lo como entidade Plugin no catálogo do seu espaço de trabalho
Os campos de contrato da entidade são lidos do guest em vez de escritos à mão, então a entidade não pode reivindicar um export que o binário não tem. Você fornece a identidade em uma pequena sobreposição, 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.yamlA entidade gerada:
# 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 é a que o build.sh do esqueleto grava no guest, 0.1.0, a menos que AGGREGA_PLUGIN_VERSION nomeie outra; pluginType e os quatro exports são o que describe() relata. Um plugin de governança não declara capacidades: o que ele pode retornar vem do papel em que está vinculado, não da entidade.
Enquanto você desenvolve um plugin, não há nada publicado para buscar, então um build o lê de um diretório de catálogo, com o .wasm ao lado da sua entidade. O arquivo ao lado da entidade recebe o nome a partir do tipo de plugin e do nome da entidade, no diretório em que está o documento da entidade — 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.wasmCopie o arquivo em vez de criar um link para ele. Um link nesse lugar só é seguido até algum ponto dentro do espaço de trabalho — ou, para um diretório de catálogo listado fora do espaço de trabalho, até algum ponto dentro desse diretório; um que leve além disso interrompe o build e o pull, nomeando o link, como expõe o limite do workspace. Um pull que não encontra nenhum .wasm com esse nome para e nomeia o arquivo que esperava, como descreve A plugin’s .wasm is not on this machine (O arquivo Wasm de um plugin não está nesta máquina).
7. O espaço de trabalho que o plugin protege
O espaço de trabalho é uma pequena loja: uma API, e os documentos que a constroem com Docker Compose. Seu catálogo também traz o console de administração que a regra vai recusar, um Component cuja categoria é 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. Vinculá-lo e fazer o build
Um operador vincula um plugin de governança na configuração do espaço de trabalho, nomeando o papel e as configurações da vinculação. .aggrega-config.yaml:
workspace: catalog_dirs: - catalogauto_pull: trueplugins: governance: - uri: governance/category-guard:0.1.0 role: ir-verdict with: settings: forbidden_categories: - devtoolO uri nomeia a entidade por seu tipo de plugin, nome e versão. O papel é ir-verdict, então o host chama verdict_ir com o grafo de build assim que o grafo é construído e antes de qualquer coisa ser renderizada. auto_pull permite que o build resolva a Release por conta própria, então o primeiro build não precisa de nenhum passo separado.
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>/distA loja não traz nenhum componente devtool, então a regra permite o build, e a saída do Compose vai para dist/compose/docker-compose.yaml.
O aviso é esperado, e permanece enquanto o plugin for local. Ele diz que o guest foi executado sem nenhum digest de conteúdo registrado com o qual verificá-lo — o que é verdade para um guest compilado há um minuto e lido de ao lado da sua entidade a cada build. Um plugin vinculado em um papel de veredito não molda nenhuma saída, então um pull não registra nenhum digest para ele a partir de um diretório de catálogo; o que registra um é publicar o plugin e referenciar a entidade publicada.
9. Introduzir uma violação
Adicione o console de administração ao Aggregate e coloque-o na 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 violationO build para antes de renderizar qualquer coisa e não escreve nenhum dist/. A mensagem é a frase própria da regra, encabeçada pelo nome do plugin, para que um autor que a lê saiba qual componente remover e qual política pediu isso. O plugin não removeu o console, não o renomeou nem renderizou o build sem ele: um papel de veredito aceita ou rejeita, e o host nunca aplica sua resposta como uma alteração.
O que mudar em seguida
- Mais regras, ou uma linguagem de políticas. Uma regra escrita em Go é compilada no guest. Para carregar regras de arquivos em vez disso, leia
programsemEvaluate— ossourcesda vinculação, cada um com seu nome base e seu texto — e entregue-os a um mecanismo. A ABI é própria do Aggrega descreve um guest que encapsula um mecanismo de políticas externo. - Outros papéis. O mesmo
Evaluateatende a todos os papéis; responder aannotationsoulabelsfaz o plugin moldar um build em um papel de transformação. As formas das decisões estão no README do esqueleto, e o que cada papel pode alterar é descrito na seção as quatro funções. - Menos exports. Um plugin que atende apenas a
ir-verdictexclui os outros arquivos de papel e suas entradas emdescriptor(). Uma vinculação que aponta um papel para um export que o guest não declara é então recusada pelo nome, antes de o guest ser executado. - Configurações tipadas. Um guest pode declarar um JSON Schema para suas configurações em
describe(), e o host então valida as configurações de uma vinculação em relação a ele antes de o guest ser executado; veja Configurações tipadas. - A publicação, que transforma o arranjo em diretório de catálogo em um artefato fixado por digest que uma Release resolve e verifica. O guia do desenvolvedor de plugins cobre esse ciclo de vida.
Referências relacionadas
- O socket de governança — os quatro papéis, seus payloads, as severidades dos vereditos e como um operador vincula um plugin.
- Contrato de Plugins — as formas de entrada e saída de cada socket, e a codificação que cada uma carrega.
- Guia do desenvolvedor de plugins Wasm — a entidade
Plugin, a superfície de capacidades e o ciclo de vida de publicação. - Criar um provedor — o mesmo percurso para um guest de provedor.
- Ler a saída nestas páginas — a convenção que os blocos de saída acima seguem.