Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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.mod da 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 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

A 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

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

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

O 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:

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

aggrega 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.

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

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"
}
]
}

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 seus labels — o mesmo caminho que O que o payload de cada papel expõe dá a uma política Rego como input.graph.spec.nodes. Uma regra escrita para este papel não lê nada nos outros: o payload de render-verdict nã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 settings da vinculação, então o mesmo .wasm atende a um espaço de trabalho que proíbe devtool e 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

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

Chame os quatro exports de novo com os mesmos arquivos:

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": []
}

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"
]
}
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"
}
]
}

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"
]
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 [

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

A entidade gerada:

# 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 é 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:

Terminal window
cp dist/governance-adapter-skeleton-go.wasm \
../shop/catalog/plugin/governance/category-guard/0.1.0/governance--category-guard.wasm

Copie 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/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. 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:
- catalog
auto_pull: true
plugins:
governance:
- uri: governance/category-guard:0.1.0
role: ir-verdict
with:
settings:
forbidden_categories:
- devtool

O 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.

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

A 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: {}
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

O 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 programs em Evaluate — os sources da 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 Evaluate atende a todos os papéis; responder a annotations ou labels faz 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-verdict exclui os outros arquivos de papel e suas entradas em descriptor(). 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.