Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Une politique qui rattache des Features que personne n’a écrites : des annotations injectées à `annotation-transform`

Une politique de gouvernance donne à chaque composant d’une boutique la surveillance de la plateforme et un rôle AWS IAM. Elle le fait en ajoutant des annotations. Le Manifest lie deux clés d’annotation à deux Features, et une annotation sous une clé liée se développe en un rattachement de Feature. Ainsi, les annotations que la politique ajoute apportent à chaque composant un ServiceMonitor Prometheus et un ServiceAccount Kubernetes, et ni l’Aggregate ni la Release n’écrivent l’un ou l’autre.

La politique est rattachée au rôle annotation-transform, une fois pour chaque moteur de politiques compilé dans la CLI : Rego et CEL. La preuve centrale est une Release témoin qui écrit les mêmes annotations à la main. Construite sans aucune politique, elle rend les mêmes fichiers, octet par octet, que la Release que la politique annote.

Ce qu’il construit

instanceComponent du cataloguece qu’elle porte dans release.yaml
apiexample/compute/servicerien
workerexample/compute/servicerien
gatewayexample/compute/servicesa propre annotation de surveillance, avec un intervalle de 10 secondes

Les trois sont compilés pour Kubernetes via Helm, dans dist/shop/helm/. example/compute/service est un Component de démonstration du catalogue de la bibliothèque standard. Chacune de ses instances doit porter un rattachement core/prometheus-exporter, une exigence que le Component énonce et que le build vérifie.

Les deux liaisons d’annotations

manifest.yaml donne un sens à deux clés d’annotation :

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

Une liaison qui achemine plusieurs sous-clés prend comme valeur un objet qui nomme chacune d’elles, si bien que feature.aggrega.ai/monitoring prend {interval: …, port: …, path: …}. Une liaison qui achemine une seule sous-clé prend une chaîne, si bien que aws-role prend l’ARN du rôle. Le rattachement en lequel une annotation se développe porte le nom de sa clé. core/aws-irsa nomme son ServiceAccount d’après le rattachement, c’est pourquoi cette clé ne contient ni point ni barre oblique.

Rattacher la politique

.aggrega-config.yaml désigne le hub comme registre, aucun répertoire de catalogue et aucun rattachement de gouvernance. La politique est rattachée par le fichier qu’un build nomme avec --config : governance-rego.yaml pour le moteur Rego, governance-cel.yaml pour le moteur CEL. Celui de Rego se lit ainsi :

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

--config nomme le fichier de configuration global pour cette exécution, à la place de celui que la machine lirait sinon, et le .aggrega-config.yaml de ce workspace se superpose toujours à lui.

0.9.0 est une version à laquelle le hub publie l’entité Plugin de chaque moteur, si bien que le rattachement est résolu depuis le registre que lit le workspace, ou depuis le binaire aggrega de cette version, qui la porte. Le moteur qui s’exécute est celui compilé dans le binaire aggrega qui exécute le build, quelle que soit la version que nomme le rattachement. L’objet que prend l’annotation de surveillance nécessite un moteur qui injecte un objet de sous-clés, et les moteurs des versions antérieures à 0.8.7 ne le font pas.

Ce que lit une politique annotation-transform

Une politique à annotation-transform lit deux choses :

  • input.targets liste chaque composant qu’elle peut annoter. Chaque cible a un boundary_path, un component_name et les annotations que la Release écrit sur ce composant, chaque valeur telle qu’elle est écrite.
  • input.binding_keys liste les clés d’annotation que le Manifest lie.

aggrega build --release <release> --dry-run --policy-input <dir> écrit dans <dir> la charge utile que reçoit chaque rôle et n’écrit rien d’autre. Une fois qu’un build de release.yaml a rempli son 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"}}}

Les annotations d’une cible contiennent ce que la Release écrit sur le composant lui-même. La valeur aggrega.ai/namespace de la frontière n’en fait pas partie.

La politique

policies/platform-defaults.rego rassemble une décision par annotation sous annotations. Chaque décision nomme la cible par les deux champs sous lesquels elle a été lue, puis la clé et la valeur :

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

Chaque règle ne se déclenche que pour une clé de input.binding_keys, si bien que la politique n’ajoute rien à quoi un Manifest n’a pas donné de sens. Chaque règle ignore aussi une cible qui porte déjà la clé. Une décision sous une clé que le composant porte déjà remplace la valeur que la Release a écrite. Sans ce test, gateway perdrait son intervalle de 10 secondes au profit des 30 secondes de la politique.

