Feature
Le rôle conceptuel de l’entité Feature (le trait opérationnel modulaire du domaine 2) est décrit dans architecture/04-entity-taxonomy.md. La distinction entre les Features opérationnelles et les Features d’identifiants (celles portant le label feature.aggrega.ai/kind: secret) est décrite dans architecture/08-credential-model.md. Le vocabulaire de labels sémantiques utilisé par les sélecteurs de Feature se trouve dans entities/component. Cette page couvre la surface de rédaction du catalogue de Feature.
Emplacement dans le catalogue
Contrairement aux Components (qui utilisent des URI à trois segments avec des sous-répertoires de catégorie), les Features sont organisées à plat : un répertoire par Feature sous son éditeur, contenant un répertoire par version.
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...URI OCI : hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (par ex. hub.aggrega.ai/feature/core/data-masking:1.0.0).
Contrat de rédaction
Les Features déclarent :
metadata.labels: utilisezfeature.aggrega.ai/kind: secretpour marquer une Feature comme Feature d’identifiants. Le label est une métadonnée descriptive pour l’auteur, pour le site du catalogue et pour les sélecteurs de labels ; aucune branche du compilateur ne le lit, et ce que produit un rattachement est décidé par la FeatureRecipe vers laquelle le Manifest mappe son type, et non par le label. Une Feature d’identifiants et une Feature ordinaire se rattachent de la même manière, sur la même surface de rattachement, à n’importe quelle portée. La famille d’identifiants de la bibliothèque standard se répartit selon le résultat :core/secret-valuedélivre une valeur dans le tube d’injection ;core/referenced-secretnomme une ressource secrète référençable (un Secret Kubernetes, un secret AWS Secrets Manager, une entrée Vault), créée par la sortie de sa FeatureRecipe ou déjà existante, et déclare un contrat de sortieschema.provides—name(le localisateur de la ressource, neutre vis-à-vis du provider) etkey(le champ de données qu’elle contient) — qu’un consommateur lit sous la forme.features.<slot>.provides.<key>pour référencer la ressource sans en redériver le nom ;core/referenced-secret-setmatérialise une ressource portant un ensemble de clés de données fourni par l’appelant et ne publie que le localisateur, pour un consommateur dont la cible connaît déjà les noms de clés qu’elle lit ;core/secret-providedexpose la valeur d’un secret préexistant ;core/generated-secretne produit rien, car le moteur cible génère et gère lui-même l’identifiant, de sorte qu’elle ne déclare nivaluesniprovideset que ses FeatureRecipes sont du pur câblage qui ne rend aucun octet. Deux axes séparent les membres : qui fournit le matériel — un auteur l’écrit ou indique où le récupérer, ou bien le moteur cible le possède entièrement, comme aveccore/generated-secret— et ce que donne le rattachement : une valeur injectée, une ressource référençable ou rien de rendu du tout. Chaque membre est le pair des autres sur la même surface de rattachement, de sorte qu’un slot d’identifiants est toujours lié et que ce qui varie entre les Releases, c’est ce qui le lie. Une Feature d’identifiants qui déclare un contratschema.providesoblige chaque FeatureRecipe qui l’implémente à publier ces clés — sinon le build s’arrête — et leselectord’un slotfeaturesSchemacible le membre de la famille dont il a besoin.usesSchema(facultatif) : déclare les sockets topologiques que la Feature peut consommer (par ex. le socketpath/keyd’une Feature d’identifiants ciblant un coffre-fort). Voir architecture/13-catalog-and-registry.md §2 pour le mécanisme du Split Schema.schema: valide les blocsvaluesetinfradu rattachement de la Feature — l’intention cognitive que le développeur configure sur chaque rattachement dans l’Aggregate (lesvaluesrelèvent du domaine du développeur, et le schéma de la Release interditvalues:sur les rattachements de Feature) et la capacité que l’opérateur décide par environnement dans la Release (infra). Un champ qui déclare undefault:est à la fois validé par rapport à celui-ci et inséré dans le pilier rendu lorsque rien ne le renseigne ; voir Portée de la Feature et forme de rédaction. Accepte JSON Schema 2020-12 exprimé dans la notation abrégée YAML en forme compacte (par défaut ; voirvocabulary/compact-form-authoring.md) ou en YAML JSON Schema complet, avec des$ref:inter-documents vers des entrées SchemaLibrary pour les formes partagées (voirvocabulary/cross-document-ref.md). Une feuille qui porte du matériel secret déclaresensitive: true— les Features d’identifiants de la bibliothèque standard marquent la feuille qui contient le matériel et laissent délibérément non marqués les localisateurs qu’elles publient, puisqu’un nom de ressource et une clé de données sont tous deux publics. Le mot-clé, et la limite de ce que sa déclaration permet, se trouvent dansvocabulary/compact-form-authoring.md« Déclarer une feuille sensible ».featuresSchema(facultatif) : déclare les slots de rattachement dont la Feature a besoin pour son propre fonctionnement — une Feature déclare des slots exactement comme le fait un Component, de sorte qu’une Feature qui a elle-même besoin d’un identifiant (la clé d’API d’une Feature sidecar Datadog, par exemple) nomme le point de liaison au lieu de recourir aux slots du Component hôte. Voir L’identifiant propre d’une Feature pour une Feature déclarant son propre slot et une FeatureRecipe lisant ce qui le remplit. Chaque slot accepte les mêmes champs qu’un slotfeaturesSchemad’un Component, avec la même sémantique — y compris unselectorfacultatif (un sélecteur de labels de style Kubernetes qui restreint la Feature pouvant remplir le slot, l’analogue pour les slots d’un sélecteur de socketusesSchema; un remplissage dont les labels ne le satisfont pas provoque un arrêt, et le sélecteur est évalué par rapport aux labels de la Feature rattachée et à rien d’autre), unsensitivefacultatif (qui déclare que tout ce qui lie le slot manipule du matériel secret — une affirmation sur le point de liaison plutôt que sur un remplissage particulier), et la même ouverture : déclarer un slot n’interdit jamais un rattachement sous un nom qu’aucun slot ne déclare. Le tableau complet des champs, la déclaration de sensibilité au niveau du slot et ce qui la distingue de celle d’une feuille de schéma, ainsi que les deux formes sous lesquelles est déployée une entité déclarant des slots, se trouvent tous dans entities/component.md « Slots de rattachement ».appliesTo/appliesToAnyOf: sélecteurs de labels qui contrôlent à quels Components la Feature peut se rattacher. Ils sont évalués par le moteur natif de correspondance de labels du compilateur pendant l’étape d’analyse statique. Voir Rattachement par labels ci-dessous et architecture/13-catalog-and-registry.md §2 « Sélecteurs de style Kubernetes » pour la référence de la syntaxe des sélecteurs.interoperability(facultatif) : un bloc imbriqué portantconflictsWith— les Features aux côtés desquelles cette Feature ne peut pas atteindre un composant. Le build s’arrête avant le rendu lorsqu’un composant finit par porter les deux, quelle que soit la portée à laquelle chacune a été rattachée. Voir Le blocinteroperabilityci-dessous pour l’explication complète.
Le rendu structurel d’une Feature est lié à sa FeatureRecipe correspondante, qui mappe l’interface de la Feature vers une implémentation d’infrastructure concrète.
Rattachement par labels
Les deux sélecteurs d’application du schéma de la Feature contrôlent à quels Components la Feature se rattache, évalués par le moteur natif de correspondance de labels du compilateur pendant l’étape d’analyse statique :
appliesTo— une chaîne de sélecteur de labels de style Kubernetes ; la surface de composition AND. Les exigences séparées par des virgules doivent toutes être satisfaites, avec le vocabulaire complet d’opérateurs :key=value,key!=value,key in (v1, v2),key notin (v1, v2),keyseul (label présent),!key(label absent). Une Feature qui déclareappliesTo: "datastore.aggrega.ai/engine=vector"ne se rattache qu’aux Components portant exactement cette paire clé-valeur comme label ;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"exprime « tout serveur ou worker qui ne détient pas de données restreintes » dans une seule chaîne de sélecteur.appliesToAnyOf— la surface de composition OR. Une liste d’éléments de sélecteur où il suffit qu’un seul élément corresponde. Chaque élément est soit un sélecteur sous forme de chaîne (même grammaire queappliesTo; les exigences à l’intérieur de la chaîne se combinent en AND), soit une map clé-valeur plate pour une correspondance par égalité uniquement. S’utilise lorsqu’une Feature convient à plusieurs formes de composant sans rapport entre elles — par exemple, une Feature d’observabilité qui s’applique soit à{ component.aggrega.ai/type: worker }OU à{ component.aggrega.ai/type: task }sans forcer les deux dans une seule chaîne de sélecteur.
Sans la forme any-of, les architectes devraient dupliquer le même YAML de Feature pour chaque forme de composant sans rapport à laquelle la Feature convient. Les deux formes se composent : une Feature peut déclarer les deux, et les résultats se combinent en AND d’une forme à l’autre — la chaîne appliesTo doit être satisfaite et au moins un élément appliesToAnyOf doit correspondre. Un sélecteur omis ou vide ne déclare aucune contrainte et correspond à tout ensemble de labels.
Une chaîne de sélecteur est lue par rapport aux six formes chaque fois qu’un rattachement de la Feature est évalué, et une exigence hors de ces formes arrête le build au lieu d’être lue comme un autre sélecteur : une exigence vide (une virgule en tête, en fin ou doublée, ou une chaîne composée uniquement de séparateurs), une clé contenant des espaces ou l’un des caractères =, !, (, ) et la virgule, et un ensemble in ( ou notin ( non fermé. C’est ce qui intercepte les erreurs qui, sinon, sélectionneraient silencieusement l’inverse de ce qui était voulu : appliesTo: "!tier=frontend", écrit pour tenir une Feature à l’écart des frontends, est refusé parce que ! nomme une clé de label et rien d’autre — tier!=frontend est la manière d’exclure une valeur — et tier in frontend est refusé au profit de tier in (frontend). Une valeur est le texte qui suit son opérateur, quels que soient les caractères qu’il contient, de sorte que tier==frontend demande un label dont la valeur est =frontend. L’arrêt nomme la Feature, son sélecteur et l’exigence qui n’a pas pu être lue. Une Feature que rien ne rattache n’est jamais évaluée, de sorte qu’un sélecteur mal formé sur celle-ci n’est signalé qu’au moment où un rattachement la nomme.
Voir architecture/13-catalog-and-registry.md §2 « Sélecteurs de style Kubernetes » pour la référence de la syntaxe des sélecteurs — la grammaire qu’accepte un sélecteur de Feature est la même que celle qu’acceptent les sélecteurs de socket usesSchema, la forme de chaîne que les utilisateurs de Kubernetes connaissent grâce à kubectl get -l.
Le bloc interoperability
Le schéma de la Feature déclare un bloc spec.interoperability facultatif portant un seul contrôle : avec quelles autres Features cette Feature peut coexister sur un composant.
interoperability.conflictsWith — une liste des Features mutuellement exclusives avec la Feature en cours de définition, chacune écrite de la manière dont le type d’un rattachement nomme une Feature. Elle empêche de générer des configurations incompatibles — rattacher à la fois un maillage TCP uniquement et un proxy compatible HTTP au même composant, par exemple.
Le build s’arrête avant de rendre quoi que ce soit lorsqu’un composant finit par porter cette Feature et une Feature que nomme sa liste. Ce qui compte, c’est l’atteinte : un rattachement atteint le composant sur lequel il est écrit, ainsi que chaque composant à l’intérieur du sous-système ou de la frontière sur laquelle il est écrit, frontières imbriquées comprises ; un rattachement écrit sur une entrée de composant de la Release, ou produit par l’expansion pilotée par les annotations, atteint son composant de la même manière. Un conflit déclaré provoque donc un arrêt lorsque les deux Features sont rattachées au même composant, lorsque l’une est sur une frontière et l’autre sur un composant à l’intérieur, lorsque l’une est sur une frontière extérieure et l’autre sur une frontière imbriquée à l’intérieur qui contient un composant, et lorsque l’une est sur un sous-système et l’autre sur un composant de ce sous-système. Deux Features rattachées à des frontières sœurs qui ne partagent aucun composant ne se rencontrent jamais, et une frontière ne contenant aucun composant n’atteint rien — aucun de ces cas ne provoque d’arrêt.
- Une seule déclaration suffit. Le build s’arrête lorsque la liste de l’une ou l’autre Feature nomme l’autre ; la seconde Feature n’a pas à lister la première en retour.
- Les noms, quelles que soient les versions. Chaque entrée et le type de chaque rattachement sont comparés après suppression de toute version, de sorte qu’une entrée
core/fixed-replica-controllercorrespond à un rattachement decore/fixed-replica-controller:2.0.0, et qu’une entrée portant une version correspond à toutes les versions de la Feature qu’elle nomme. - Il ne lit que des noms. Le compilateur compare les noms que l’auteur de la Feature a déclarés aux Features que porte un composant — le même type d’évaluation que
appliesTo, sur des données écrites par l’auteur. Savoir si deux Features sont incompatibles relève du jugement de l’auteur, et la liste est l’endroit où il est consigné.
L’arrêt nomme la Feature dont la liste nomme l’autre, chaque endroit où chacune des deux a été rattachée — sur le composant dans l’Aggregate, sur un sous-système, sur une frontière de la Release avec son chemin, sur une entrée de composant de la Release, ou par expansion pilotée par les annotations d’une annotation nommée — et le composant où elles se rencontrent. Une paire qui se rencontre sur plusieurs composants est signalée une fois pour chacun. Voir errors/fatal-halts.md pour le message.
Exemple :
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controllerCette Feature ne se rattache qu’aux Components de type server et déclare une incompatibilité avec une autre Feature de contrôle des réplicas : un build dans lequel un composant quelconque finit par porter les deux s’arrête avant le rendu. Une FeatureRecipe qui a besoin du nom du composant auquel elle est rattachée — pour diriger un autoscaler vers sa cible, par exemple — le lit dans son contexte de template et l’écrit partout où sa sortie en a besoin : .context.instance_id est l’identité du composant, et .context.rendered_name est le nom que le provider propre du composant donne aux ressources qu’il rend pour lui, celui par lequel cibler une ressource — sous helm, le nom du Deployment qu’émet une charge de travail synthétisée, et le nom de release à partir duquel un chart construit ses propres noms.
Héritage via extends
Une Feature peut déclarer spec.extends: <feature-name> pointant vers une Feature de base dont elle hérite la surface de rédaction. La référence nomme la base par son metadata.name, et non par la coordonnée de registre sous laquelle la Feature est publiée, et accepte les trois mêmes formes de version que toute référence de catalogue : nue (core/queue) pour la version disponible la plus élevée, exacte (core/queue:1.0.0) ou une plage caret (core/queue:^1.0.0). Le compilateur parcourt la chaîne des parents au chargement du catalogue, vérifie que la chaîne est acyclique, puis fusionne les specs des parents dans l’enfant pour produire une seule Feature résolue. Les champs rédigés par l’enfant ont la priorité en cas de collision de clés ; les metadata.labels et metadata.annotations du parent, les sélecteurs appliesTo / appliesToAnyOf, le bloc interoperability, usesSchema, featuresSchema et les déclarations JSON Schema 2020-12 sur schema sont fusionnés automatiquement vers le bas. Tout autre champ de metadata est celui de l’enfant tel quel, de sorte que l’identité et la provenance ne s’héritent jamais.
Ce dont hérite le metadata: d’une Feature. labels et annotations fusionnent clé par clé le long de la chaîne, la base d’abord, la valeur de la Feature qui étend l’emportant sur une clé partagée — la même règle que suivent les Components. Le reste de metadata: ne se transmet pas : name, version, description, maintainers, license, repository, home et keywords sont ceux de la Feature qui étend, exactement tels que rédigés.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }Le core/kafka-queue fusionné hérite de appliesTo du parent, hérite des propriétés values.qos et infra.partition_count, et ajoute values.compression_codec par-dessus. Un enfant qui déclare explicitement appliesTo remplace en bloc le sélecteur du parent (la fusion des sélecteurs de labels n’est pas profonde — le sélecteur de l’enfant remplace celui du parent). Le schema.values.qos d’un enfant remplace la déclaration du parent pour cette propriété.
Comment hérite chaque partie de la surface de rattachement. Les deux formes de sélecteur s’héritent indépendamment l’une de l’autre, car elles se composent au lieu de se remplacer : chaque forme présente doit être satisfaite — la chaîne appliesTo doit correspondre, et au moins un élément appliesToAnyOf doit correspondre — tandis qu’une forme absente ne contraint rien. Une Feature peut donc reprendre le sélecteur AND de sa base tout en déclarant son propre ensemble OR. Le bloc interoperability s’hérite champ par champ — un enfant qui déclare le bloc sans liste conflictsWith porte toujours la liste déclarée par sa base, tandis qu’un enfant qui déclare son propre conflictsWith remplace la liste de la base au lieu de s’y ajouter. Une Feature qui ne déclare aucun des trois se rattache exactement là où se rattache sa base.
L’héritage est une fusion de schémas, pas une liaison d’interface. Une chaîne extends: de Feature produit une seule Feature résolue, et non une famille polymorphe. L’URI de la Feature de base de la chaîne n’est pas ce que référence le champ feature: d’une liaison de Manifest — les Manifests lient par l’URI de la Feature feuille, et le schéma résolu inclut les propriétés héritées. Le contrat de Feature qu’une FeatureRecipe implements: est de même l’URI feuille ; les FeatureRecipes ne parcourent pas la chaîne d’héritage.
aggrega pull récupère la base. Une Feature de base est une dépendance de chaque Release qui attache une Feature qui l’étend, que quoi que ce soit d’autre la nomme ou non. aggrega pull suit chaque extends: jusqu’au bout de la chaîne, récupère depuis le registre une base qu’aucun répertoire de catalogue ne contient, et enregistre chaque base dans le lockfile de la Release, référencée depuis le spec.extends de la Feature qui la nomme ; un build lit la base à partir de là.
Modes d’erreur. Une chaîne extends: cyclique, et un parent qu’aucune entité de catalogue ne fournit, arrêtent le build, en nommant la Feature à partir de laquelle la résolution a commencé, la Feature dont il faut ouvrir la ligne extends:, et la référence qu’elle déclare. Les messages se trouvent dans Cyclic extends on Components or Features (extends cyclique sur des Components ou des Features) et An extends: chain cannot be assembled (Une chaîne ne peut pas être assemblée).
Pour le vocabulaire plus large de l’héritage et de l’interface à travers les Components, les Features et les Features d’identifiants, voir vocabulary/inheritance-and-interface.md.
Composabilité : le contrat social de pureté
La convention de la bibliothèque standard est une Feature, une fonction interne — un sidecar d’observabilité est une Feature d’observabilité ; un sidecar de proxy réseau est une Feature de proxy réseau ; ils ne se combinent pas en un composite unique avec deux préoccupations sans rapport. La convention garde les Features individuelles composables, versionnées indépendamment et rattachables indépendamment.
Le compilateur Go central n’impose pas cette convention. Les définitions de Feature aux préoccupations mélangées sont syntaxiquement légales et se compilent sans erreur. L’application est facultative :
- Les entreprises qui rédigent des catalogues internes peuvent écrire un plugin de linter personnalisé qui inspecte les définitions de Feature dans la CI/CD et avertit lorsque les labels
appliesTod’une seule Feature couvrent des domaines de capacité sans rapport. - Un auteur de Feature qui consigne, dans
interoperability.conflictsWith, que deux Features se chevaucheraient active une vérification au moment du build : le compilateur s’arrête partout où les deux atteignent un même composant. Il compare les noms déclarés et rien de plus, de sorte qu’il impose la déclaration qu’un auteur a écrite plutôt que la convention de pureté elle-même.
Les Features open source de la bibliothèque standard suivent la convention de pureté par discipline de rédaction ; les catalogues d’entreprise sont libres de s’en écarter lorsqu’un composite étroitement couplé convient réellement au modèle de déploiement.
Ce qui justifie une Feature, et où se place le réglage propre d’un produit
Une Feature est un rattachement : elle apporte quelque chose que le développeur ou l’opérateur rattache délibérément — des ressources, une étape de pipeline, du câblage — et la convention de la bibliothèque standard veut qu’elle puisse être honorée par au moins deux produits indépendants. Cette seconde moitié est le test à appliquer avant d’en écrire une, car la portabilité est ce que promet le mot rattachement. Un rattachement signifie que la capacité voyage : rattachez-la à un composant, rattachez-la à un autre, et la réalisation de chaque produit l’honore dans ses propres termes.
Une capacité que seul un produit sur le terrain possède est le réglage propre de ce produit plutôt qu’une Feature. Elle a sa place comme valeur écrite sur la surface propre de ce produit, que l’auteur qui en décide définit dans son propre pilier et lit à côté de tout ce qui configure le même produit. La publier plutôt comme Feature offre une portabilité qu’aucun autre produit ne peut fournir : le rattachement nomme un seul produit par construction, de sorte qu’un auteur qui la rattache au prochain produit vers lequel il se tourne rencontre un build qui s’arrête en nommant le type, et la Feature a enseigné une capacité qu’elle n’a jamais eue.
Le test compte les produits sur le terrain, et non les composants de ce catalogue, chacun lu dans sa propre référence de configuration actuelle. Deux produits indépendants qui implémentent une capacité la rendent portable, quel que soit le nombre d’entre eux livrés ici ; une Feature peut donc être déclarée avant que quoi que ce soit dans le catalogue ne la réalise — la rattacher arrête alors le build en nommant le type — et chaque réalisation livrée est une FeatureRecipe pour un seul produit, qui honore le rattachement de la manière dont ce produit le configure.
L’épinglage des certificats amont est le cas d’école. Un épinglage est un contrôle sur la clé qu’un amont peut présenter : n’accepter qu’un certificat dont la clé publique correspond à l’une de celles que fournit la Release. C’est une assertion différente de celle qui exige que le certificat d’un amont soit chaîné à une ancre de confiance fournie par la Release, et différente encore de celle qui affirme ce que dit le sujet d’un certificat — toutes deux énoncent ce qu’un certificat doit dire, tandis qu’un épinglage énonce quelle clé il doit être. Plusieurs passerelles ici peuvent vérifier par rapport à une ancre, c’est pourquoi dataplane.aggrega.ai/upstream-tls: trust-anchor est une valeur qu’un sélecteur peut faire correspondre. L’épinglage est une capacité distincte, et au moins deux produits indépendants l’implémentent pour les connexions qu’ils ouvrent vers un amont : Tyk prend la clé publique de l’amont au format PEM, et Envoy en prend un hachage. C’est donc une Feature, core/upstream-key-pinning, dont le sélecteur nomme dataplane.aggrega.ai/upstream-pinning: public-key, et ce que ce catalogue réalise se décide produit par produit : core/gateway/tyk porte la valeur et une FeatureRecipe pour chacune de ses cibles, tandis que les passerelles d’ici qui embarquent Envoy n’exposent son paramètre d’épinglage que pour les certificats présentés par les clients, ou pas du tout, de sorte qu’elles ne portent aucune valeur et qu’un rattachement à celles-ci s’arrête au sélecteur. Un épinglage restreint ce qu’un amont peut présenter ; c’est un contrôle, et non une assurance que la connexion est par ailleurs saine.
Deux limites au test, et la seconde est la moitié la plus facilement oubliée :
- C’est une discipline d’écriture, et non une vérification du compilateur. Une Feature déclarant des options qu’aucun produit n’implémente passe aussi bien la validation de schéma que le linter de publication et un rendu — le compilateur n’interprète pas ce qu’une Feature promet. Le jugement reste à l’auteur du catalogue.
- L’incapacité d’un produit à honorer une option n’est pas une raison de retirer cette option. Lorsque deux produits ou plus livrent une capacité sous des noms qui se regroupent, la capacité est portable et la Feature la conserve ; le produit qui ne peut pas l’honorer la décline. Une Feature réduite à ce que chaque produit prend en charge n’a presque plus rien à dire.
Portée de la Feature et forme d’écriture
Le spec.schema d’une Feature définit les formes values: et infra: propres à la Feature — l’intention cognitive que le développeur configure pour chaque rattachement de Feature dans l’Aggregate (values), distincte des valeurs de capacité que l’opérateur décide par environnement (infra). Les piliers de la Feature vivent dans leurs propres espaces de noms et sont validés indépendamment des piliers du Component hôte. Lorsque le développeur rattache une Feature autoscaler à un Component web-server dans l’Aggregate, l’Aggregate porte les values: du Component (forme de l’hôte) ainsi que les values: de la Feature (la forme de l’intention de mise à l’échelle — quelle métrique pilote la mise à l’échelle) ; les valeurs de capacité destinées à l’opérateur (min_replicas / max_replicas) transitent par le bloc infra: de la Release sur le rattachement de la Feature.
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10Le schema: de la Feature valide les blocs values: et infra: propres au rattachement de la Feature. Le schema: du Component valide ceux du Component. Les deux sont évalués indépendamment à l’étape d’analyse statique ; un pilier de rattachement qui ne correspond pas au schema: de la Feature arrête le build avec une erreur limitée au site de rattachement de la Feature, et non au Component hôte. Ce qui est validé est la configuration effective du rattachement — le résultat de la composition de chaque portée qui l’a configuré — de sorte qu’une valeur rendue conforme à une portée puis remplacée par une valeur illégale à une portée plus étroite est détectée.
Les valeurs par défaut déclarées se matérialisent dans les piliers rendus du rattachement. Au-delà de la validation, un default: déclaré sur un champ values ou infra d’une Feature est inséré dans le pilier rendu de ce rattachement au moment du build pour chaque clé que rien n’a écrite — ainsi un template de FeatureRecipe qui lit {{ .infra.tier }} reçoit la valeur déclarée dans le schéma plutôt qu’une valeur vide. Les valeurs fournies par l’auteur l’emportent toujours, et une valeur par défaut ne remplit que les clés qu’elles omettent : un rattachement qui écrit une clé du schéma de la Feature reçoit tout de même les valeurs par défaut déclarées pour les autres clés de ce schéma, et un objet imbriqué partiellement écrit conserve ce qui a été écrit et gagne les éléments frères qui ne l’ont pas été.
Trois propriétés du remplissage sont utiles à connaître lors de l’écriture :
- Une valeur par défaut ne remplace jamais une valeur fournie par une portée. Lorsqu’une Feature est rattachée à plus d’une portée — une frontière de Release et l’un de ses composants, par exemple — la valeur de la portée la plus étroite s’applique et la valeur par défaut ne remplit que ce qu’aucune portée n’a écrit.
- Une valeur par défaut remplit un rattachement ; elle n’en crée jamais. Déclarer des valeurs par défaut sur une Feature que rien ne rattache n’apporte rien à la sortie, de sorte que le schéma d’une Feature ne peut pas ajouter une configuration qu’aucun auteur n’a demandée.
- Un rattachement déclaré sur une frontière de Release plutôt que sur un composant unique ne remplit que
infra, car cette surface ne porte aucun blocvalues:à remplir.
Comme la matérialisation utilise la même résolution de schéma que la validation, une valeur par défaut déclarée sur une Feature parente atteint les rattachements d’un enfant extends:, et les valeurs par défaut atteintes par un $ref: inter-documents vers une SchemaLibrary se matérialisent aussi. Les valeurs par défaut déclarées uniquement dans une référence locale interne au document #/$defs/, ou sous une branche allOf / oneOf / anyOf, ne sont pas matérialisées.
Une conséquence mérite d’être énoncée clairement, car la validation seule ne la révélera pas : un champ required: qui porte aussi un default: est satisfait par cette valeur par défaut, donc l’omettre est légal — et la valeur sur laquelle la vérification a statué est la valeur que porte la sortie rendue.
Le contexte de template du compilateur expose l’état d’instance de la Feature à la FeatureRecipe liée via le champ .features.<alias> (qui contient .type, .resolved_version, .labels, .values, .infra et .provides par rattachement). Les templates de la FeatureRecipe lisent les values: propres à la Feature via .values.<field> dans la portée de template propre à la FeatureRecipe ; les values: du Component hôte ne sont pas directement visibles pour les templates de la FeatureRecipe, à moins que la Feature ne déclare explicitement un socket uses: vers le Component hôte.
Cette séparation des portées rend les Features composables : une Feature autoscaler ne dépend pas du Component auquel elle est rattachée ; son schema: décrit l’intention d’autoscaling quel que soit l’hôte. Les values: du Component hôte relèvent de l’hôte ; les values: de la Feature relèvent de la Feature ; les deux piliers se composent sans laisser fuir de noms de champs au-delà de la frontière.
Cibles des liaisons d’annotations
Une Feature ne déclare pas elle-même de liaisons d’annotations ; c’est la map mappings.features.annotations du Manifest qui les porte. Une Feature participe indirectement à la relation de liaison en tant que cible de routage : chaque liaison nomme un type de Feature via son champ feature:, et les listes maps.infra et maps.values de la liaison déclarent des chemins pointés vers les propriétés spec.schema.infra.<path> et spec.schema.values.<path> de la Feature nommée.
Au chargement du catalogue, le compilateur vérifie que chaque chemin pointé des listes maps d’une liaison correspond à une propriété que le spec.schema de la Feature cible déclare effectivement dans le pilier nommé. Une liaison qui route vers un chemin que le schéma de la Feature ne déclare pas arrête le chargement du catalogue avec une OPS_ERROR claire, nommant la liaison, la Feature cible, ainsi que le pilier et le chemin par lesquels elle a routé — la liaison est écrite dans le Manifest, qui est le document de l’opérateur. Les auteurs de schémas savent donc que toute propriété qu’ils déclarent sous spec.schema.values.<path> ou spec.schema.infra.<path> est atteignable comme cible de liaison ; inversement, toute propriété par laquelle route une liaison du Manifest doit exister dans le schéma de la Feature cible.
Lorsqu’une annotation côté Aggregate ou côté Release correspond à une liaison, le compilateur synthétise un rattachement de Feature dont les charges utiles des piliers routent la valeur de l’annotation vers les chemins nommés. Le rattachement synthétisé est structurellement indiscernable d’un rattachement de Feature explicite déclaré par l’auteur au même site ; le rendu en aval, la validation et le contexte de template de la FeatureRecipe consomment les deux formes de manière uniforme. Pour la forme de la liaison, la partition côté/pilier et la discipline selon laquelle le rattachement explicite l’emporte, voir entities/manifest.md §« Liaisons de Feature pilotées par annotations ». Pour la règle de cascade côté Aggregate et un exemple d’écriture, voir providers/well-known-annotations.md §« Cascade d’annotations côté Aggregate ».
Le bloc assertions:
Feature.spec.assertions: est une map facultative de règles nommées exprimant des invariants architecturaux du contrat de la Feature — des règles inter-champs portant sur les values: de la Feature et sur l’état résolu du Component rattaché. Chaque clé est un identifiant de règle qui apparaît dans le message d’échec ; chaque valeur est un corps de template Go. Le compilateur les évalue après la validation de schéma et avant le rendu de la FeatureRecipe liée, dans l’ordre où elles sont écrites, et la première règle en échec arrête le build avec le message d’erreur propre à cette règle.
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}Comme les assertions de Component, les assertions de Feature expriment des invariants au niveau du contrat — des propriétés que le rattachement de la Feature doit satisfaire quelle que soit la FeatureRecipe qui implémente le rendu. Pour les règles inter-champs qui dépendent de l’implémentation spécifique (une exigence d’un plugin Wasm, une particularité d’un chart), utilisez plutôt le champ assertions: de la FeatureRecipe. Pour la grammaire d’écriture complète, le contexte de template et la répartition des responsabilités entre les assertions de Feature et celles de FeatureRecipe, voir templates/assertions-block.md.