Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Una policy che associa Features che nessuno ha scritto: annotazioni iniettate in `annotation-transform`

Una policy di governance fornisce a ogni componente di un negozio il monitoraggio della piattaforma e un ruolo AWS IAM. Lo fa aggiungendo annotazioni. Il Manifest lega due chiavi di annotazione a due Features, e un’annotazione sotto una chiave legata si espande in un’associazione di Feature. Così le annotazioni che la policy aggiunge portano a ciascun componente un ServiceMonitor di Prometheus e un ServiceAccount di Kubernetes, e né l’Aggregate né la Release ne scrivono alcuno.

La policy è associata al ruolo annotation-transform, una volta per ciascun motore di policy compilato nella CLI: Rego e CEL. La prova centrale è una Release di controllo che scrive a mano le stesse annotazioni. Compilata senza alcuna policy, renderizza gli stessi file, byte per byte, della Release che la policy annota.

Che cosa costruisce

istanzaComponent del catalogoche cosa porta in release.yaml
apiexample/compute/servicenulla
workerexample/compute/servicenulla
gatewayexample/compute/servicela propria annotazione di monitoraggio, con un intervallo di 10 secondi

Tutti e tre sono compilati per Kubernetes tramite Helm, in dist/shop/helm/. example/compute/service è un Component dimostrativo nel catalogo della libreria standard. Ogni sua istanza deve portare un’associazione core/prometheus-exporter, un requisito che il Component dichiara e il build verifica.

I due binding delle annotazioni

manifest.yaml dà un significato a due chiavi di annotazione:

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

Un binding che instrada più sottochiavi prende come valore un oggetto che le nomina ciascuna, quindi feature.aggrega.ai/monitoring prende {interval: …, port: …, path: …}. Un binding che instrada una sola sottochiave prende una stringa, quindi aws-role prende l’ARN del ruolo. L’associazione in cui un’annotazione si espande prende il nome dalla sua chiave. core/aws-irsa dà al proprio ServiceAccount il nome dell’associazione, ed è per questo che quella chiave non contiene né punti né barre.

Associare la policy

.aggrega-config.yaml indica l’hub come proprio registry e nessuna directory di catalogo, e nessuna associazione di governance. La policy viene associata dal file che un build nomina con --config: governance-rego.yaml per il motore Rego, governance-cel.yaml per il motore CEL. Quello Rego recita:

plugins:
governance:
- uri: governance/rego:0.9.0
role: annotation-transform
with:
sources:
- policies/platform-defaults.rego

--config nomina il file di configurazione globale per quell’esecuzione, al posto di quello che la macchina leggerebbe altrimenti, e il .aggrega-config.yaml di questo workspace vi si sovrappone comunque.

0.9.0 è una versione in cui l’hub pubblica l’entità Plugin di ciascun motore, quindi l’associazione viene risolta dal registry che il workspace legge, oppure dal binario aggrega di quella release, che la contiene. Il motore che viene eseguito è quello compilato nel binario aggrega che esegue il build, qualunque sia la versione che l’associazione nomina. L’oggetto che l’annotazione di monitoraggio prende richiede un motore che inietti un oggetto di sottochiavi, e i motori delle versioni precedenti alla 0.8.7 non lo fanno.

Che cosa legge una policy annotation-transform

Una policy in annotation-transform legge due cose:

  • input.targets elenca ogni componente che può annotare. Ogni target ha un boundary_path, un component_name e le annotations che la Release scrive su quel componente, ciascun valore così come è scritto.
  • input.binding_keys elenca le chiavi di annotazione che il Manifest lega.

aggrega build --release <release> --dry-run --policy-input <dir> scrive in <dir> il payload che ciascun ruolo riceve e non scrive nient’altro. Dopo che un build di release.yaml ha riempito il suo 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"}}}

Le annotations di un target contengono ciò che la Release scrive sul componente stesso. Il valore aggrega.ai/namespace del confine non è tra queste.

La policy

policies/platform-defaults.rego raccoglie una decisione per annotazione sotto annotations. Ogni decisione nomina il target con i due campi sotto cui è stato letto, poi la chiave e il valore:

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)
}

Ogni regola scatta solo per una chiave in input.binding_keys, quindi la policy non aggiunge nulla a cui un Manifest non abbia dato un significato. Ogni regola salta anche un target che porta già la chiave. Una decisione sotto una chiave che il componente porta già sostituisce il valore che la Release ha scritto. Senza quel test, gateway perderebbe il suo intervallo di 10 secondi a favore dei 30 secondi della policy.

policies/platform-defaults.cel esprime le stesse due decisioni come un’unica espressione, unendo due liste con +. Una chiave di mappa viene testata con in anziché con object.keys, e l’ARN del ruolo viene composto con +, poiché il linguaggio delle espressioni non ha sprintf. La metà dell’espressione relativa al ruolo recita:

