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

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

Uma 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.targets lista cada componente que 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 de uma compilação de release.yaml ter preenchido 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 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

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

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

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

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

escreve 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

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

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

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

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

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd policy-annotation-transform

Compilação

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

Terminal window
./check.sh

check.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.yaml sem política é a referência. Tem de renderizar os seis ficheiros em que as anotações se expandem.
  • release.yaml sem política tem de ser interrompido com E0162 para api e worker, e para nenhum outro componente.
  • release.yaml com 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.yaml com 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' 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 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ó gateway escreve 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 em annotation-transform atravé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 comando aggrega build equivalente.
  • check.sh — faz as cinco compilações e verifica cada resultado.