Uma política que vincula Features que ninguém escreveu: anotações injetadas em `annotation-transform`
Uma política de governança dá a cada componente de uma loja o monitoramento da plataforma e um papel do AWS IAM. Ela faz isso adicionando anotações. O Manifest associa duas chaves de anotação a duas Features, e uma anotação sob uma chave associada se expande em uma vinculação de Feature. Assim, as anotações que a política adiciona trazem a cada componente um ServiceMonitor do Prometheus e um ServiceAccount do Kubernetes, e nem o Aggregate nem a Release escrevem qualquer um deles.
A política é vinculada no papel annotation-transform, uma vez para cada mecanismo de políticas compilado na CLI: Rego e CEL. A prova central é uma Release de controle que escreve à mão as mesmas anotações. Compilada sem nenhuma política, ela renderiza os mesmos arquivos, byte a byte, que a Release que a política anota.
O que ele constrói
| instância | Component do catálogo | o que ela traz em release.yaml |
|---|---|---|
api | example/compute/service | nada |
worker | example/compute/service | nada |
gateway | example/compute/service | a sua própria anotação de monitoramento, com um intervalo de 10 segundos |
Os três são compilados para o Kubernetes por meio do Helm, em dist/shop/helm/. example/compute/service é um Component de demonstração no catálogo da biblioteca padrão. Cada instância dele precisa trazer uma vinculação core/prometheus-exporter, um requisito que o Component declara e o build verifica.
As duas associações de anotações
manifest.yaml dá significado a duas chaves de anotação:
features: type: core/prometheus-exporter: helm/prometheus-exporter:1.0.0 core/aws-irsa: helm/aws-irsa:1.0.0 annotations: feature.aggrega.ai/monitoring: feature: core/prometheus-exporter maps: infra: - interval - port - path aws-role: feature: core/aws-irsa maps: infra: - role_arnUma associação que roteia várias subchaves recebe como valor um objeto que nomeia cada uma delas, então feature.aggrega.ai/monitoring recebe {interval: …, port: …, path: …}. Uma associação que roteia uma única subchave recebe uma string, então aws-role recebe o ARN do papel. A vinculação em que uma anotação se expande recebe o nome da sua chave. core/aws-irsa dá ao seu ServiceAccount o nome da vinculação, e é por isso que essa chave não tem ponto nem barra.
Vincular a política
.aggrega-config.yaml indica o hub como seu registry, nenhum diretório de catálogo e nenhuma vinculação de governança. A política é vinculada pelo arquivo que um build nomeia com --config: governance-rego.yaml para o mecanismo Rego, governance-cel.yaml para o mecanismo CEL. O do Rego diz:
plugins: governance: - uri: governance/rego:0.9.0 role: annotation-transform with: sources: - policies/platform-defaults.rego--config nomeia o arquivo de configuração global para essa execução, no lugar daquele que a máquina leria de outra forma, e o .aggrega-config.yaml deste workspace continua se sobrepondo a ele.
0.9.0 é uma versão em que o hub publica a entidade Plugin de cada mecanismo, então a vinculação é resolvida a partir do registry que o workspace lê, ou do binário aggrega dessa versão, que a traz. O mecanismo que roda é o compilado no binário aggrega que executa o build, qualquer que seja a versão que a vinculação nomeia. O objeto que a anotação de monitoramento recebe precisa de um mecanismo que injete um objeto de subchaves, e os mecanismos das versões anteriores à 0.8.7 não fazem isso.
O que uma política annotation-transform lê
Uma política em annotation-transform lê duas coisas:
input.targetslista cada componente que ela pode anotar. Cada destino tem umboundary_path, umcomponent_namee asannotationsque a Release escreve nesse componente, cada valor tal como está escrito.input.binding_keyslista as chaves de anotação que o Manifest associa.
aggrega build --release <release> --dry-run --policy-input <dir> escreve em <dir> o payload que cada papel recebe e não escreve mais nada. Depois que um build de release.yaml preencheu o seu lockfile:
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '.binding_keys' payloads/annotation-transform.json# ["feature.aggrega.ai/monitoring","aws-role"]jq -c '.targets[]' payloads/annotation-transform.json# {"boundary_path":"shop","component_name":"api","annotations":{}}# {"boundary_path":"shop","component_name":"worker","annotations":{}}# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}As annotations de um destino contêm o que a Release escreve no próprio componente. O valor aggrega.ai/namespace da fronteira não está entre elas.
A política
policies/platform-defaults.rego reúne uma decisão por anotação sob annotations. Cada decisão nomeia o destino pelos dois campos sob os quais ele foi lido, depois a chave e o valor:
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": monitoring, "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { monitoring in input.binding_keys some t in input.targets not monitoring in object.keys(t.annotations)}
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": role, "annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),} if { role in input.binding_keys some t in input.targets not role in object.keys(t.annotations)}Cada regra dispara apenas para uma chave em input.binding_keys, então a política não adiciona nada a que um Manifest não tenha dado significado. Cada regra também ignora um destino que já traz a chave. Uma decisão sob uma chave que o componente já traz substitui o valor que a Release escreveu. Sem esse teste, gateway perderia o seu intervalo de 10 segundos para os 30 segundos da política.
policies/platform-defaults.cel expressa as mesmas duas decisões como uma única expressão, unindo duas listas com +. Uma chave de mapa é testada com in em vez de object.keys, e o ARN do papel é montado com +, já que a linguagem de expressões não tem sprintf. A metade da expressão referente ao papel diz:
+ input.targets .filter(t, "aws-role" in input.binding_keys && !("aws-role" in t.annotations)) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "aws-role", "annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name, }),O que o build renderiza
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullescreve doze arquivos em dist/shop/helm/: um Deployment e um Service para cada componente, o ServiceMonitor em que a sua anotação de monitoramento se expande e o ServiceAccount em que a sua anotação aws-role se expande. O spec do ServiceMonitor de api, a partir da anotação que a política injetou:
spec: selector: matchLabels: app.kubernetes.io/name: api endpoints: - port: metrics interval: 30s path: /metricsO de gateway traz interval: 10s, o valor que a sua entrada na Release escreve. O ServiceAccount sob o qual api roda, a partir da anotação aws-role injetada:
apiVersion: v1kind: ServiceAccountmetadata: name: api-aws-role namespace: shop annotations: eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api" aggrega.ai/boundary-path: shop aggrega.ai/recipe-uri: "aws-irsa:1.0.0" [… omitted: the labels, which carry the version of the aggrega binary that built the file]Injetadas ou escritas à mão: os mesmos arquivos
release-by-hand.yaml é release.yaml com as anotações que a política injeta escritas à mão em cada componente. Compilado sem nenhuma política vinculada,
aggrega build --release release-by-hand.yaml --auto-pullele escreve os mesmos doze arquivos, byte a byte, que release.yaml com a política vinculada em qualquer um dos dois mecanismos. Nada é excluído dessa comparação: se uma anotação foi injetada não fica registrado em nenhum arquivo renderizado. check.sh compara as árvores a cada execução.
O build lê um valor injetado exatamente como lê o mesmo valor escrito na Release, então o valor se expande na mesma vinculação.
Onde a injeção fica registrada
O grafo de build a registra, e --ir-graph imprime o grafo. Cada componente que recebeu uma anotação injetada traz aggrega.ai/injected-by, que nomeia o plugin, entre as suas anotações de Release. Depois de aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph, api diz:
"release_annotations": { "aggrega.ai/namespace": "shop", "aws-role": "arn:aws:iam::123456789012:role/shop-api", "aggrega.ai/injected-by": "governance/rego"},O registro é por componente, não por chave: gateway também o traz, pelo seu aws-role. Cada vinculação em que as anotações se expandiram tem "origin": "annotation" no grafo, como teria para uma anotação escrita à mão.
O destino Helm não renderiza nenhuma anotação aggrega.ai/injected-by, e diz isso. Neste build, cada componente que recebeu uma injeção adiciona três avisos à saída. O primeiro dos de api diz:
warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it--no-unsupported-field-warnings silencia essa classe de aviso e não muda nada do que o build escreve.
O papel adiciona anotações, e nada mais
Uma decisão nomeia um componente, uma chave de anotação e o seu valor. Nada em uma decisão adiciona um componente, muda um rótulo ou vincula diretamente uma Feature. A política alcança uma Feature apenas por meio de uma chave que o Manifest associa, e é o Manifest que decide qual Feature é essa.
Uma decisão também não pode remover uma anotação. O seu valor é uma string ou um objeto de subchaves, e um null é recusado, nomeando a injeção, porque null é a forma como um autor exclui um componente de uma anotação que ele herdaria.
Uma string onde a associação roteia três subchaves
governance-monitoring-as-string.yaml vincula policies/monitoring-as-string.rego, que injeta a string "30s" sob a chave de monitoramento. Essa associação roteia três subchaves, e uma string não nomeia nenhuma delas, então
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pullé interrompido, sai com 1 e não escreve nenhum dist/. A política injetou a string em api e em worker, e cada uma é recusada. Cada recusa nomeia o plugin que injetou o valor e o papel em que ele está vinculado, de modo que o valor é rastreado até a política que o decidiu, e não até uma linha da Release que ninguém escreveu:
[… omitted: a warning that the attachment is in the global configuration named with --config][OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")---[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")Sem a política
release.yaml compilado sem nenhuma vinculação de governança,
aggrega build --release release.yaml --auto-pullé interrompido. O seu Component exige uma vinculação core/prometheus-exporter, e nada dá uma a api ou a worker:
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")gateway não é nomeado, porque a sua entrada na Release escreve o seu próprio monitoramento. Com a política vinculada, a mesma Release é compilada: uma vinculação em que uma anotação injetada se expande atende ao requisito, assim como uma escrita à mão.
O que o lockfile registra
Uma vinculação annotation-transform muda o que o build renderiza, então o lockfile a fixa. Depois do build com Rego, release.lock traz a vinculação sob mutators:, com o seu plugin, o seu papel, e o conteúdo e o digest do seu arquivo de política:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.regoEle também fixa o plugin sob plugins::
plugins: - uri: governance/rego [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/rego:0.9.0A vinculação nomeia uma versão que o hub publica, então a fixação é resolvida pelo registry que o workspace lê, ou pelo binário aggrega dessa versão.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example policy-annotation-transformEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd policy-annotation-transformBuild
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullaggrega build --release release.yaml --config governance-cel.yaml --auto-pullaggrega build --release release-by-hand.yaml --auto-pullO catálogo da biblioteca padrão fornece aqui cada Component, Feature, Recipe e FeatureRecipe, e as entidades Plugin dos dois mecanismos. Eles são resolvidos a partir de hub.aggrega.ai, o registry padrão que .aggrega-config.yaml nomeia. Com um checkout do catálogo (onde obter um) nomeado com --catalog, nada é buscado de um registry, então os builds rodam offline. --auto-pull preenche o lockfile de cada Release durante o build. Os lockfiles e a saída renderizada são gerados, não incluídos.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta Workspace ainda não contiver uma pasta `policy-annotation-transform`, chame uma vez a ferramenta `scaffold` com `example` definido como `policy-annotation-transform` e sem `dir`: ela grava o exemplo em uma nova pasta `policy-annotation-transform`. Em seguida, chame a ferramenta `cli-build`, que executa `aggrega build` e aceita a flag `--config` dele, com `workspace_root` definido como `policy-annotation-transform`, `release` definido como `release.yaml`, `auto_pull` definido como true e `config` definido como `governance-rego.yaml`; depois chame-a de novo da mesma forma com `config` definido como `governance-cel.yaml`. Por fim, chame a ferramenta `build` com `workspace_root` definido como `policy-annotation-transform`, `release` definido como `release-by-hand.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `policy-annotation-transform/dist/`.Verificando cada build
Esta autoverificação é executada em um checkout do repositório da documentação, que contém o script auxiliar de build compartilhado que ela usa; uma cópia escrita por aggrega scaffold --example não traz esse script auxiliar.
./check.shcheck.sh faz cinco builds por meio do helper build-release e verifica cada resultado em relação ao que esta página descreve:
release-by-hand.yamlsem política é a referência. Ele precisa renderizar os seis arquivos em que as anotações se expandem.release.yamlsem política precisa ser interrompido comE0162paraapieworker, e para nenhum outro componente.release.yamlcom a política é compilado uma vez em cada mecanismo. Cada build precisa escrever os arquivos da referência byte a byte, fixar o plugin no seu lockfile e registrar os três componentes como injetados por esse plugin.release.yamlcom a string plantada precisa ser interrompido com a recusa acima.
Ele imprime uma linha por build, depois os arquivos que as duas associações renderizaram, e sai com 1 se algum resultado for diferente, imprimindo a saída desse build:
POLICY RELEASE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------none release-by-hand.yaml 0 reference OK: the six attachments' filesnone release.yaml 1 halt OK: E0162 for api and workerrego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedcel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedstring release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml: shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.Cada build roda na sua própria cópia deste workspace, criada em um diretório temporário, com o caminho do catálogo no seu .aggrega-config.yaml tornado absoluto para que ainda seja resolvido a partir dali. Nada neste diretório é escrito. Ele usa o binário que o helper build-release resolve, então AGGREGA_BIN o escolhe, e os argumentos depois de -- chegam a cada build. O seu status de saída é todo o veredito.
Onde o compilador não interpreta
O compilador entrega à política os componentes e as chaves associadas. Ele adiciona as anotações que a política decide e as expande pelas associações do Manifest, como expande qualquer anotação. Ele não sabe que um serviço deveria ser monitorado, o que é um intervalo de scrape ou com qual papel do IAM um componente deveria rodar: esses significados pertencem à política e ao Manifest. Para os papéis, os payloads e as chaves de decisão, veja o socket de governança. Para a expansão de anotações sem política, veja annotation-driven-monitoring.
Arquivos
aggregate.yaml— os três serviços, sem nenhuma anotação.manifest.yaml— associa o tipo de componente e as duas Features às suas Recipes Helm, e as duas chaves de anotação às duas Features.release.yaml— a Release que a política anota; sógatewayescreve uma anotação.release-by-hand.yaml— o controle: cada anotação escrita à mão..aggrega-config.yaml— o registry padrão; nenhuma vinculação de governança.governance-rego.yaml,governance-cel.yaml— a política vinculada emannotation-transformpor meio de cada mecanismo, cada um nomeado com--config.governance-monitoring-as-string.yaml— o erro plantado, nomeado com--config.policies/platform-defaults.rego,policies/platform-defaults.cel— a política, uma vez por mecanismo.policies/monitoring-as-string.rego— o erro plantado.build-release.sh— faz o build de uma Release, exibindo o comandoaggrega buildequivalente.check.sh— faz os cinco builds e verifica cada resultado.