+ 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,
}),

Che cosa renderizza il build

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

scrive dodici file sotto dist/shop/helm/: un Deployment e un Service per ciascun componente, il ServiceMonitor in cui si espande la sua annotazione di monitoraggio e il ServiceAccount in cui si espande la sua annotazione aws-role. Lo spec del ServiceMonitor di api, dall’annotazione che la policy ha iniettato:

spec:
selector:
matchLabels:
app.kubernetes.io/name: api
endpoints:
- port: metrics
interval: 30s
path: /metrics

Quello di gateway porta interval: 10s, il valore che scrive la sua voce nella Release. Il ServiceAccount con cui viene eseguito api, dall’annotazione aws-role iniettata:

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]

Iniettate o scritte a mano: gli stessi file

release-by-hand.yaml è release.yaml con le annotazioni che la policy inietta scritte a mano su ciascun componente. Compilato senza alcuna policy associata,

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

scrive gli stessi dodici file, byte per byte, di release.yaml con la policy associata sull’uno o sull’altro motore. Nulla è escluso da quel confronto: il fatto che un’annotazione sia stata iniettata non viene registrato in alcun file renderizzato. check.sh confronta gli alberi a ogni esecuzione.

Il build legge un valore iniettato esattamente come legge lo stesso valore scritto nella Release, quindi il valore si espande nella stessa associazione.

Dove viene registrata l’iniezione

Lo registra il grafo di build, e --ir-graph stampa il grafo. Ogni componente che ha ricevuto un’annotazione iniettata porta aggrega.ai/injected-by, che nomina il plugin, tra le sue annotazioni di Release. Dopo aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph, api riporta:

"release_annotations": {
"aggrega.ai/namespace": "shop",
"aws-role": "arn:aws:iam::123456789012:role/shop-api",
"aggrega.ai/injected-by": "governance/rego"
},

La registrazione è per componente, non per chiave: anche gateway la porta, per il suo aws-role. Ogni associazione in cui le annotazioni si sono espanse ha "origin": "annotation" nel grafo, come avverrebbe per un’annotazione scritta a mano.

Il target Helm non renderizza alcuna annotazione aggrega.ai/injected-by, e lo dice. In questo build, ogni componente che ha ricevuto un’iniezione aggiunge tre avvisi all’output. Il primo di quelli di api recita:

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 silenzia quella classe di avvisi e non cambia nulla di ciò che il build scrive.

Il ruolo aggiunge annotazioni, e nient’altro

Una decisione nomina un componente, una chiave di annotazione e il suo valore. Nulla in una decisione aggiunge un componente, cambia un’etichetta o associa direttamente una Feature. La policy raggiunge una Feature solo tramite una chiave che il Manifest lega, ed è il Manifest a decidere quale Feature sia.

Una decisione non può nemmeno rimuovere un’annotazione. Il suo valore è una stringa o un oggetto di sottochiavi, e un null viene rifiutato, con il nome dell’iniezione, perché null è il modo in cui un autore esclude un componente da un’annotazione che erediterebbe.

Una stringa dove il binding instrada tre sottochiavi

governance-monitoring-as-string.yaml associa policies/monitoring-as-string.rego, che inietta la stringa "30s" sotto la chiave di monitoraggio. Quel binding instrada tre sottochiavi, e una stringa non ne nomina nessuna, quindi

Terminal window
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pull

si arresta, esce con 1 e non scrive alcun dist/. La policy ha iniettato la stringa su api e su worker, e ciascuna viene rifiutata. Ogni rifiuto nomina il plugin che ha iniettato il valore e il ruolo a cui è associato, così il valore viene ricondotto alla policy che lo ha deciso, anziché a una riga della Release che nessuno ha scritto:

