Uma política que anexa Features que ninguém escreveu: anotações injetadas em `annotation-transform`
Uma política de governação dá a cada componente de uma loja a monitorização da plataforma e uma função do AWS IAM. Fá-lo adicionando anotações. O Manifest associa duas chaves de anotação a duas Features, e uma anotação sob uma chave associada expande-se num anexo 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 é anexada no papel annotation-transform, uma vez para cada motor de políticas compilado na CLI: Rego e CEL. A prova central é uma Release de controlo que escreve à mão as mesmas anotações. Compilada sem nenhuma política, renderiza os mesmos ficheiros, byte a byte, que a Release que a política anota.
O que constrói
| instância | Component do catálogo | o que contém em release.yaml |
|---|---|---|
api | example/compute/service | nada |
worker | example/compute/service | nada |
gateway | example/compute/service | a sua própria anotação de monitorização, com um intervalo de 10 segundos |
Os três são compilados para o Kubernetes através do Helm, em dist/shop/helm/. example/compute/service é um Component de demonstração no catálogo da biblioteca padrão. Cada instância sua tem de conter um anexo core/prometheus-exporter, um requisito que o Component declara e a compilação 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 encaminha várias subchaves recebe como valor um objeto que nomeia cada uma delas, pelo que feature.aggrega.ai/monitoring recebe {interval: …, port: …, path: …}. Uma associação que encaminha uma única subchave recebe uma string, pelo que aws-role recebe o ARN da função. O anexo em que uma anotação se expande tem o nome da sua chave. core/aws-irsa dá ao seu ServiceAccount o nome do anexo, e é por isso que essa chave não contém ponto nem barra.
Anexar a política
.aggrega-config.yaml indica o hub como o seu registo, nenhum diretório de catálogo e nenhum anexo de governação. A política é anexada pelo ficheiro que uma compilação nomeia com --config: governance-rego.yaml para o motor Rego, governance-cel.yaml para o motor 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 ficheiro de configuração global para essa execução, em vez daquele que a máquina leria de outro modo, e o .aggrega-config.yaml deste workspace continua a sobrepor-se a ele.
0.9.0 é uma versão em que o hub publica a entidade Plugin de cada motor, pelo que o anexo é resolvido a partir do registo que o workspace lê, ou a partir do binário aggrega dessa versão, que a contém. O motor que é executado é o que está compilado no binário aggrega que executa a compilação, seja qual for a versão que o anexo nomeia. O objeto que a anotação de monitorização recebe precisa de um motor que injete um objeto de subchaves, e os motores das versões anteriores à 0.8.7 não o fazem.
O que uma política annotation-transform lê
Uma política em annotation-transform lê duas coisas:
input.targetslista cada componente que 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 de uma compilação de release.yaml ter preenchido 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 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 só dispara para uma chave em input.binding_keys, pelo que a política não adiciona nada a que um Manifest não tenha dado significado. Cada regra ignora também um destino que já contém a chave. Uma decisão sob uma chave que o componente já contém 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 exprime as mesmas duas decisões como uma única expressão, juntando duas listas com +. Uma chave de mapa é testada com in em vez de object.keys, e o ARN da função é composto com +, uma vez que a linguagem de expressões não tem sprintf. A metade da expressão relativa à função 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 a compilação renderiza
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullescreve doze ficheiros em dist/shop/helm/: um Deployment e um Service para cada componente, o ServiceMonitor em que a sua anotação de monitorização 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 contém interval: 10s, o valor que a sua entrada na Release escreve. O ServiceAccount sob o qual api é executado, 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 ficheiros
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 anexada,
aggrega build --release release-by-hand.yaml --auto-pullescreve os mesmos doze ficheiros, byte a byte, que release.yaml com a política anexada em qualquer um dos dois motores. Nada é excluído dessa comparação: o facto de uma anotação ter sido injetada não fica registado em nenhum ficheiro renderizado. check.sh compara as árvores em cada execução.
A compilação lê um valor injetado exatamente como lê o mesmo valor escrito na Release, pelo que o valor se expande no mesmo anexo.
Onde a injeção fica registada
O grafo de compilação regista-a, e --ir-graph imprime o grafo. Cada componente que recebeu uma anotação injetada contém 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 registo é por componente, não por chave: gateway também o contém, pelo seu aws-role. Cada anexo 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 di-lo. Nesta compilação, 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 altera nada do que a compilação 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 numa decisão adiciona um componente, altera uma etiqueta ou anexa diretamente uma Feature. A política só chega a uma Feature através de uma chave que o Manifest associa, e é o Manifest que decide qual é essa Feature.
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, com o nome da injeção, porque null é a forma como um autor exclui um componente de uma anotação que herdaria.
Uma string onde a associação encaminha três subchaves
governance-monitoring-as-string.yaml anexa policies/monitoring-as-string.rego, que injeta a string "30s" sob a chave de monitorização. Essa associação encaminha três subchaves, e uma string não nomeia nenhuma delas, pelo que
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pullé interrompido, termina 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 está anexado, pelo que o valor é atribuído à política que o decidiu, e não a 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 nenhum anexo de governação,
aggrega build --release release.yaml --auto-pullé interrompido. O seu Component exige um anexo core/prometheus-exporter, e nada dá um 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 a sua própria monitorização. Com a política anexada, a mesma Release é compilada: um anexo em que uma anotação injetada se expande cumpre o requisito, tal como um escrito à mão.
O que o lockfile regista
Um anexo annotation-transform altera o que a compilação renderiza, pelo que o lockfile o fixa. Depois da compilação com Rego, release.lock contém o anexo sob mutators:, com o seu plugin, o seu papel, e o conteúdo e o digest do seu ficheiro de política:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.regoFixa também 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.0O anexo nomeia uma versão que o hub publica, pelo que a fixação é resolvida através do registo que o workspace lê, ou a partir do binário aggrega dessa versão.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example policy-annotation-transformDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd policy-annotation-transformCompilação
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 motores. São resolvidos a partir de hub.aggrega.ai, o registo predefinido que .aggrega-config.yaml nomeia. Com um checkout do catálogo (onde obter um) nomeado com --catalog, nada é obtido de um registo, pelo que as compilações são executadas offline. --auto-pull preenche o lockfile de cada Release durante a compilação. 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-lhe este prompt.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa 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`: esta escreve o exemplo numa nova pasta `policy-annotation-transform`. Em seguida, chame a ferramenta `cli-build`, que executa `aggrega build` e aceita a respetiva flag `--config`, 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 novamente 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. Indique-me que ficheiros cada compilação escreveu; encontram-se em `policy-annotation-transform/dist/`.Verificar cada compilação
Esta autoverificação é executada num checkout do repositório da documentação, que contém o script auxiliar de compilação partilhado que usa; uma cópia escrita por aggrega scaffold --example não inclui esse script auxiliar.
./check.shcheck.sh faz cinco compilações através do helper build-release e verifica cada resultado face ao que esta página descreve:
release-by-hand.yamlsem política é a referência. Tem de renderizar os seis ficheiros em que as anotações se expandem.release.yamlsem política tem de ser interrompido comE0162paraapieworker, e para nenhum outro componente.release.yamlcom a política é compilado uma vez em cada motor. Cada compilação tem de escrever os ficheiros da referência byte a byte, fixar o plugin no seu lockfile e registar os três componentes como injetados por esse plugin.release.yamlcom a string plantada tem de ser interrompido com a recusa acima.
Imprime uma linha por compilação, depois os ficheiros que as duas associações renderizaram, e termina com 1 se algum resultado for diferente, imprimindo a saída dessa compilação:
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 compilação é executada na sua própria cópia deste workspace, criada num diretório temporário, com o caminho do catálogo no seu .aggrega-config.yaml tornado absoluto para que continue a ser resolvido a partir daí. Nada neste diretório é escrito. Usa o binário que o helper build-release resolve, pelo que AGGREGA_BIN o escolhe, e os argumentos depois de -- chegam a cada compilação. O seu estado de saída é todo o veredicto.
Onde o compilador não interpreta
O compilador entrega à política os componentes e as chaves associadas. Adiciona as anotações que a política decide e expande-as através das associações do Manifest, tal como expande qualquer anotação. Não sabe que um serviço deveria ser monitorizado, o que é um intervalo de scrape ou com que função do IAM um componente deveria ser executado: esses significados pertencem à política e ao Manifest. Para os papéis, os payloads e as chaves de decisão, ver o socket de governação. Para a expansão de anotações sem política, ver annotation-driven-monitoring.
Ficheiros
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 controlo: cada anotação escrita à mão..aggrega-config.yaml— o registo predefinido; nenhum anexo de governação.governance-rego.yaml,governance-cel.yaml— a política anexada emannotation-transformatravés de cada motor, 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 motor.policies/monitoring-as-string.rego— o erro plantado.build-release.sh— compila uma Release, mostrando o comandoaggrega buildequivalente.check.sh— faz as cinco compilações e verifica cada resultado.