Modèle des identifiants
Une seule famille d’attachements
Dans Aggrega, un identifiant est une Feature. Il s’attache sur la même surface, sous le même mot-clé et sous la même forme que n’importe quelle autre Feature. Ici, le développeur attache l’identifiant de la base de données dans l’Aggregate, en écrivant son localisateur dans values :
# the Aggregate — its parameters and the components' own values left outspec: components: api: type: core/compute/server db: type: core/datastore/mariadb features: root_password: # a credential Feature type: core/secret-value:1.0.0 values: key: MARIADB_ROOT_PASSWORD origin: "{{ .parameters.db_root_pass }}"et l’opérateur attache au serveur une cible de collecte de métriques dans la Release, car chaque entrée que prend core/prometheus-exporter — le port, le chemin et l’intervalle de collecte — est opérationnelle, et s’écrit donc dans infra :
# the Release — the api's own infra and the db's entry left outspec: components: api: features: metrics: # an operational Feature type: core/prometheus-exporter:1.0.0 infra: port: http # the named port of the api's ServiceIl existe un seul mot-clé d’attachement (features:), une seule forme de contexte de rendu (.features.<name>, et la même forme sous une connexion, .context.uses.<alias>.features.<slot>, pour un attachement écrit sur une connexion), un seul ordre d’exécution et un seul ensemble de coordonnées de sortie — pour un attachement sur un composant, le composant auquel il est attaché puis le nom sous lequel il est attaché, que la disposition de la cible porte ces deux éléments sous forme de répertoire <component>--<instance>/ à côté de celui du composant ou de préfixe de nom de fichier <component>--<instance>--. Ce qui varie d’un attachement à l’autre, c’est ce qu’ils produisent — une valeur injectée, une ressource référençable, un sidecar, une identité cloud — et non la surface sur laquelle ils sont déclarés.
Une Feature d’identifiant porte l’étiquette feature.aggrega.ai/kind: secret sur son entité de catalogue. Cette étiquette est une métadonnée descriptive : elle indique à un lecteur, à un site de catalogue et à un sélecteur d’étiquettes à quoi sert la Feature. Aucune branche du compilateur ne la lit, et aucun comportement n’en dépend. Le comportement provient de la FeatureRecipe à laquelle un opérateur associe le type de Feature.
Le modèle mental en une phrase : il n’existe qu’un seul type d’attachement ; ce qui varie, c’est ce qu’il produit.
Slots et attachements libres
Un Component ou une Feature peut déclarer des slots dans featuresSchema :
spec: featuresSchema: root_password: required: true inject: [] # blackbox — the Recipe delivers it selector: "feature.aggrega.ai/kind=secret" user_password: inject: [env, file] # transparent — the developer may dictate deliveryUn attachement dont le nom d’instance correspond à un slot déclaré remplit ce slot. Un attachement sous tout autre nom est un attachement libre : l’entité ne l’a pas demandé, et il est rendu à côté de tout ce que l’entité a demandé. Le schéma généré pour un slot déclaré reste ouvert, de sorte que déclarer un slot ne ferme jamais le bloc aux attachements libres. Une seule forme provoque un arrêt au lieu d’un rendu : un attachement écrit sur le composant lui-même dont la Feature satisfait le selector d’un slot que rien n’y lie, ce qui est un remplissage écrit sous le mauvais nom plutôt qu’un attachement libre.
Deux choses qu’un slot peut contraindre :
inject— les mécanismes de livraison qu’un Workload peut sélectionner pour ce qui remplit le slot. Une liste vide désigne un slot boîte noire : c’est la mécanique propre de la Recipe qui le livre (l’optionexistingSecretd’un chart, par exemple), et un Workload ne peut pas y faire référence depuis un conteneur.selector— une chaîne de sélecteur d’étiquettes que les étiquettes de la Feature qui remplit le slot doivent satisfaire. C’est là que l’étiquettekind=secretprend toute son utilité : l’auteur d’une entité qui veut qu’un slot ne soit rempli que par un identifiant l’exprime avec un sélecteur, et la vérification est une évaluation d’ensemble d’étiquettes que le compilateur effectue pendant l’analyse statique.
Un slot peut aussi exiger d’être finalement lié. required: true rend le nom du slot obligatoire : le compilateur s’arrête pendant l’analyse statique lorsque rien ne le lie, avec un diagnostic qui nomme le slot et le type de composant qui l’a déclaré. L’exigence est évaluée sur l’ensemble d’attachements dont dispose le composant une fois que chaque portée a été appliquée en cascade, de sorte qu’un attachement fourni au-dessus du composant lie le slot exactement comme un remplissage écrit sur le composant.
Une seconde surface exprime une exigence différente. L’annotation répétable de Component features.aggrega.ai/requiredType.<label> déclare une obligation de présence : au moins un attachement doit porter le type de Feature que nomme l’annotation, sous n’importe quel nom et à n’importe quelle portée, et une obligation que rien ne satisfait provoque un arrêt pendant la même analyse statique, avec son propre diagnostic. Les deux ne répondent jamais l’une pour l’autre — un slot demande si un point de liaison nommé est lié, une obligation si un attachement porte un type nommé — de sorte qu’une entité dont la Recipe doit lire ce qui a été attaché déclare un slot, tandis qu’une entité dont le contrat exige simplement la présence d’une capacité déclare une obligation.
Ce que le compilateur garantit et ne garantit pas
Cette section est la section porteuse. Aggrega est un compilateur ahead-of-time, et ses garanties sont plus étroites que ce que le mot « secret » invite un lecteur à supposer.
Le compilateur ne résout jamais un identifiant. Il ne s’authentifie auprès d’aucune API cloud, ne lit aucun coffre et ne récupère aucun matériel pendant aggrega build. Les values et l’infra d’un attachement d’identifiant traversent le graphe et entrent dans le contexte de rendu comme des scalaires opaques, et une FeatureRecipe les rend dans l’artefact qu’attend la plateforme cible. La résolution a lieu plus tard, dans le cluster ou le gestionnaire d’état IaC, par rapport à ce que désigne l’artefact rendu.
Le compilateur ne peut pas distinguer un pointeur d’une valeur de matériel. Il est agnostique vis-à-vis de ce que signifie un scalaire (voir 05-invariants.md). Un attachement d’identifiant dont le localisateur porte une coordonnée de magasin (path, key, un ARN) rend une référence à cette coordonnée ; un attachement d’identifiant dont le localisateur porte le matériel lui-même rend le matériel, tel quel, dans le fichier de sortie. Les deux sont légaux, et le compilateur les traite de manière identique, car il n’a aucun moyen de les distinguer.
L’énoncé honnête de la garantie est donc :
Aggrega garantit que le compilateur n’effectue aucune résolution. Il ne garantit pas que la sortie rendue ne contient aucun matériel — cela dépend entièrement de la Feature d’identifiant attachée et de ce que son auteur y a mis, le développeur dans
valuesou l’opérateur dansinfra.
Deux conséquences à intérioriser :
- Un arbre d’artefacts rendu est aussi sensible que son attachement qui porte le plus de matériel. Traitez
dist/en conséquence : si un attachement porte du matériel en ligne, l’arbre contient du matériel. - Les familles
core/secret-valueetcore/referenced-secretdu catalogue lui-même comprennent des formes qui acceptent directement une valeur. Elles existent parce que les déploiements réels ont besoin d’un chemin pour le développement local, et elles l’assument : les exemples fournis utilisent des valeurs fictives évidentes (dev-root-pw-change-me) précisément pour que le matériel d’un exemple rendu ne soit visiblement pas un véritable identifiant. Pour un déploiement qui ne doit pas porter de matériel, attachez une Feature d’identifiant adossée à un magasin dont la FeatureRecipe émet une ressource de récupération (unExternalSecret, une ressource personnalisée de récupération depuis un coffre, une référence de secret native du provider) plutôt qu’une ressource qui émet des données.
La convention de la bibliothèque standard est qu’un identifiant est demandé sous forme d’attachement plutôt qu’écrit dans un bloc values, de sorte que remplacer un remplissage de développement local par un remplissage adossé à un magasin soit une modification du Manifest plutôt qu’une modification de l’intention du développeur. C’est une convention que suit le catalogue, pas une règle qu’impose le compilateur.
Sensibilité déclarée
Le compilateur ne peut pas distinguer un pointeur d’une valeur de matériel, comme l’indique la section précédente — mais un auteur le peut, et peut le dire. Dans Aggrega, la sensibilité est une annotation sur une déclaration : l’auteur d’une entité de catalogue indique ce qui porte du matériel secret, et le compilateur déduit le reste de cette indication et du câblage qu’il a déjà construit. Rien n’est inféré d’une valeur, et rien n’est deviné à partir du nom d’un champ.
Elle s’écrit à exactement deux endroits, qui portent des affirmations réellement différentes.
Sur une feuille de schéma — cette donnée est du matériel secret. Une feuille de values, infra ou provides déclare sensitive: true :
spec: schema: values: origin: type: string required: true sensitive: true # the material key: type: string default: value # a data key — a locator, not materialSur un slot d’attachement — tout ce qui lie ce point manipule du matériel secret. Un slot de featuresSchema déclare sensitive: true :
spec: featuresSchema: password: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]Les deux niveaux ne sont pas un doublon de commodité l’un de l’autre, et la forme de l’identifiant référençable est le cas concret qui montre pourquoi. Un identifiant référençable publie provides.name et provides.key — le localisateur de la ressource et la clé de données qu’elle contient — et aucun des deux n’est sensible : le nom d’un Secret Kubernetes est public, tout comme la clé qu’il contient. Tous deux sont rendus en clair dans le manifest du consommateur sous forme de secretKeyRef. Pourtant, le slot que remplit cet identifiant manipule incontestablement du matériel secret. Un seul niveau ne peut pas exprimer les deux faits : marquer les localisateurs publiés pour que le slot soit lu comme sensible affirmerait quelque chose de faux à leur sujet et propagerait cette erreur partout où la déclaration est lue.
À partir de ces deux déclarations, le compilateur déduit, pour chaque attachement, si l’attachement manipule du matériel déclaré sensible — vrai lorsque la Feature attachée déclare une feuille sensible, ou lorsque le slot qu’elle lie en déclare une, l’un ou l’autre suffisant à lui seul. Il le déduit de l’attachement tel qu’il se présente une fois toutes les portées de rédaction repliées, de sorte qu’une déclaration de portée plus large qu’un remplissage plus étroit a remplacée ne subsiste pas, et que l’exigence d’un slot s’applique au remplissage qui l’a effectivement emporté. Une Feature d’identifiant qui ne déclare aucune feuille sensible — parce que le moteur cible détient le matériel et que l’auteur n’écrit rien — produit tout de même un attachement sensible lorsqu’elle lie un slot sensible.
Le plafond, énoncé clairement
Le mot « sensible » invite un lecteur à attendre un mécanisme de confidentialité. Ce n’en est pas un, et la garantie est plus étroite que ne le suggère le nom, de cinq façons précises :
- Elle ne chiffre pas. Rien n’est enveloppé, scellé ni transformé.
- Elle ne change pas le verdict du build, à une exception près. Aucun build ne s’arrête parce qu’une déclaration manque, et un catalogue dont les entités d’identifiant ne portent aucune déclaration se construit avec succès. Aucune valeur n’est acceptée ni refusée parce qu’une déclaration existe, sauf lorsque le
valuesMappingd’une Recipe ou d’une FeatureRecipe CloudFormation lit une valeur déclarée sensible pour remplir les paramètres d’un template sourcé : là, chaque littéral que lie le mapping est refusé, de sorte qu’ajouter une déclaration peut transformer un build qui réussissait en un build qui s’arrête — voir A secret bound to a CloudFormation parameter would be written into the template (Un secret lié à un paramètre CloudFormation serait écrit dans le template). Partout ailleurs, ajouter des déclarations à un catalogue existant laisse réussir chaque build qui réussissait. - Elle ne garantit pas que la sortie rendue soit exempte de matériel. La garantie énoncée plus haut est inchangée : qu’un artefact porte du matériel dépend du remplissage attaché et de ce que son auteur y a mis. Une valeur déclarée sensible fournie en ligne est rendue exactement comme une valeur non déclarée partout où le build la rend — le refus CloudFormation ci-dessus arrête un littéral au lieu de le rendre, et une fonction intrinsèque est écrite telle quelle, texte compris — et
dist/reste aussi sensible que son attachement qui porte le plus de matériel. - Elle n’impose pas de mécanisme de livraison. Une déclaration ne peut pas convertir une valeur en ligne en référence de magasin, et elle ne restreint pas ce que permet la liste d’autorisation
injectd’un slot. Imposer la livraison reviendrait à émettre une ressource que l’auteur n’a jamais déclarée, ce que l’invariant d’absence d’infrastructure fantôme interdit précisément — voir 05-invariants.md. - Elle ne change aucun octet rendu sur la plupart des cibles, et sur celles-ci ne le fera jamais. Deux chemins de rendu fournis agissent sur la déclaration dans ce qu’ils produisent (les providers Helm, Helm-Chart et Compose la lisent aussi, uniquement pour tenir une valeur marquée hors du texte d’un échec) : le provider Terraform marque l’entrée d’un module vendorisé qui porte du matériel déclaré sensible avec l’attribut de sensibilité propre à Terraform — voir language-reference/providers/terraform.md « Entrées de module déclarées sensibles » ; lorsque le
valuesMappingd’une Recipe, ou celui de la FeatureRecipe d’une Feature attachée à un composant, invente les noms des entrées, aucune entrée ne peut porter l’attribut et le build affiche un avertissement qui le signale, voir A declared-sensitive value reaches the target through a values mapping (Une valeur déclarée sensible atteint la cible via un mapping de valeurs) — et le provider CloudFormation refuse les liaisons littérales décrites plus haut, ce qui arrête un build plutôt que de changer ses octets. Partout ailleurs, ajouter des déclarations dans un catalogue existant laisse chaque artefact rendu identique. Au-delà, le plafond est structurel et ne dépend pas de ce qui a été construit : une déclaration ne peut jamais atteindre un artefact rendu que sur une plateforme cible dont le langage propre comporte une notion de sensibilité — une déclaration que cette plateforme comprend, qui régit la manière dont elle affiche une valeur et non la manière dont elle la stocke. Sur une cible dépourvue d’une telle notion, une déclaration n’a rien en quoi se transformer, de sorte qu’une entrée identique se rend de manière identique avec ou sans elle, de façon permanente.
Une chose qu’une déclaration change, en revanche, est ce que la CLI affiche pour qu’un humain le lise. Une valeur déclarée sensible est remplacée par une valeur fictive fixe dans la trace par passe et dans les dispositions inspect, en conservant la clé et en ne retenant que la valeur. C’est une décision d’affichage sur des surfaces que personne ne déploie, et les artefacts rendus sont émis tels quels parce qu’ils sont ce qui se déploie.
Lorsque le compilateur peut identifier la valeur par sa clé — une feuille déclarée, ou une clé de livraison qui porte du matériel provenant d’une clé provides déclarée — la substitution est exacte. Une valeur qu’un template a déjà écrite dans un autre document ne porte aucune clé où effectuer la substitution, car un document rendu n’enregistre rien sur la déclaration dont provient chaque caractère, et la retrouver reviendrait à inspecter le contenu. La trace montre donc un tel document en évaluant le même template une seconde fois par rapport à un contexte dont les données déclarées sensibles se lisent déjà comme la valeur fictive, et elle étiquette le résultat comme un nouveau rendu plutôt que comme ce qui a été rendu : un template qui se ramifie selon le contenu d’une valeur se rend différemment avec une valeur fictive, et une donnée qu’aucune déclaration ne nomme passe inchangée. Les surfaces, cet étiquetage et ses limites se trouvent dans language-reference/vocabulary/compact-form-authoring.md « Déclarer une feuille sensible ».
L’énoncé honnête de ce qu’apporte cet axe est donc :
Une déclaration de sensibilité est un énoncé de l’intention de l’auteur qui voyage avec l’entité, afin que l’outillage et les politiques puissent raisonner sur ce que manipule un déploiement. Ce n’est pas un mécanisme qui le protège.
Protéger le matériel reste le rôle du magasin de secrets, du cluster et du pipeline qui manipule l’arbre rendu — comme le dit le reste de ce chapitre.
Comment un identifiant atteint un conteneur
Deux formes de livraison, choisies par la FeatureRecipe de l’attachement plutôt que par le développeur :
Valeur injectée. La FeatureRecipe déclare un injectMapping et aucune ressource. Sa sortie est fusionnée en profondeur dans le pipe de livraison du composant consommateur avant le rendu de la Recipe de base, de sorte qu’une Recipe qui lit .context.inject.env.<KEY> reçoit la valeur. Rien d’autonome n’est émis.
Deux identifiants livrés sous une même clé arrêtent le build, en nommant les deux attachements : un mapping qui écrit une clé qu’une autre Feature attachée a déjà livrée — par le mapping propre de cette Feature ou par son propre bloc inject: — est refusé plutôt que fusionné, de sorte qu’un identifiant n’est jamais présenté à la place d’un autre. La règle est la même pour chaque attachement, où qu’il ait été attaché et qu’il remplisse un slot sur le composant ou sur une connexion. Un mapping qui remplace une clé livrée par le propre bloc inject: du composant ou par l’une de ses connexions est l’interception sur laquelle reposent les Features de routage, et reste légal.
Ressource référençable. La FeatureRecipe déclare source, workload, artifacts et/ou valuesMapping, et émet donc une ressource — typiquement un Secret natif de la plateforme. Elle publie l’identité de cette ressource via ses provides, et un consommateur la relit sous la forme .features.<name>.provides.name / .provides.key. Le nom propre de la ressource est dérivé des mêmes provides publiés, de sorte que le nom que lit le consommateur et le nom que porte la ressource sont une seule chaîne évaluée plutôt que deux dérivations qui pourraient diverger.
Le Workload d’une Recipe consomme un remplissage référençable via la map attachments: d’un conteneur :
workload: | containers: main: attachments: DB_PASSWORD: from: root_password # a slot the Component declares as: envLe synthétiseur résout la référence à partir des provides publiés du slot — un secretKeyRef Kubernetes pour as: env, un volume adossé à un secret pour as: file. L’auteur de la Recipe n’écrit que le nom du slot et le mécanisme.
Une FeatureRecipe peut faire les deux : réécrire le pipe de livraison et émettre une ressource. Elle peut aussi déclarer un pipeline d’étapes Wasm, qui s’exécutent de la même manière pour chaque famille d’attachements — un attachement d’identifiant peut transformer les documents rendus du composant hôte sur invitation exactement comme peut le faire un attachement opérationnel.
Qui nomme l’identifiant
Le localisateur d’un identifiant — le nom du secret, l’entrée du magasin à récupérer, la valeur à livrer — est écrit par celui qui le connaît, et ce n’est pas toujours le développeur. Une connexion que câble la Release n’a aucune entrée dans l’Aggregate, et la Release n’écrit values nulle part, de sorte qu’un identifiant qui ne prendrait son localisateur que dans values ne pourrait jamais être nommé sur une telle connexion, ni sur aucun attachement que crée la Release.
Ainsi, chaque Feature d’identifiant de la bibliothèque standard qui porte le localisateur d’un appelant — core/referenced-secret, core/referenced-secret-set, core/secret-value et core/secret-provided — l’accepte de l’un ou l’autre auteur : le développeur dans les values de l’attachement, dans l’Aggregate, ou l’opérateur dans son infra, dans la Release. La feuille a un seul nom, une seule forme et une seule déclaration sensitive: true dans les deux piliers, et chaque réalisation lit le pilier qui la porte. L’interdiction de values: dans la Release reste intacte : le localisateur de l’opérateur est infra. Les Features qui ne prennent aucun localisateur — core/random-password, core/generated-secret — ne sont pas concernées.
Exactement un, garanti par la Feature. Un attachement porte le localisateur dans un seul pilier, jamais dans les deux et jamais dans aucun. Le schéma d’aucun pilier ne peut l’exprimer, car chaque pilier est validé séparément ; c’est le bloc assertions propre à chaque Feature qui le fait, et un attachement qui l’enfreint arrête le build en nommant la Feature, l’attachement et le composant. C’est le contrat de l’entité de catalogue, respecté comme toute assertion de Feature : le compilateur évalue le template écrit par l’auteur de la Feature et ne détient aucune règle propre concernant les identifiants, les piliers ou les localisateurs.
Ce qui reste à sa place. Chaque autre champ conserve son pilier — la clé de données d’un identifiant référençable s’écrit toujours dans values, de sorte qu’un attachement que crée la seule Release lit sa valeur par défaut — et core/secret-provided ne livre toujours que par le propre bloc inject: de l’attachement, que seul l’Aggregate écrit et que l’attachement d’une connexion ne porte jamais.
Partager un identifiant entre plusieurs consommateurs
Le consommateur peut détenir l’identifiant. Un slot appartient à l’entité qui a besoin de l’identifiant, et il s’agit souvent de l’appelant plutôt que de ce qui est appelé : un composant qui présente une clé lorsqu’il établit une connexion déclare le slot de cette clé sur sa propre entité de catalogue, sur le socket par lequel il se connecte, de sorte que la clé est détenue sur la connexion où elle est présentée — et rien dans une arête uses n’oblige la cible à en fournir une. core/ai-agent/crewai en est la forme livrée — son socket model déclare un slot credential facultatif portant le sélecteur feature.aggrega.ai/kind=secret, inject: [env] et sensitive: true, et un Aggregate le remplit sous la connexion, à uses.model.<alias>.features.credential. Ce que les composants de modèle de la bibliothèque standard publient à l’intention d’un consommateur est un emplacement de service et un nom de modèle, pas un identifiant, de sorte que la clé que l’agent présente lorsqu’il appelle ce point de terminaison est déclarée par l’agent et détenue sur sa connexion. Le slot est facultatif, mais une connexion qui atteint un modèle que son catalogue étiquette component.aggrega.ai/hosting: managed et qui ne porte aucun identifiant arrête le build, à moins que ses propres values n’indiquent que le modèle n’en demande aucun, unauthenticated: true — une assertion que porte l’entité de catalogue de l’agent, et que le compilateur évalue comme il évalue toute assertion, en lisant l’étiquette comme une chaîne. Le composant de modèle auquel il se connecte peut détenir une clé à lui pour ses propres appelants — core/ai-model/vllm déclare un slot api_key exactement pour cela — et les deux sont des points de liaison distincts : un attachement lie un slot par son nom là où il est déclaré, sur le composant ou sur la connexion, de sorte que remplir l’un ne dit rien de l’autre.
C’est ce placement qui fait des deux formes ci-dessous de véritables choix de déploiement : avec le slot sur le consommateur, un build peut donner à chaque consommateur sa propre clé et un autre peut leur donner à tous la même, sans qu’aucune entité de catalogue ne change entre les deux.
La même entité de catalogue sert les deux formes, et c’est l’auteur qui choisit laquelle :
- Par consommateur. Chaque consommateur remplit son propre slot avec son propre attachement d’identifiant — sur le composant, ou sur sa connexion lorsque le slot est celui d’un socket. Chacun obtient sa propre ressource rendue.
- Partagé. Pour un slot qu’un composant déclare, un identifiant est attaché une seule fois à une portée partagée — un sous-système dans l’Aggregate, une frontière dans la Release — et se propage en cascade à chaque composant de cette portée. Un slot qu’un socket déclare se remplit par connexion, et rien ne se propage en cascade dans une connexion, si bien que la forme partagée s’y écrit sur chaque connexion : l’identifiant de chaque connexion lit un même paramètre. Lorsque les consommateurs doivent référencer une seule ressource physique, ce paramètre la nomme —
core/referenced-secretlié à la réalisation existing-Secret fait pointer chaque connexion vers un seul Secret par son nom, et un identifiant généré est une requête et de nombreuses références, comme ci-dessous.
Il faut énoncer précisément le rendu de la forme partagée, car il est facile de supposer le contraire : un attachement partagé rend une ressource par consommateur, chacune portant le même contenu secret issu de l’unique déclaration. Le rendu s’exécute par composant, et un nom de ressource dérivé de {{ .context.instance_id }}-{{ .attachment_name }} diffère donc d’un consommateur à l’autre. C’est la déclaration unique qui est partagée ; les ressources émises ne sont pas dédupliquées en une seule. Un même paramètre lu sur chaque connexion se rend de la même manière sous une réalisation qui rend une ressource — une par connexion, le nom de l’attachement étant l’alias de la connexion, un point et le slot.
Si un déploiement a besoin d’exactement un seul Secret physique que plusieurs consommateurs lisent, exprimez-le avec une Feature d’identifiant dont la FeatureRecipe s’exécute à la portée de la frontière (executionScope: boundary), qui rend une seule fois pour la frontière plutôt qu’une fois par composant.
Une clé détenue par les deux extrémités d’une connexion
Un serveur qui vérifie une clé et le composant qui l’appelle détiennent chacun cette clé, chacun de son côté. Le serveur détient la clé qu’il vérifie dans un slot de son propre Component — core/ai-model/vllm, core/ai-model/tei et core/ai-model/tgi déclarent chacun api_key, tout comme le modèle et la passerelle LiteLLM pour la clé que LiteLLM appelle sa master key — et sa Recipe délivre ce qui remplit le slot sous la forme de la variable que lit le serveur. L’appelant détient la clé qu’il présente de son propre côté : sur la connexion où il la présente, dans un slot que déclare son socket — comme le socket model de core/ai-agent/crewai déclare credential — ou, lorsque son Component déclare la clé sur lui-même, dans ce slot, pour chaque connexion qu’il établit. Aucune extrémité ne voit les attachements de l’autre : un attachement sur une connexion n’atterrit que sur l’appelant, et la sortie rendue d’un serveur est la même quoi que portent les connexions qui l’atteignent. Le serveur n’apprend jamais quelle clé détient un appelant, et l’appelant ne lit que ce que le serveur publie — une adresse et un nom de modèle. Les deux extrémités s’accordent parce que l’Aggregate les alimente toutes deux à partir d’un même paramètre :
spec: parameters: model_key_secret: { type: string } components: model: type: core/ai-model/vllm values: { model: Qwen/Qwen2.5-0.5B-Instruct } features: api_key: # the key the server verifies type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key router: type: local/gateway/model-router # its `models` socket declares a `credential` slot uses: models: local: target: model features: credential: # the key the caller presents type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-keyQu’il s’agisse d’un secret ou de deux découle de l’endroit où les deux extrémités résolvent les secrets. Un provider résout un secret par référence au sein d’une portée de secrets : un namespace Kubernetes sur helm, un projet Compose sur compose, la configuration racine d’une frontière sur terraform et, sur cloudformation, une stack, dans le compte et la région AWS où elle est déployée. Lorsque les deux extrémités se trouvent dans une même portée, elles référencent une seule ressource secrète. Lorsqu’elles se trouvent dans des portées différentes, chaque extrémité détient sa propre ressource secrète, réalisée à partir de la même entrée du store. Le Manifest choisit la réalisation de chaque extrémité — par type de Feature ou, pour un attachement, par son nom, qui pour l’attachement d’une connexion est <alias>.<slot> (local.credential ci-dessus). Comme un même paramètre alimente les deux, les deux réalisations lisent origin comme le même genre de localisateur : toutes deux le nom d’un Secret, toutes deux la clé d’une entrée du store, ou toutes deux la valeur elle-même.
Sur helm, avec les deux extrémités dans un même namespace, lier core/referenced-secret à helm/k8s-existing-secret et satisfaire le paramètre avec le nom d’un Secret que contient ce namespace, model-keys, amène les deux extrémités à le référencer par son nom et ne rend aucun Secret. Le conteneur du serveur porte :
- name: VLLM_API_KEY valueFrom: secretKeyRef: name: model-keys key: api-keyet la Recipe du routeur lit le même nom et la même clé depuis sa connexion, à .context.uses.local.features.credential.provides. Avec les deux extrémités dans des namespaces différents, le lier à helm/k8s-external-secret et satisfaire le paramètre avec la clé d’une entrée du store donne à chaque extrémité son propre ExternalSecret, dans son propre namespace, tous deux récupérant cette même entrée. Sur compose, les deux extrémités portent la même référence ${VAR}, que Docker Compose substitue à partir de l’environnement avec lequel l’unique projet est démarré. Ce placement est une convention que suit le catalogue de la bibliothèque standard ; le compilateur ne compare rien entre les deux extrémités.
Une clé sert chaque appelant. vLLM, TEI et TGI vérifient chacun une seule clé, de sorte que chaque appelant présente la même clé et que le serveur ne peut distinguer un appelant d’un autre, quel que soit le nombre de connexions qui l’atteignent. C’est une limite propre au serveur. TGI compare sa clé sans tenir compte de la casse, de sorte que deux clés ne différant que par la casse sont pour lui une seule clé. Le modèle et la passerelle LiteLLM acceptent aussi les clés qu’ils émettent eux-mêmes, tant que leur base de données de comptabilité est attachée.
Un identifiant que la cible génère
Lorsqu’une Release ne fournit aucun identifiant, une entité de catalogue se rabat souvent sur une valeur par défaut de développement — une valeur en ligne dans une Recipe, une valeur par défaut sur le paramètre d’un module. Cette valeur est la même pour chaque lecteur du catalogue, ce qui est acceptable pour une évaluation et pour rien d’autre. core/random-password en supprime le besoin : personne n’écrit l’identifiant, parce que la cible le génère.
Le build ne peut pas être l’endroit où le mot de passe est créé. Sa sortie est une fonction pure de son entrée et ne porte jamais la valeur d’un secret, de sorte qu’un mot de passe tiré au moment du build changerait à chaque build et figurerait dans les fichiers rendus. La FeatureRecipe rend à la place une requête — une ressource génératrice nommant la ressource secrète qu’elle remplit — et la cible tire la valeur au moment du déploiement :
- sur
helm, un contrôleur dans le cluster : le générateur de mots de passe de l’External Secrets Operator, réconcilié par unExternalSecret, ou le contrôleur kubernetes-secret-generator, qui réconcilie unStringSecret; - sur
terraform, lerandom_passworddu provider random, tiré lorsque la configuration est appliquée ; - sur
cloudformation, un secret Secrets Manager qui génère sa propre chaîne lorsque la stack le crée.
Dans tous les cas, la sortie rendue nomme le générateur et la ressource secrète et ne porte aucune valeur. C’est une propriété de ce dont dispose le build, non une protection qu’il ajoute : la valeur n’existe jamais tant que la cible ne la crée pas. L’endroit où la cible la conserve ensuite relève de la cible — Terraform la conserve dans le plan et l’état, un cluster dans un Secret.
Ce que la cible doit faire tourner. Une requête n’est satisfaite que là où quelque chose la satisfait. Sur helm, c’est le contrôleur, et le compilateur ne peut pas inspecter le cluster pour savoir s’il en tourne un, si bien que les FeatureRecipes helm arrêtent le build à moins que la Release n’affirme le prérequis avec infra.control_plane_present: true sur l’attachement. Sur terraform et cloudformation, l’apply ou la stack génère la valeur elle-même et rien ne doit tourner au préalable.
Là où il ne peut pas être utilisé. Compose n’exécute aucun contrôleur et n’a aucune ressource qui génère une valeur, de sorte qu’aucune FeatureRecipe ne réalise core/random-password à cet endroit, et un build qui le lie sur compose s’arrête faute d’en avoir une. Une Release ciblant compose fournit son identifiant via core/secret-value, typiquement sous la forme d’une référence de variable que Docker Compose substitue au démarrage de la stack.
Comment un consommateur le lit. core/random-password publie les mêmes provides.name et provides.key que core/referenced-secret, et porte la même étiquette feature.aggrega.ai/kind: secret, de sorte qu’un slot qui sélectionne la famille des identifiants l’admet et qu’un consommateur lit un identifiant généré exactement comme il en lit un qui existe déjà.
Comment plusieurs consommateurs en partagent un. Un générateur tire une nouvelle valeur pour chaque requête, si bien que la règle de partage de la section précédente s’applique avec plus de tranchant : un identifiant généré attaché à une portée partagée — ou sur chaque consommateur — rend une requête par consommateur, et chaque requête tire un mot de passe différent, qu’une base de données et ses clients ne peuvent pas utiliser. Un identifiant généré partagé par plusieurs consommateurs s’exprime comme une requête et de nombreuses références : core/random-password sur un composant, avec sa valeur name fixant le Secret qu’il remplit, et core/referenced-secret sur les autres, lié à la réalisation existing-Secret et pointé vers ce même nom. Écrits à partir d’un même paramètre, les deux ne peuvent pas diverger, et le rendu porte exactement une requête que chaque consommateur référence.
core/random-password n’est pas core/generated-secret. Cette Feature remet un identifiant à un moteur qui en possède déjà tout le cycle de vie — une base de données managée, un contrôleur de base de données — et ne rend rien. core/random-password rend la requête elle-même, pour un workload dont la Recipe s’attend à recevoir un identifiant.
Priorité des attachements
Un attachement peut être déclaré à plusieurs portées à la fois. La propriété d’un champ disputé se résout par trois règles, appliquées dans cet ordre :
- Origine. Un champ écrit explicitement l’emporte sur un champ apporté par une expansion pilotée par les annotations, quelle que soit la portée d’où provient chacun.
- Autorité de composition. Une déclaration dans l’Aggregate que vous déployez l’emporte sur une déclaration située dans un Aggregate qu’il compose, même lorsque le document composé l’a déclarée à la portée plus étroite.
- Spécificité. Au sein d’un même niveau de rédaction, la portée la plus étroite affine la plus large champ par champ : un remplissage au niveau du composant remplace un attachement de même nom d’instance défini à l’échelle d’un sous-système ou d’une frontière uniquement pour les champs qu’il mentionne, et les champs qu’il omet conservent les valeurs de la portée plus large.
Le côté développeur fournit values et le côté opérateur fournit infra, de sorte que les deux ne se disputent jamais le même champ. Une Feature d’identifiant qui prend son localisateur de l’un ou l’autre côté le déclare sous forme de deux champs, un par pilier, et sa propre assertion refuse un attachement qui porte les deux, si bien que la priorité n’a là non plus aucune égalité à départager. La priorité ne régit que les valeurs des champs ; elle ne réordonne pas l’évaluation, qui suit la séquence de cascade décrite dans 10-compilation-pipeline.md.
Charts hérités qui exigent une chaîne formatée
Un chart veut parfois une seule chaîne de connexion dans laquelle le contenu secret est incorporé — oracle://admin:PASSWORD@HOST:1521/DB. Un compilateur ahead-of-time ne peut pas construire cette chaîne à partir d’une coordonnée du store, car il ne détient jamais le contenu secret. Deux voies prises en charge :
Templating côté cluster. La FeatureRecipe d’identifiant émet une ressource qui formate la chaîne dans le cluster, au moyen du templating propre à l’opérateur du coffre. L’application référence ensuite par son nom le Secret de plateforme résultant, et le compilateur a câblé la relation sans jamais détenir le contenu secret :
{ "apiVersion": "external-secrets.io/v1beta1", "kind": "ExternalSecret", "metadata": { "name": "oracle-dsn-secret" }, "spec": { "target": { "name": "oracle-formatted-dsn", "template": { "engineVersion": "v2", "data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" } } }, "data": [ { "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } } ] }}Remontée de paramètre. L’Aggregate déclare un paramètre typé et le pipeline CI environnant fournit la valeur au moment du build via les parameters: de la Release — par exemple un fichier que le pipeline écrit et que la Release importe avec parameters: { $import: ./ci-parameters.yaml }. C’est la porte de sortie explicite, et elle rend le compromis visible : le contenu secret transite désormais par le build, si bien que la sortie rendue le porte et doit être traitée en conséquence.
Développement local
La voie de référence pour le développement local garde l’intention du développeur inchangée et remplace la liaison. L’Aggregate continue d’attacher le même type de Feature d’identifiant ; le Manifest local associe ce type à une FeatureRecipe locale au lieu de celle adossée au store. Le compilateur ne récupère toujours rien — la FeatureRecipe locale délivre simplement une syntaxe native du provider que l’environnement d’exécution local résout : pour Compose, une référence de variable telle que ${SECRET_NAME} écrite dans l’environnement du service, que Docker Compose substitue à partir de l’environnement du shell ou d’un fichier .env au démarrage de la stack. Changer d’environnement est une modification du Manifest.
Gouvernance des données autour des identifiants
Aggrega ne modélise pas les schémas de données — lignes, colonnes et fichiers relèvent de l’application. Il modélise l’identité de gouvernance des données au moyen d’étiquettes, et la convention de la bibliothèque standard est la suivante :
- Les données résident dans des composants dont l’étiquette d’ontologie les marque comme stateful ou de type ressource (
component.aggrega.ai/type: stateful-server,resource). Un broker de messages qui conserve des charges utiles en file d’attente en fait aussi partie : il portestateful-serverlorsqu’il possède son propre disque etresourcelorsque la Release en câble un hébergé, et le rayonmessagingsous lequel on le parcourt relève de l’axe distinctcomponent.aggrega.ai/category. compliance.aggrega.ai/data-class(public,internal,restricted) donne à ces données une identité sémantique. La convention fixe la clé et ses valeurs, pas les composants qui la portent : aucun Component de la bibliothèque standard ne la porte, car la classe des données que détient un composant est une affirmation sur la manière dont un parc utilise le composant plutôt qu’une propriété du produit ; un parc la déclare donc sur ses propres Components. C’est une étiquette ordinaire : les sélecteurs d’étiquettes l’évaluent, et un plugin de gouvernance qu’un opérateur attache peut la lire et rejeter un build. Le compilateur lui-même ne l’interprète pas et ne place aucune classe au-dessus d’une autre — quelles classes existent et comment elles se classent relève des paramètres propres de la politique attachée, comme dans ../language-reference/examples/policy-data-class-route/.
data-class et sensitive sont deux axes, et les fusionner fait perdre de l’information. Ils se trouvent l’un à côté de l’autre et il est facile de les prendre pour une seule surface, retenez donc la distinction :
compliance.aggrega.ai/data-class | sensitive | |
|---|---|---|
| Forme | gradué — public / internal / restricted | booléen |
| Granularité | un nœud entier | une feuille de schéma, ou un slot d’attachement |
| Exprime | quelle identité de gouvernance ont les données que détient un composant | que cette donnée est un contenu secret, ou que ce point de liaison en traite |
| Écrit sous forme de | une étiquette dans metadata.labels | un mot-clé sur une déclaration |
Aucun ne remplace l’autre : forcer la sensibilité dans l’étiquette graduée imposerait un ordre à un fait qui n’en a pas, et forcer une classe de données sur une feuille imposerait une granularité que la classification n’a pas. Une entité peut porter les deux, et un composant détenant des données restricted dont le slot d’identifiant est déclaré sensitive énonce deux choses vraies distinctes. Les mots-clés de feuille et de slot sont présentés dans ../language-reference/vocabulary/compact-form-authoring.md « Déclarer une feuille sensible » et ../language-reference/entities/component.md « Déclarer un slot sensible ».
Le chiffrement au repos se situe délibérément hors de l’intention du développeur et hors du compilateur. Il relève de la Recipe Ops du composant stateful, et du plugin de rendu qui lit les étiquettes du nœud et émet la configuration de stockage chiffré. Ce placement est une orientation de conception sur l’endroit où cette préoccupation a sa place — le compilateur ne vérifie pas qu’une Recipe la respecte.
Ce qui est distinctif ici, et ce qui ne l’est pas
Le positionnement public mérite d’être énoncé simplement et de façon circonscrite, afin que le lecteur puisse s’étalonner.
Distinctif : le contrat de socket est publié, et non déclaré en ligne. Le contrat qu’un identifiant doit satisfaire — le slot, sa liste d’autorisation de livraison, son sélecteur de labels — est rédigé sur l’entité de catalogue par celui qui l’a publiée, et réside dans un catalogue qu’un tiers maintient. Un consommateur ne décrit pas le contrat en ligne dans sa propre configuration ; il remplit un contrat que quelqu’un d’autre a publié, et le compilateur vérifie ce remplissage par rapport à cette déclaration publiée. Le consommateur et l’auteur du contrat sont des personnes différentes, qui travaillent dans des dépôts différents, selon des cadences de publication différentes.
Distinctif : le remplissage est contraint par un sélecteur de labels. Un slot peut indiquer quel genre de chose peut le remplir (selector: "feature.aggrega.ai/kind=secret") plutôt que de nommer une implémentation précise. La vérification est une évaluation d’ensemble de labels, de sorte qu’une entité peut accepter une famille de remplissages dont elle n’a jamais entendu parler, et qu’un nouveau remplissage devient admissible en portant les bons labels.
Non distinctif : le mapping d’injection. Associer « ce nom de variable d’environnement locale reçoit cette valeur produite » est un modèle bien connu ; plusieurs outils de configuration et de déploiement expriment la même idée dans leur propre syntaxe. La version d’Aggrega est un mapping évalué à l’avance et fusionné dans un canal de livraison, mais l’idée appartient à l’écosystème, pas à nous.
Non distinctif : la génération statique anticipée. Générer statiquement des artefacts de déploiement à partir d’une description de plus haut niveau, sans accès à un cluster actif au moment de la génération, n’est pas une invention d’Aggrega. D’autres outils le font, et le faisaient avant qu’Aggrega n’existe. Ce qu’Aggrega ajoute, c’est la couche de contrats publiés au-dessus, pas la génération statique elle-même.
Pas une frontière de sécurité. Rien dans ce chapitre n’est un mécanisme de confidentialité. Le modèle d’identifiants est un modèle de câblage : il décide d’où vient un pointeur ou une valeur, qui peut le contraindre et comment il atteint un conteneur. Protéger le matériel est le rôle du coffre de secrets, du cluster et du pipeline qui traite l’arbre rendu.
Références croisées
- 05-invariants.md — les invariants de compilation anticipée et de canal de chaînes sur lesquels repose ce chapitre.
- 10-compilation-pipeline.md — où se situent dans le pipeline la résolution des attachements et la Resource Generation.
- ../language-reference/entities/component.md — la rédaction des slots de
featuresSchema, y compris la déclarationsensitiveau niveau du slot, le mot-clérequiredet la comparaison point par point entre un slot et une obligation de présence. - ../language-reference/vocabulary/compact-form-authoring.md — le mot-clé
sensitiveau niveau de la feuille, l’endroit où la déclaration est lue, et l’asymétrie deparameters:. - ../language-reference/entities/workload.md — la map
attachments:du conteneur et ses règles de validation. - ../language-reference/examples/04-secrets.md — la liste de contrôle de rédaction et des exemples complets transparent / blackbox.
- ../language-reference/examples/05-credential-features.md — les familles de Feature d’identifiants et un parcours de bout en bout.
- ../language-reference/examples/model-api-key-sharing/ — un slot d’identifiant que déclare le socket d’un agent, rempli sur chaque connexion de trois façons à partir d’une seule entité de catalogue : une clé par connexion, un seul Secret référencé par toutes les connexions, et une valeur par défaut partagée qu’une connexion remplace, avec la sortie rendue de chaque forme.