Le bloc `assertions:`
Component, Feature, Recipe et FeatureRecipe portent un champ facultatif spec.assertions: — une map de règles nommées que le compilateur évalue après la validation du schéma mais avant le rendu. Chaque clé est un identifiant de règle qui apparaît dans le message d’échec ; chaque valeur est un corps de template Go. Un corps de template unique écrit directement sous assertions: n’a pas la forme du champ et est rejeté lorsque l’entité est lue, de sorte que chaque règle est rédigée sous un nom qui lui est propre. Le bloc exprime des règles inter-champs que JSON Schema ne peut pas capturer de manière compacte : des invariants impliquant plusieurs champs où aucun champ unique n’est « celui qui est validé ». Cette page couvre la grammaire de rédaction, la phase d’évaluation, le contexte du template et la répartition des responsabilités entre les assertions de Component / Feature (invariants architecturaux du contrat) et les assertions de Recipe / FeatureRecipe (invariants d’implémentation du fournisseur précis).
Pour les contraintes par champ (plage, motif, enum, format), utilisez les mots-clés natifs de JSON Schema dans schema:. Pour les prédicats personnalisés par champ, utilisez le champ validate: de la forme compacte. Pour une forme conditionnelle, utilisez when:. Le champ assertions: les complète — c’est le lieu des véritables règles inter-champs.
Où le champ apparaît
Les quatre entités qui peuvent porter assertions: :
- Component — invariants architecturaux du contrat du Component.
- Feature — invariants architecturaux du contrat de la Feature.
- Recipe — invariants d’implémentation du chart ou du module sous-jacent de la Recipe.
- FeatureRecipe — invariants d’implémentation du mécanisme sous-jacent de la FeatureRecipe.
Le champ est facultatif sur chacune. Les entités sans règles inter-champs omettent entièrement le champ.
Quand les assertions s’exécutent
Les phases d’évaluation des assertions se situent entre la validation du schéma et le rendu dans le pipeline de compilation :
- Résolution : validation et interpolation des paramètres, puis validation du schéma par rapport à
schema:/usesSchema:/featuresSchema:. - Construction de la topologie et finalisation du graphe : le graphe est assemblé.
- Analyse statique : le sélecteur de chaque socket
uses:est vérifié par rapport aux labels des composants qu’atteignent ses connexions. - Assertions de Component / Feature évaluées par rapport à chaque instance.
- Liaison de la Recipe.
- Assertions de Recipe / FeatureRecipe évaluées par rapport à l’instance liée.
- Rendu : templates de mappage évalués, sortie produite.
Les deux phases d’assertion s’exécutent avant tout rendu — aucun chart rendu, aucun fichier Compose généré. La seule chose que l’on demande à un fournisseur avant que les assertions de la Recipe s’exécutent est le nom qu’il donne aux ressources de chaque nœud lié, que le provides d’une Recipe peut lire. Une assertion en échec arrête immédiatement le build avec le message d’erreur spécifique de l’assertion ; les étapes suivantes ne s’exécutent pas.
La séparation entre les deux phases reflète la répartition des responsabilités : les règles de niveau Component s’appliquent quelle que soit la Recipe liée, elles se déclenchent donc avant la liaison ; les règles de niveau Recipe s’appliquent étant donné un choix de Recipe précis, elles se déclenchent donc après la liaison.
Le contexte de template
Pour les assertions: de Component et de Feature, le contexte de template expose l’état résolu de l’instance :
.values— le contenuvaluesdu développeur..infra— le contenuinfrades Ops (provenant de l’Aggregate ou de la Release)..uses— les connexionsuses:résolues, chacune déjà vérifiée par rapport au sélecteur de son socket, dans la forme où l’auteur les écrit : indexées par nom de socket et, sous chaque socket, par l’alias de chaque connexion qui s’y trouve — le nom que l’auteur a donné à la connexion sous le socket ou, pour une connexion écrite comme entrée de liste, sa cible. L’entrée de chaque connexion décrit la connexion et ne porte rien de ce que sa cible a publié.targetest l’identifiant d’instance de la cible résolue,aliasrépète le nom sous lequel l’entrée est indexée, etorigin_featureest présent lorsqu’un rattachement de Feature a tracé la connexion. À côté d’eux se trouvent trois faits, sous les noms par lesquels un template de Recipe les lit dans l’entrée.context.uses.<alias>de la même connexion, où template-context-contract.md décrit ce que contient chacun :labels— les labels de la cible, jamais les labels du composant sur lequel l’assertion s’exécute —values, les valeurs écrites sur la connexion, etfeatures, les rattachements écrits sur la connexion, indexés par le slot que chacun occupe. Chacun des trois est présent sur chaque connexion, vide là où la connexion n’en porte aucun, et un rattachement sousfeaturesa la forme que.featuresdonne à un rattachement plus bas. Ainsi.uses.<socket>.<alias>.targetlit la cible résolue d’une connexion,.uses.<socket>.<alias>.labelsles labels de cette cible, un socket qui contient plusieurs connexions contient une entrée pour chacune, et une référence qui passe par cette map pour atteindre une valeur publiée par la cible arrête le build, car l’entrée ne porte aucun champ de ce type..features— les rattachements résolus, indexés par le nom d’instance que l’auteur a donné à chacun. Chaque entrée portetype(l’URI de catalogue de la Feature rattachée),resolved_version(la version liée pour ce build) etvalues(le contenu d’intention du développeur propre au rattachement). Un rattachement écrit sur l’une des connexions du composant n’en fait pas partie, exactement comme il ne fait pas partie des.featuresd’un template de Recipe : il est lu sous sa connexion, à.uses.<socket>.<alias>.features.<slot>, dans cette même forme..metadata— l’instance en cours d’évaluation : soninstance_id, son typecomponentet saresolved_version, sonboundary_path, ainsi queaggregate_name,aggregate_versionetrelease_versiondu build.
Pour les assertions: de Recipe et de FeatureRecipe, le contexte ajoute des champs propres à la Recipe :
.provides— les valeursprovides:résolues du composant en cours d’évaluation, déjà calculées au moment où l’assertion s’exécute. Les valeurs publiées d’une cible ne se trouvent pas sur cette surface ; elles parviennent plutôt à un appelant dans le contexte de rendu..locals— les locals de la Recipe..recipe.metadata— lenameet laversionde la Recipe, ainsi que sacapability..recipe.source— le pointeur de source de la Recipe.
L’accès aux champs utilise la syntaxe standard des templates Go (.values.architecture, .uses.databases.primary.target) ; la construction qui arrête le build est {{ fail "message" }}, conformément au contrat Loud Guardrails — une assertion échouée produit une erreur claire et précise au moment du build, qui nomme l’invariant violé.
Cette surface s’évalue avec missingkey=error. Une référence à une clé que le contexte ne porte pas arrête le build — en nommant l’entité, l’instance, l’assertion et la clé absente — au lieu d’être rendue comme rien. Cette rigueur est ce qui rend une assertion digne de confiance : un prédicat dont la référence serait rendue vide comparerait avec rien et réussirait, de sorte qu’une seule faute de frappe retirerait silencieusement la règle que l’assertion a été écrite pour faire respecter. Cela signifie aussi que la référence nue se résout avant qu’un repli puisse s’exécuter, de sorte qu’un champ facultatif a besoin d’une forme qui tient compte de la présence ; errors/fatal-halts.md donne la politique de clé manquante propre à chaque surface et les formes qui fonctionnent avec elle.
Lire les connexions d’un socket. L’entrée d’un socket a une seule forme, quoi qu’elle contienne : une entrée par connexion, sous son alias. Une assertion lit une connexion par son alias, compte ou parcourt le socket pour voir chacune de ses connexions, et teste la clé propre du socket pour demander s’il est câblé ou non. Étant donné un composant dont l’entrée dans l’Aggregate écrit
uses: models: local: { target: llama } fast: { target: turbo }ces assertions la lisent de chaque façon :
assertions: # The socket's presence: the socket key alone, however many connections it holds. models-wired: | {{- if not (hasKey .uses "models") -}} {{- fail "wire at least one model to the models socket" -}} {{- end -}} # Every connection on the socket: a range visits each one. every-model-distinct: | {{- $seen := list -}} {{- range $alias, $connection := (optional .uses "models" dict) -}} {{- if has $connection.target $seen -}} {{- fail (printf "connection %s points at %s, which another models connection already points at" $alias $connection.target) -}} {{- end -}} {{- $seen = append $seen $connection.target -}} {{- end -}} # One connection, by the alias it was written under; guarded, because the # connection is optional. fast-is-not-local: | {{- with (optional .uses "models" dict) -}} {{- if and (hasKey . "fast") (hasKey . "local") (eq .fast.target .local.target) -}} {{- fail (printf "the fast and local connections both point at %s" .local.target) -}} {{- end -}} {{- end -}}Une boucle range parcourt les connexions d’un socket dans l’ordre alphabétique de leurs alias — ici fast avant local — et non dans l’ordre où l’Aggregate les a écrites. Un socket qui contient une seule connexion se lit de la même manière : .uses.models.local.target lit llama, que fast soit câblé à côté ou non, et .uses.models.target n’adresse aucune connexion et arrête le build.
Chaque connexion que détient un composant a ici sa propre entrée, car deux connexions d’un même composant ne partagent jamais un alias — sur un socket ou sur deux, quel que soit le document ou le rattachement qui a tracé chacune. Le build refuse une telle paire, en nommant les deux connexions et l’endroit où chacune a été écrite, avant qu’aucune assertion ne s’exécute. Une liste qui nomme deux fois la même cible est une telle paire, puisque l’alias d’une entrée de liste est sa cible ; il en va de même de la connexion local propre à un composant à côté de la connexion local d’un rattachement sur le même composant.
Lire ce que porte une connexion. Une règle sur une connexion peut lire ce qu’est sa cible, ce que le développeur a écrit sur la connexion et ce qui y est rattaché, de sorte qu’elle tient quelle que soit la Recipe liée. Un Component dont le socket models déclare une valeur unauthenticated et un slot credential peut refuser une connexion vers une cible que son catalogue étiquette comme service hébergé lorsque cette connexion ne porte ni informations d’identification ni l’opt-out :
assertions: hosted-model-needs-a-credential: | {{- range $alias, $connection := (optional .uses "models" dict) -}} {{- $hosted := eq (optional $connection.labels "component.aggrega.ai/hosting" "") "managed" -}} {{- $optedOut := optional $connection.values "unauthenticated" false -}} {{- if and $hosted (not (hasKey $connection.features "credential")) (not $optedOut) -}} {{- fail (printf "the models connection %s reaches a hosted model with no credential: attach one under credential, or set unauthenticated: true on the connection" $alias) -}} {{- end -}} {{- end -}}Le label est lu dans labels, qui sont ceux de la cible — le modèle — et jamais ceux du composant lui-même ; l’opt-out est lu dans les values de la connexion ; et les informations d’identification sont un slot sous les features de la connexion. Chacun est lu avec optional ou hasKey, car une cible peut ne porter aucun label de ce type et une connexion aucune valeur de ce type. Ce que signifie le label relève de la convention du catalogue : le build porte la chaîne et l’assertion décide de ce qu’elle signifie.
Le .uses d’une assertion n’est pas le .context.uses d’un template de Recipe, et une référence écrite pour l’un ne se transpose pas à l’autre. Le contexte de rendu porte une projection plus riche des mêmes arêtes : indexée par alias seul, avec le nom du socket comme champ de l’entrée, et avec les valeurs publiées de chaque cible imbriquées sous provides — de sorte qu’un template de Recipe lit .context.uses.<alias>.provides.<name> là où une assertion lit .uses.<socket>.<alias>.target. Les faits que portent les deux vues partagent leurs noms mais pas leurs chemins : .context.uses.<alias>.labels et .uses.<socket>.<alias>.labels sont les labels de la même cible, et values et features lisent de même la même connexion dans l’une ou l’autre. Les deux phases d’assertion s’évaluent avant le rendu, c’est pourquoi la vue qu’une assertion a d’une arête ne porte rien de ce que sa cible a publié, et pourquoi un rattachement sur celle-ci ne porte aucun provides.
Pour la forme plus large du contexte de template et la sémantique de disponibilité par champ, voir template-context-contract.md.
Nombres sur cette surface
Une assertion lit un nombre écrit par l’auteur exactement comme le fait un template de valeur — voir Nombres dans un template de valeur :
- Comparaisons. Les six comparaisons lisent deux nombres par leur valeur, quel que soit le type qui porte chacun :
lt .values.replicas 1.5eteq .values.replicas 3.0répondent ici comme sur un template de valeur, un0.1écrit par l’auteur esteqà un0.1écrit dans l’assertion, et comparer un nombre avec un texte entre guillemets arrête le build dans les mêmes termes. - Vacuité. Un
0écrit par l’auteur est vide : faux pourifetwith, vrai pourempty, et remplacé pardefault. Une règle qui demande si l’auteur a écrit une valeur — un0compris — le demande avec les helpers de présence : pour un0écrit par l’auteur,hasKey .values "replicas"est vrai etoptional .values "replicas" 1renvoie0. Une règle qui demande si la valeur vaut zéro compare :eq .values.replicas 0. Présence et vacuité met les deux questions côte à côte. - Affichage. Un nombre qu’un message
failaffiche se lit comme il se lirait dans la sortie d’un template de valeur : un nombre entier en entier, de sorte queprintf "%d"en affiche les chiffres, et tout autre nombre dans sa forme décimale exacte la plus courte, de sorte qu’un0.0000001écrit par l’auteur se lit0.0000001.
Assertions de Component / Feature — invariants architecturaux
Celles-ci expriment des règles qui valent quelle que soit la Recipe qui lie le Component. La règle est une propriété du contrat, non de l’implémentation.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-server component.aggrega.ai/category: datastorespec: schema: values: architecture: { type: string, enum: [standalone, replication], default: standalone } primary: replicaCount: { type: integer, min: 1, max: 9, default: 1 } secondary: replicaCount: { type: integer, min: 0, max: 9, default: 0 }
assertions: # Replication mode requires at least 2 secondary replicas. replication-needs-two-secondaries: | {{- if eq .values.architecture "replication" -}} {{- if lt .values.secondary.replicaCount 2 -}} {{- fail "architecture=replication requires secondary.replicaCount >= 2" -}} {{- end -}} {{- end -}}
# Total node count limit for safe replication coordination. total-node-count-within-cap: | {{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}} {{- if gt $total 9 -}} {{- fail (printf "total node count must not exceed 9; got %d" $total) -}} {{- end -}}Les deux règles expriment des propriétés du contrat MariaDB. Quelle que soit la Recipe liée — un chart Bitnami, une alternative faite maison — les règles s’appliquent.
Le contrôle des espaces {{- ... -}} compte : les templates d’assertions ne produisent pas de sortie, seulement des effets de bord via {{ fail }}. La suppression des espaces garde vide le corps du template rendu en cas de succès.
Assertions de Recipe / FeatureRecipe — invariants d’implémentation
Celles-ci expriment des règles qui valent pour le chart ou le module précis dont la Recipe tire sa source. La règle est une propriété de l’implémentation, non du contrat.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: bitnami/datastore/mariadb/k8s version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:^1.0.0 source: # Keys this provider defines for itself; a source the build fetches is written as { kind, url, version } instead. chart: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0"
valuesMapping: $import: BitnamiHelpers#/mappings/MariaDBBitnamiCore
assertions: # Bitnami chart 20.x requires an explicit ServiceMonitor namespace when # replication and metrics scraping are both enabled. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}
# ARM-node incompatibility. arm-rejects-hard-anti-affinity: | {{- if and (eq .values.primary.podAntiAffinityPreset "hard") (eq .infra.cpu_arch "arm64") -}} {{- fail "Bitnami MariaDB 20.x is incompatible with ARM nodes when podAntiAffinityPreset=hard; use 'soft' or omit" -}} {{- end -}}Chaque règle est propre à l’implémentation du chart Bitnami 20.x. Si une autre Recipe MariaDB est liée — un chart fait maison, une implémentation alternative — ces règles ne s’appliquent pas. Les règles de niveau Component (replication-needs-two-secondaries, total-node-count-within-cap) s’appliquent toujours, car ce sont des propriétés du contrat.
Pourquoi les assertions de Component et de Recipe sont séparées
Les deux rôles se ressemblent (tous deux exécutent des arrêts {{ fail }} sur des règles inter-champs), mais la répartition des responsabilités est porteuse :
- Les assertions de Component font partie du contrat. Lorsque le développeur écrit
architecture: replicationavecsecondary.replicaCount: 1, le build refuse quelle que soit la Recipe liée. Une future Recipe alternative n’y change rien. - Les assertions de Recipe font partie de l’implémentation. Lorsque l’architecte choisit le chart Bitnami 20.x comme Recipe, le chart a des particularités spécifiques (l’exigence
serviceMonitor.namespace, le bogue des nœuds ARM). Celles-ci ne s’appliquent pas à un autre chart.
Regrouper les deux types de règles sur le Component enchevêtrerait le contrat et ses implémentations : le Component devrait faire référence à sa Recipe liée pour savoir quelles règles d’implémentation faire respecter, ce qui romprait la séparation Component-Recipe. Répartir les règles à leur emplacement naturel garde le modèle de responsabilité propre. Le coût d’exécution de cette répartition est négligeable ; les deux phases s’exécutent avant le rendu et s’arrêtent avec le même diagnostic Loud Guardrails, E0033, qui nomme l’entité, l’instance et la règle.
La convention des messages fail
L’argument de {{ fail "..." }} est l’erreur de build présentée à l’utilisateur. Conventions :
- Nommer la contrainte — « architecture=replication requires secondary.replicaCount >= 2 » (architecture=replication exige secondary.replicaCount >= 2).
- Nommer la valeur lorsque c’est pertinent — « total node count must not exceed 9; got 12 » (le nombre total de nœuds ne doit pas dépasser 9 ; obtenu 12).
- Suggérer la correction lorsque c’est possible — « use ‘soft’ or omit the field » (utilisez ‘soft’ ou omettez le champ).
- Éviter le jargon — le lecteur est le développeur qui a rédigé l’Aggregate, pas l’architecte qui a écrit l’assertion.
Pour les messages longs ou porteurs de valeurs, utilisez printf :
{{- fail (printf "field %s exceeds limit: got %d, max is %d" .field .value .max) -}}Le compilateur présente le message dans le format d’erreur Loud Guardrails avec le nom de l’entité, l’emplacement source de l’assertion et le message d’échec. Le diagnostic est suffisamment précis pour que le développeur identifie et corrige la cause première.
Une valeur qu’un auteur a déclarée sensitive: true se lit <redacted> dans ce message partout où le message la cite, de sorte que nommer la valeur d’un champ déclaré dans le message est sans risque : le diagnostic nomme toujours la règle et le champ, et seule la valeur est retenue. Une assertion dont le résultat dépend de ce que contient une telle valeur — une comparaison avec un littéral, un test de préfixe — signale que son texte d’échec est retenu au lieu de son message. vocabulary/compact-form-authoring.md « Ce qu’un refus dit d’une valeur déclarée » contient la règle complète.
Ce que assertions: ne remplace pas
assertions: est le lieu des règles inter-champs. Il ne remplace pas :
- Les contraintes JSON Schema dans
schema:— les règles par champ (plage, motif, enum, format, type) relèvent des mots-clés natifs de JSON Schema. - Le champ
validate:de la forme compacte — des prédicats personnalisés par champ, de portée limitée à un seul champ. Utilisezvalidate:lorsque la règle s’applique à un champ précis ; utilisezassertions:lorsque la règle implique plusieurs champs et qu’aucun champ unique n’est « celui qui est validé ». - Le champ
when:de la forme compacte — la forme conditionnelle (si les contraintes d’un sous-arbre s’appliquent). Utilisezwhen:pour les variations de forme ; utilisezassertions:lorsque la combinaison de valeurs est invalide d’une manière mieux exprimée sous forme de prédicat libre. - Vérifications à l’exécution —
assertions:s’exécute uniquement au moment de la compilation. Tout ce qui dépend de l’état du cluster à l’exécution (IP actives, contenu du vault, état des pods à l’exécution) doit être exprimé sous forme de chaînes de pointeurs déterministes (voir le contrat de pureté AOT).
Exemples détaillés
Minimal — règle architecturale unique
spec: assertions: replication-needs-two-secondaries: | {{- if and (eq .values.architecture "replication") (lt .values.secondary.replicaCount 2) -}} {{- fail "replication requires secondary.replicaCount >= 2" -}} {{- end -}}Taille moyenne — contrat de Component à plusieurs règles
spec: assertions: # Replication minimum. replication-needs-two-secondaries: | {{- if eq .values.architecture "replication" -}} {{- if lt .values.secondary.replicaCount 2 -}} {{- fail "architecture=replication requires secondary.replicaCount >= 2" -}} {{- end -}} {{- end -}}
# Total node limit. total-node-count-within-cap: | {{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}} {{- if gt $total 9 -}} {{- fail (printf "total node count exceeds 9: got %d (primary=%d, secondary=%d)" $total .values.primary.replicaCount .values.secondary.replicaCount) -}} {{- end -}}
# A ServiceMonitor scrapes the metrics exporter, so it needs one. service-monitor-needs-metrics: | {{- if and .values.metrics.serviceMonitor.enabled (not .values.metrics.enabled) -}} {{- fail "metrics.serviceMonitor.enabled=true requires metrics.enabled=true" -}} {{- end -}}Production — Recipe avec règles d’implémentation
spec: assertions: # Bitnami 20.x: serviceMonitor namespace requirement. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}
# TLS certificate consistency. tls-needs-both-certificate-files: | {{- if .values.tls.enabled -}} {{- if not (and .values.tls.certFilename .values.tls.certKeyFilename) -}} {{- fail "tls.enabled=true requires both tls.certFilename and tls.certKeyFilename" -}} {{- end -}} {{- end -}}
# Replication-mode storage class consistency. replication-needs-one-storage-class: | {{- if eq .values.architecture "replication" -}} {{- $primaryClass := .values.primary.persistence.storageClass -}} {{- $secondaryClass := .values.secondary.persistence.storageClass -}} {{- if and $primaryClass $secondaryClass (ne $primaryClass $secondaryClass) -}} {{- fail "replication mode requires primary and secondary to use the same storageClass" -}} {{- end -}} {{- end -}}Intégration avec l’outillage
aggrega buildévalue les assertions entre la validation du schéma et le rendu ; une assertion en échec arrête le build avec le message{{ fail }}de l’assertion.aggrega validateapplique la même exactitude avant le rendu sans écrire d’artefacts — pour une Recipe dont la source n’est pas récupérée, il pilote le véritable pipeline de compilation autour d’un Aggregate, d’un Manifest et d’une Release minimaux synthétisés, de sorte qu’un template d’assertion mal formé ou une assertion qui fait référence à un champ inconnu ressort comme une erreur d’exactitude ; les assertions d’une Recipe dont la source est récupérée sont évaluées par un build. Une assertion qui y appellefailest signalée comme un avertissement portant son message, et la vérification réussit : la Release synthétisée contient des espaces réservés et des valeurs par défaut au lieu des valeurs que définit une vraie Release, de sorte que le verdict sur l’assertion est laissé à un build — voir une assertion échouée est un avertissement. (aggrega lintcouvre les conventions de publication, pas l’exactitude des assertions.)- Les IDE prenant en charge les templates Sprig mettent en évidence les références
.values.X; la documentation au survol renvoie à la définition du schéma lorsque l’intégration à l’IDE est configurée.