policies/platform-defaults.cel énonce les deux mêmes décisions sous forme d’une seule expression, en joignant deux listes avec +. Une clé de map est testée avec in plutôt qu’avec object.keys, et l’ARN du rôle est assemblé avec +, car le langage d’expressions n’a pas de sprintf. La moitié de l’expression consacrée au rôle se lit ainsi :

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

Ce que le build rend

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

écrit douze fichiers sous dist/shop/helm/ : un Deployment et un Service pour chaque composant, le ServiceMonitor en lequel se développe son annotation de surveillance, et le ServiceAccount en lequel se développe son annotation aws-role. Le spec du ServiceMonitor de api, issu de l’annotation que la politique a injectée :

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

Celui de gateway porte interval: 10s, la valeur qu’écrit son entrée dans la Release. Le ServiceAccount sous lequel api s’exécute, issu de l’annotation aws-role injectée :

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]

Injectées ou écrites à la main : les mêmes fichiers

release-by-hand.yaml est release.yaml avec les annotations que la politique injecte écrites à la main sur chaque composant. Construit sans aucune politique rattachée,

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

il écrit les mêmes douze fichiers, octet par octet, que release.yaml avec la politique rattachée sur l’un ou l’autre moteur. Rien n’est exclu de cette comparaison : le fait qu’une annotation ait été injectée n’est consigné dans aucun fichier rendu. check.sh compare les arborescences à chaque exécution.

Le build lit une valeur injectée exactement comme il lit la même valeur écrite dans la Release, si bien que la valeur se développe en le même rattachement.

Où l’injection est consignée

Le graphe de build la consigne, et --ir-graph affiche le graphe. Chaque composant qui a reçu une annotation injectée porte aggrega.ai/injected-by, qui nomme le plugin, parmi ses annotations de Release. Après aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph, api se lit ainsi :

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

L’enregistrement est par composant, et non par clé : gateway le porte aussi, pour son aws-role. Chaque rattachement en lequel les annotations se sont développées a "origin": "annotation" dans le graphe, comme ce serait le cas pour une annotation écrite à la main.

La cible Helm ne rend aucune annotation aggrega.ai/injected-by, et elle le dit. Dans ce build, chaque composant qui a reçu une injection ajoute trois avertissements à la sortie. Le premier de ceux de api se lit ainsi :

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 fait taire cette classe d’avertissements et ne change rien à ce que le build écrit.

Le rôle ajoute des annotations, et rien d’autre

Une décision nomme un composant, une clé d’annotation et sa valeur. Rien dans une décision n’ajoute un composant, ne change une étiquette ou ne rattache directement une Feature. La politique n’atteint une Feature que par une clé que le Manifest lie, et c’est le Manifest qui décide de quelle Feature il s’agit.

Une décision ne peut pas non plus supprimer une annotation. Sa valeur est une chaîne ou un objet de sous-clés, et un null est refusé, en nommant l’injection, car null est la façon dont un auteur exclut un composant d’une annotation dont il hériterait.

Une chaîne là où la liaison achemine trois sous-clés

governance-monitoring-as-string.yaml rattache policies/monitoring-as-string.rego, qui injecte la chaîne "30s" sous la clé de surveillance. Cette liaison achemine trois sous-clés, et une chaîne n’en nomme aucune, si bien que

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

s’arrête, se termine avec 1 et n’écrit aucun dist/. La politique a injecté la chaîne sur api et sur worker, et chacune est refusée. Chaque refus nomme le plugin qui a injecté la valeur et le rôle auquel il est rattaché, si bien que la valeur est ramenée à la politique qui l’a décidée, plutôt qu’à une ligne de la Release que personne n’a écrite :

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

Sans la politique

release.yaml construit sans aucun rattachement de gouvernance,

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

s’arrête. Son Component exige un rattachement core/prometheus-exporter, et rien n’en donne un à api ni à 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’est pas nommé, car son entrée dans la Release écrit sa propre surveillance. Avec la politique rattachée, la même Release se construit : un rattachement en lequel se développe une annotation injectée satisfait l’exigence, tout comme un rattachement écrit à la main.

Ce qu’enregistre le lockfile

Un rattachement annotation-transform change ce que le build rend, si bien que le lockfile l’épingle. Après le build Rego, release.lock porte le rattachement sous mutators:, avec son plugin, son rôle, ainsi que le contenu et le digest de son fichier de politique :

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

Il épingle aussi le plugin sous 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

Le rattachement nomme une version que le hub publie, si bien que l’épinglage se résout via le registre que lit le workspace, ou depuis le binaire aggrega de cette version.

