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

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ânciaComponent do catálogoo que ela traz em release.yaml
apiexample/compute/servicenada
workerexample/compute/servicenada
gatewayexample/compute/servicea 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_arn

Uma 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.targets lista cada componente que ela pode anotar. Cada destino tem um boundary_path, um component_name e as annotations que a Release escreve nesse componente, cada valor tal como está escrito.
  • input.binding_keys lista 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:

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -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

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull

escreve 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: /metrics

O 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: v1
kind: ServiceAccount
metadata:
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,

Terminal window
aggrega build --release release-by-hand.yaml --auto-pull

ele 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

Terminal window
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,

Terminal window
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.rego

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

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

Terminal window
aggrega scaffold --example policy-annotation-transform

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd policy-annotation-transform

Build

Terminal window
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release.yaml --config governance-cel.yaml --auto-pull
aggrega build --release release-by-hand.yaml --auto-pull

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

Terminal window
./check.sh

check.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.yaml sem política é a referência. Ele precisa renderizar os seis arquivos em que as anotações se expandem.
  • release.yaml sem política precisa ser interrompido com E0162 para api e worker, e para nenhum outro componente.
  • release.yaml com 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.yaml com 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' files
none release.yaml 1 halt OK: E0162 for api and worker
rego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
cel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injected
string 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ó gateway escreve 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 em annotation-transform por 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 comando aggrega build equivalente.
  • check.sh — faz os cinco builds e verifica cada resultado.