Escrever o seu próprio plugin de governação
Esta página acompanha um plugin de governação desde o esqueleto de adaptador do kit de desenvolvimento de plugins até uma compilação que ele recusa. Copia-se o esqueleto, escreve-se nele uma regra, compila-se o .wasm, chama-se à mão cada um dos seus exports sobre os ficheiros de payload que acompanham o esqueleto, declara-se como uma entidade Plugin no catálogo do próprio espaço de trabalho, anexa-se a um papel e vê-se como interrompe uma compilação que viola a regra.
É o complemento prático de duas páginas: o socket de governação, que documenta os quatro papéis, o payload que cada um transporta e os veredictos com base nos quais o anfitrião age, e o guia do programador de plugins, que documenta a entidade Plugin e o seu ciclo de vida. Criar um fornecedor é o mesmo tipo de percurso para um guest de fornecedor.
Sobre os blocos desta página. Cada bloco que mostra uma saída foi copiado de uma execução real dos passos abaixo, pela ordem em que aparecem, segundo a convenção de saída: um bloco está completo, ou é um excerto que assinala onde foram omitidas linhas. 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á anexado.
O que é necessário
- A cadeia de ferramentas do Go, que compila para WebAssembly sem ferramentas adicionais.
- Uma cópia local do kit de desenvolvimento de plugins, que contém o esqueleto, e do pacote ABI em que o kit assenta: o
go.modda sua cópia aponta para ambos. - O binário
aggrega.
O kit fornece 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 ficheiros de payload, e uma cópia não modificada de cada um responde-lhes da mesma forma; cada comando aggrega desta página aplica-se a qualquer um deles com o seu próprio nome de artefacto, e o README de cada um indica como compilá-lo.
A estrutura do resultado final
Um plugin de governação são dois artefactos, como qualquer plugin: um guest .wasm, e uma entidade Plugin que o leva para um catálogo. Anexá-lo é uma entrada na configuração do espaço de trabalho. Nada muda no compilador.
Os dois diretórios com que este percurso termina, menos o que uma compilação 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 uma consola de administração — e uma compilação que transporte um componente de uma delas é interrompida, 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 chega ao kit e ao pacote ABI por caminhos relativos ao local onde se encontra dentro do kit, pelo que uma cópia fora do kit tem de os nomear ela própria. Dê-se ao módulo um caminho próprio e apontem-se as duas linhas replace para as 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 mantém-se como está.
2. Compilá-lo e chamar cada papel à mão
Compila-se a cópia antes de alterar o que quer que seja, para que a primeira coisa a executar seja uma cablagem que não se 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 indicado é um dos que a autodescrição describe() do guest declara — e, com --type governance, que o guest se declara um plugin de governação —, chama-o com um payload fornecido e imprime a resposta. O esqueleto inclui um ficheiro 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 governação transporta uma codificação binária, pelo que 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ê o seu guest e o seu payload a partir dos caminhos que lhe são dados e não precisa de nenhum espaço de trabalho, pelo que 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 o seu papel pode devolver: anotações a acrescentar, alterações de etiquetas e veredictos. Os dois papéis de transformação não devolvem nada, e cada papel de veredicto devolve um veredicto info — uma nota que regista uma observação e deixa inalterado o resultado de uma compilação. Essa nota é a prova de cablagem do esqueleto. Cada ficheiro de payload contém as duas entradas de um anexo tal como uma compilação as entrega: um ficheiro 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.
Eis 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 compilação com um único componente, os caminhos de encaminhamento enumerados sobre o grafo, e os sources e settings do anexo. 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 compilação; os outros três ficheiros 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 descodifica o seu payload, escreve-o como documento JSON e chama Evaluate com os ficheiros de política do anexo, as suas definições, esse documento e o nome da decisão que pretende receber. Os papéis de veredicto pedem três decisões, uma de cada vez — deny, warn e audit — e comunicam as respostas de cada uma com a severidade halt, warn e info; os dois papéis de transformação pedem annotations e labels. Assim, uma regra que interrompe uma compilação responde a deny.
Substitua-se 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 mantém-se, porque os ficheiros de papel constroem com ele a sua lista de programas. O resto é a regra, e quatro aspetos dela merecem uma leitura atenta.
- Lê o payload sob os nomes que o formato de transmissão lhe dá. Os nós estão em
graph.spec.nodes, indexados por id de nó, cada um com os 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 contém nenhum grafo, pelo que aí o ciclo não encontra nenhum nó. - O que proíbe cabe ao operador, não ao plugin. As categorias vêm dos
settingsdo anexo, pelo que o mesmo.wasmserve um espaço de trabalho que proíbedevtoole um que não proíbe nada. - Ordena antes de responder. A saída de uma compilação é idêntica byte a byte entre execuções com entrada idêntica, e um guest que respondesse pela ordem de um mapa Go quebraria isso por dentro.
- Falha de forma explícita. Definições ou um payload que não consiga ler devolvem um erro em vez de uma lista vazia, e o papel transforma esse erro numa chamada falhada. Uma lista vazia é uma política que não encontrou nada a dizer; uma chamada falhada é uma que não foi executada, e uma compilação só distingue as duas se o guest o fizer.
A regra nunca lê programs. A regra deste plugin está compilada no guest, pelo que um anexo fornece definições e nenhum ficheiro de política — a mesma forma que um guest construído em torno de um motor pré-compilado, e o oposto de um que carrega as suas regras a partir de sources.
Por fim, diz-se o que o plugin é. Em main.go, altere-se a descrição em descriptor():
Description: "Refuse a build that carries a component of a category the attachment forbids.",O gerador de entidades da secção 6 copia-a para a entidade Plugin.
4. Compilar de novo e ler a resposta da regra
./build.shWrote <guest>/dist/governance-adapter-skeleton-go.wasmChamam-se de novo os quatro exports sobre os mesmos ficheiros:
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 desapareceu de ambos os papéis de veredicto, e nenhum devolve um veredicto: os settings do payload fornecido não proíbem nenhuma categoria, pelo que a regra o permite. Uma lista results vazia é a forma de um papel de veredicto dizer que a compilação pode prosseguir.
Para ver a regra disparar, dão-se-lhe definições que proíbam o que o payload contém. Copie-se ir-verdict-payload.json para my-payload.json e substituam-se os 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 veredicto halt que contém a mensagem própria da regra. Numa compilação, um halt interrompe-a com essa mensagem como motivo.
5. Quando um payload não encaixa
O comando converte cada campo que o payload contém no tipo que a sua forma declara, e recusa um campo que não consiga converter antes de o guest ser executado. Escrevam-se os labels de um nó como uma lista em vez de um objeto, numa 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 um código diferente de zero, e o guest nunca é chamado.
A conversão verifica o tipo de cada campo que o payload contém; não verifica se o payload contém todos os campos que a forma exige. Um payload a que falte um é convertido e entregue ao guest na mesma, e um guest cuja regra lê esse campo não encontra lá nada. Por isso, um payload escrito à mão deve ser verificado 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 a partir do guest em vez de escritos à mão, pelo que a entidade não pode reivindicar um export que o binário não tem. A identidade é fornecida numa 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 indique outra; pluginType e os quatro exports são o que describe() comunica. Um plugin de governação não declara capacidades: o que pode devolver decorre do papel em que está anexado, não da entidade.
Durante o desenvolvimento de um plugin não há nada publicado para obter, pelo que uma compilação o lê a partir de um diretório de catálogo, com o .wasm ao lado da sua entidade. O ficheiro 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-se o ficheiro em vez de criar uma ligação para ele. Uma ligação nesse local só é seguida até algum ponto dentro do espaço de trabalho — ou, para um diretório de catálogo indicado fora do espaço de trabalho, até algum ponto dentro desse diretório; uma que leve mais longe interrompe a compilação e o pull, indicando a ligação, como expõe o limite do espaço de trabalho. Um pull que não encontre nenhum .wasm com esse nome para e indica o ficheiro que esperava, como descreve A plugin’s .wasm is not on this machine (O ficheiro 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. O seu catálogo contém também a consola 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. Anexá-lo e compilar
Um operador anexa um plugin de governação na configuração do espaço de trabalho, indicando o papel e as definições do anexo. .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 pelo seu tipo de plugin, nome e versão. O papel é ir-verdict, pelo que o anfitrião chama verdict_ir com o grafo de compilação assim que o grafo está construído e antes de qualquer coisa ser renderizada. auto_pull permite que a compilação resolva por si a Release, pelo que a primeira compilação 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 contém nenhum componente devtool, pelo que a regra permite a compilação, e a saída do Compose vai para dist/compose/docker-compose.yaml.
O aviso é esperado, e mantém-se enquanto o plugin for local. Diz que o guest foi executado sem nenhum digest de conteúdo registado com o qual o verificar — o que é verdade para um guest compilado há um minuto e lido a partir de junto da sua entidade em cada compilação. Um plugin anexado num papel de veredicto não molda nenhuma saída, pelo que um pull não regista nenhum digest para ele a partir de um diretório de catálogo; o que regista um é publicar o plugin e referenciar a entidade publicada.
9. Introduzir uma violação
Acrescentar a consola de administração ao Aggregate e colocá-la 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 violationA compilação para antes de renderizar o que quer que seja 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 leia saiba que componente remover e que política o pediu. O plugin não removeu a consola, não lhe mudou o nome nem renderizou a compilação sem ela: um papel de veredicto aceita ou rejeita, e o anfitrião nunca aplica a sua resposta como uma alteração.
O que alterar a seguir
- Mais regras, ou uma linguagem de políticas. Uma regra escrita em Go é compilada no guest. Para carregar antes regras a partir de ficheiros, leia-se
programsemEvaluate— ossourcesdo anexo, cada um com o seu nome de base e o seu texto — e entreguem-se a um motor. A ABI é própria do Aggrega descreve um guest que envolve um motor de políticas externo. - Outros papéis. O mesmo
Evaluateserve todos os papéis; responder aannotationsoulabelsfaz com que o plugin molde uma compilação num papel de transformação. As formas das decisões estão no README do esqueleto, e o que cada papel pode alterar está descrito na secção os quatro papéis. - Menos exports. Um plugin que sirva apenas
ir-verdictelimina os outros ficheiros de papel e as respetivas entradas emdescriptor(). Um anexo que aponte um papel para um export que o guest não declara é então recusado pelo nome, antes de o guest ser executado. - Definições tipadas. Um guest pode declarar um JSON Schema para as suas definições em
describe(), e o anfitrião valida então as definições de um anexo em relação a ele antes de o guest ser executado; ver Definições tipadas. - A publicação, que transforma a organização em diretório de catálogo num artefacto fixado por digest que uma Release resolve e verifica. O guia do programador de plugins cobre esse ciclo de vida.
Referências relacionadas
- O socket de governação — os quatro papéis, os respetivos payloads, as severidades dos veredictos e a forma como um operador anexa um plugin.
- Contrato de Plugins — as formas de entrada e de saída de cada socket, e a codificação que cada uma transporta.
- Guia do programador de plugins Wasm — a entidade
Plugin, a superfície de capacidades e o ciclo de vida de publicação. - Criar um fornecedor — o mesmo percurso para um guest de fornecedor.
- Ler a saída nestas páginas — a convenção que os blocos de saída acima seguem.