Générer l’exemple

Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

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

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

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

Le catalogue de la bibliothèque standard fournit ici chaque Component, Feature, Recipe et FeatureRecipe, ainsi que les entités Plugin des deux moteurs. Ils sont résolus depuis hub.aggrega.ai, le registre par défaut que nomme .aggrega-config.yaml. Avec un checkout du catalogue (où en obtenir un) nommé avec --catalog, rien n’est récupéré depuis un registre, si bien que les builds s’exécutent hors ligne. --auto-pull remplit le lockfile de chaque Release pendant le build. Les lockfiles et la sortie rendue sont générés, et non livrés.

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier Workspace ne contient pas encore de dossier `policy-annotation-transform`, appelez une fois l’outil `scaffold` avec `example` défini sur `policy-annotation-transform` et sans `dir` : il écrit l’exemple dans un nouveau dossier `policy-annotation-transform`. Appelez ensuite l’outil `cli-build`, qui exécute `aggrega build` et accepte son option `--config`, avec `workspace_root` défini sur `policy-annotation-transform`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `config` défini sur `governance-rego.yaml` ; puis appelez-le de nouveau de la même façon avec `config` défini sur `governance-cel.yaml`. Enfin, appelez l’outil `build` avec `workspace_root` défini sur `policy-annotation-transform`, `release` défini sur `release-by-hand.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `policy-annotation-transform/dist/`.

Vérifier chaque build

Cette auto-vérification s’exécute dans un checkout du dépôt de la documentation, qui contient l’utilitaire de build partagé qu’elle utilise ; une copie écrite par aggrega scaffold --example ne contient pas cet utilitaire.

Terminal window
./check.sh

check.sh effectue cinq builds via l’assistant build-release et vérifie chaque résultat par rapport à celui que décrit cette page :

  • release-by-hand.yaml sans politique est la référence. Il doit rendre les six fichiers en lesquels les annotations se développent.
  • release.yaml sans politique doit s’arrêter avec E0162 pour api et worker, et pour aucun autre composant.
  • release.yaml avec la politique est construit une fois sur chaque moteur. Chaque build doit écrire les fichiers de la référence octet par octet, épingler le plugin dans son lockfile, et consigner les trois composants comme injectés par ce plugin.
  • release.yaml avec la chaîne piégée doit s’arrêter avec le refus ci-dessus.

Il affiche une ligne par build, puis les fichiers que les deux liaisons ont rendus, et se termine avec 1 si un résultat diffère, en affichant la sortie de ce 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.

Chaque build s’exécute dans sa propre copie de ce workspace, créée dans un répertoire temporaire, avec le chemin du catalogue dans son .aggrega-config.yaml rendu absolu afin qu’il se résolve toujours depuis cet emplacement. Rien n’est écrit dans ce répertoire. Il utilise le binaire que résout l’assistant build-release, si bien que AGGREGA_BIN le choisit, et les arguments après -- parviennent à chaque build. Son code de sortie constitue tout le verdict.

Là où le compilateur n’interprète pas

Le compilateur remet à la politique les composants et les clés liées. Il ajoute les annotations que la politique décide, et les développe via les liaisons du Manifest comme il développe toute annotation. Il ne sait pas qu’un service devrait être surveillé, ce qu’est un intervalle de scrape, ni sous quel rôle IAM un composant devrait s’exécuter : ces significations appartiennent à la politique et au Manifest. Pour les rôles, les charges utiles et les clés de décision, voir le socket de gouvernance. Pour le développement des annotations sans politique, voir annotation-driven-monitoring.

Fichiers

  • aggregate.yaml — les trois services, sans aucune annotation.
  • manifest.yaml — lie le type de composant et les deux Features à leurs Recipes Helm, et les deux clés d’annotation aux deux Features.
  • release.yaml — la Release que la politique annote ; seul gateway écrit une annotation.
  • release-by-hand.yaml — le témoin : chaque annotation écrite à la main.
  • .aggrega-config.yaml — le registre par défaut ; aucun rattachement de gouvernance.
  • governance-rego.yaml, governance-cel.yaml — la politique rattachée à annotation-transform via chaque moteur, chacun nommé avec --config.
  • governance-monitoring-as-string.yaml — l’erreur piégée, nommée avec --config.
  • policies/platform-defaults.rego, policies/platform-defaults.cel — la politique, une fois par moteur.
  • policies/monitoring-as-string.rego — l’erreur piégée.
  • build-release.sh — construit une Release, en affichant la commande aggrega build équivalente.
  • check.sh — effectue les cinq builds et vérifie chaque résultat.