[… 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")

Senza la policy

release.yaml compilato senza alcuna associazione di governance,

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

si arresta. Il suo Component richiede un’associazione core/prometheus-exporter, e nulla ne fornisce una ad api o 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 non viene nominato, perché la sua voce nella Release scrive il proprio monitoraggio. Con la policy associata, la stessa Release viene compilata: un’associazione in cui si espande un’annotazione iniettata soddisfa il requisito, proprio come una scritta a mano.

Che cosa registra il lockfile

Un’associazione annotation-transform cambia ciò che il build renderizza, quindi il lockfile la fissa. Dopo il build Rego, release.lock contiene l’associazione sotto mutators:, con il suo plugin, il suo ruolo, e il contenuto e il digest del suo file di policy:

mutators:
- plugin: governance/rego
role: annotation-transform
sources:
- content: |
[… omitted: the policy file, as written]
digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b
path: platform-defaults.rego

Fissa anche il plugin sotto 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

L’associazione nomina una versione che l’hub pubblica, quindi il pin si risolve attraverso il registry che il workspace legge, oppure dal binario aggrega di quella release.

Generare l’esempio

Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

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

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

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

Il catalogo della libreria standard fornisce ogni Component, Feature, Recipe e FeatureRecipe usato qui, e le entità Plugin di entrambi i motori. Vengono risolti da hub.aggrega.ai, il registry predefinito che .aggrega-config.yaml nomina. Con un checkout del catalogo (dove ottenerne uno) nominato con --catalog, nulla viene scaricato da un registry, quindi i build vengono eseguiti offline. --auto-pull riempie il lockfile di ciascuna Release durante il build. I lockfile e l’output renderizzato sono generati, non forniti.

Con un assistente AI

Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella Workspace non contiene ancora una cartella `policy-annotation-transform`, chiama una volta lo strumento `scaffold` con `example` impostato a `policy-annotation-transform` e senza `dir`: scrive l’esempio in una nuova cartella `policy-annotation-transform`. Poi chiama lo strumento `cli-build`, che esegue `aggrega build` e accetta il suo flag `--config`, con `workspace_root` impostato a `policy-annotation-transform`, `release` impostato a `release.yaml`, `auto_pull` impostato a true e `config` impostato a `governance-rego.yaml`; poi richiamalo allo stesso modo con `config` impostato a `governance-cel.yaml`. Infine, chiama lo strumento `build` con `workspace_root` impostato a `policy-annotation-transform`, `release` impostato a `release-by-hand.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto ogni build; si trovano in `policy-annotation-transform/dist/`.

Verificare ogni build

Questo controllo automatico viene eseguito in un checkout del repository della documentazione, che contiene lo script di build condiviso che usa; una copia scritta da aggrega scaffold --example non porta con sé quello script.

Terminal window
./check.sh

check.sh esegue cinque build tramite l’helper build-release e verifica ciascun esito rispetto a quello che questa pagina descrive:

  • release-by-hand.yaml senza policy è il riferimento. Deve renderizzare i sei file in cui si espandono le annotazioni.
  • release.yaml senza policy deve arrestarsi con E0162 per api e worker, e per nessun altro componente.
  • release.yaml con la policy viene compilato una volta su ciascun motore. Ogni build deve scrivere byte per byte i file del riferimento, fissare il plugin nel proprio lockfile e registrare tutti e tre i componenti come iniettati da quel plugin.
  • release.yaml con la stringa piazzata deve arrestarsi con il rifiuto descritto sopra.

Stampa una riga per build, poi i file che i due binding hanno renderizzato, ed esce con 1 se un esito differisce, stampando l’output di quel 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.

Ogni build viene eseguito in una propria copia di questo workspace, creata in una directory temporanea, con il percorso del catalogo nel suo .aggrega-config.yaml reso assoluto, così che si risolva ancora da lì. In questa directory non viene scritto nulla. Usa il binario che l’helper build-release risolve, quindi AGGREGA_BIN lo sceglie, e gli argomenti dopo -- arrivano a ogni build. Il suo stato di uscita è l’intero verdetto.

Dove il compilatore non interpreta

Il compilatore passa alla policy i componenti e le chiavi legate. Aggiunge le annotazioni che la policy decide e le espande attraverso i binding del Manifest come espande qualsiasi annotazione. Non sa che un servizio dovrebbe essere monitorato, che cos’è un intervallo di scrape o con quale ruolo IAM un componente dovrebbe essere eseguito: quei significati appartengono alla policy e al Manifest. Per i ruoli, i payload e le chiavi di decisione, vedi il socket di governance. Per l’espansione delle annotazioni senza policy, vedi annotation-driven-monitoring.

File

  • aggregate.yaml — i tre servizi, senza alcuna annotazione.
  • manifest.yaml — lega il tipo di componente e le due Features alle loro Recipes Helm, e le due chiavi di annotazione alle due Features.
  • release.yaml — la Release che la policy annota; solo gateway scrive un’annotazione.
  • release-by-hand.yaml — il controllo: ogni annotazione scritta a mano.
  • .aggrega-config.yaml — il registry predefinito; nessuna associazione di governance.
  • governance-rego.yaml, governance-cel.yaml — la policy associata in annotation-transform tramite ciascun motore, ciascuno nominato con --config.
  • governance-monitoring-as-string.yaml — l’errore piazzato, nominato con --config.
  • policies/platform-defaults.rego, policies/platform-defaults.cel — la policy, una volta per motore.
  • policies/monitoring-as-string.rego — l’errore piazzato.
  • build-release.sh — esegue il build di una Release, mostrando il comando aggrega build equivalente.
  • check.sh — esegue i cinque build e verifica ciascun esito.