Features d’informations d’identification
Cette page explique une seule idée, les Features d’informations d’identification de la bibliothèque standard et la manière dont un Manifest choisit ce qui réalise chacune d’elles, et n’est pas un espace de travail exécutable. Une seule intention du développeur, deux formes de livraison des informations d’identification effectue le build d’un Aggregate avec deux réalisations des mêmes informations d’identification ; écrivez-le dans un dossier à vous avec :
aggrega scaffold --example credential-shape-per-targetElle affiche ensuite les prochaines commandes à exécuter :
cd credential-shape-per-targetaggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pullDes informations d’identification remplissent un emplacement qu’un Component déclare dans son featuresSchema (voir entities/component.md) ; l’emplacement, la Feature qui le remplit et la FeatureRecipe que lie le Manifest forment le chemin complet, du rattachement d’un auteur jusqu’à une charge de travail en cours d’exécution.
La famille de Feature d’informations d’identification
Une Feature d’informations d’identification porte l’étiquette feature.aggrega.ai/kind: secret. L’étiquette est une métadonnée du catalogue qui décrit ce que produit le rattachement ; aucune branche du compilateur ne la lit, et une Feature d’informations d’identification se rattache sous features: comme toute autre Feature, par le développeur dans l’Aggregate ou par l’opérateur dans la Release.
La bibliothèque standard répartit les Features d’informations d’identification selon ce que la réalisation fait du secret :
core/secret-valuelivre une valeur dans le canal d’injection du composant, où sa Recipe la lit — une valeur de chart, une variable d’environnement.core/secret-providedproduit elle aussi une valeur, mais la publie plutôt comme cléprovides, de sorte que le propre blocinject:du rattachement, sur un emplacement transparent, indique où elle va.core/referenced-secretnomme une ressource de secret — un Secret Kubernetes, un secret AWS Secrets Manager, une entrée Vault — que crée sa réalisation ou qui existe déjà, et publie lenameet lekeyde cette ressource, que lit un consommateur sous la forme.features.<slot>.provides.nameet.features.<slot>.provides.key.core/referenced-secret-setmatérialise une telle ressource contenant un ensemble de clés de données fourni par l’auteur, et ne publie que son localisateur, pour un consommateur dont la cible fixe déjà les noms de clés qu’il lit. Docker Compose n’a pas de telle ressource ; sa réalisation y livre donc les clés sous forme de valeurs, comme décrit ci-dessous. MariaDB (chart Bitnami) — un seul Secret d’informations d’identification à plusieurs clés l’utilise.core/generated-secretne produit rien : le moteur cible génère et gère lui-même les informations d’identification, comme le fait une base de données managée avec son mot de passe d’administrateur. L’opérateur la rattache dans la Release, car le fait que le moteur possède les informations d’identification découle de la Recipe que choisit le Manifest ; Terraform RDS (artefact HCL en ligne) lie ainsi un emplacement obligatoire.core/random-passwordeffectue le rendu d’une demande adressée à la cible de générer un mot de passe dans une ressource de secret, et publie le localisateur de cette ressource comme le faitcore/referenced-secret. Personne n’écrit les informations d’identification et la sortie rendue n’en porte aucune.
Elles sont de même rang — même étiquette, même surface de rattachement, même emplacement — de sorte qu’un emplacement est toujours rempli, et ce qui change entre les Releases, c’est ce qui le remplit. Une Feature d’informations d’identification qui déclare un contrat provides oblige chaque FeatureRecipe qui l’implémente à publier ces clés, et le build s’arrête si l’une d’elles ne le fait pas ; c’est ce qui rend sûre la lecture du consommateur.
core/random-password a besoin de quelque chose sur la cible pour tirer la valeur, puisque le build ne le fait jamais : sur Kubernetes, un contrôleur (l’External Secrets Operator, ou kubernetes-secret-generator) dont la Release affirme la présence avec infra.control_plane_present: true ; sur Terraform, une ressource random_password ; sur CloudFormation, un secret Secrets Manager qui génère sa propre chaîne. Aucune réalisation n’est livrée pour Docker Compose, donc un build qui la lie là s’arrête. Chaque demande tire sa propre valeur, donc deux composants partagent un même mot de passe généré en le rattachant une seule fois, avec name fixé, et en le lisant ailleurs au moyen de core/referenced-secret liée à helm/k8s-existing-secret.
Qui nomme les informations d’identification : values ou infra, exactement un
core/secret-value, core/secret-provided, core/referenced-secret et core/referenced-secret-set acceptent le localisateur des informations d’identification de l’un ou l’autre auteur : le développeur l’écrit dans les values du rattachement dans l’Aggregate, l’opérateur dans l’infra du rattachement dans la Release. La feuille est la même dans les deux — origin, ou entries pour l’ensemble — et chaque réalisation lit celui des piliers qui la porte.
La forme de l’opérateur est ce qui rend des informations d’identification utilisables là où le développeur ne peut pas en écrire : sur une connexion que câble la Release, et sur un rattachement que fait la Release seule, puisqu’une Release n’écrit values nulle part.
# Release: the operator wires the connection and names the secret.spec: components: router: uses: models: gpt: target: gpt features: credential: type: core/referenced-secret infra: origin: openai-team-aExactement un des deux. Chaque pilier est validé isolément, donc aucun des deux schémas ne peut exiger le localisateur ; ce sont plutôt les propres assertions de chaque Feature qui portent la règle, et un rattachement qui porte le localisateur dans les deux piliers, ou dans aucun, arrête le build (E0033) en nommant la Feature, le rattachement et le composant. C’est le contrat des entités du catalogue : le compilateur évalue leur assertion comme il évalue celle de toute Feature.
Tout le reste garde son pilier. key reste une feuille de values, donc un rattachement que fait seule la Release lit la clé de données par défaut, value. Déclarer origin dans les deux piliers est exactement ce que recherche l’avertissement de chevauchement de piliers, donc le chargement de ces Features le signale — LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars. Ici, le chevauchement est le contrat ; l’avertissement ne change aucun verdict ni aucun octet rendu.
Le Manifest choisit la réalisation
Plusieurs FeatureRecipes peuvent implémenter une Feature pour la même cible, et le Manifest choisit. core/referenced-secret en a trois sur Kubernetes, et c’est l’endroit où se trouvent les informations d’identification qui décide entre elles :
helm/k8s-secret-from-parameterécrit la valeur fournie par un auteur dans un Secret qu’elle émet, de sorte que le matériau se trouve dans la sortie rendue : pour l’évaluation et le travail local.helm/k8s-external-secreteffectue le rendu d’unExternalSecretnommant une entrée dans un magasin de secrets, que l’External Secrets Operator du cluster réconcilie en Secret.helm/k8s-existing-secretn’émet rien : elle litorigincomme le nom d’un Secret qui existe déjà et le publie tel qu’écrit.
Les deux premières dérivent le nom du Secret de la même façon, à partir du nom rendu de l’hôte et de celui de l’emplacement, de sorte qu’un consommateur lit le même localisateur depuis l’une ou l’autre et que sa référence rendue reste inchangée ; c’est ce que montre l’exemple. La troisième publie le nom propre du Secret existant, de sorte que la lier change à dessein la référence du consommateur.
core/secret-value est réalisée sur Docker Compose par compose/dotenv-secret, qui écrit la valeur dans l’environnement du service exactement telle qu’elle a été rédigée : un origin écrit sous la forme ${DB_PASSWORD} y arrive comme cette référence, que Docker Compose remplit depuis votre shell ou un fichier .env au démarrage de la stack. Sur Kubernetes, helm/env-secret livre la valeur dans le canal d’injection, et helm/k8s-secret-from-value l’écrit en outre dans un Secret et publie son localisateur, pour un consommateur qui lit les informations d’identification par référence. Aucune des deux réalisations Kubernetes n’accepte une référence de variable Compose, que rien n’y remplirait.
core/referenced-secret est réalisée sur Docker Compose par compose/dotenv-referenced-secret. Compose n’a aucune ressource secrète à référencer, donc origin est l’information d’identification elle-même plutôt que le nom d’un Secret : elle est livrée dans le canal d’injection sous la key du rattachement, et une Recipe Compose qui lit le slot l’écrit dans le fichier émis exactement telle qu’elle a été rédigée, si bien qu’un origin écrit ${DB_PASSWORD} y arrive sous la forme de cette référence. Elle ne crée aucune ressource, donc le nom qu’elle publie est vide et la clé qu’elle publie est values.key.
core/referenced-secret-set est réalisée sur Docker Compose par compose/dotenv-secret-set, qui livre chaque entrée dans le canal d’injection comme une variable portant le nom de sa clé, écrite dans l’environnement du service exactement telle qu’elle a été rédigée, si bien qu’une entrée dont la valeur est ${GITHUB_TOKEN} arrive sous la forme de cette référence. Elle ne crée aucune ressource, donc le localisateur qu’elle publie est vide : un consommateur sur Compose lit les entrées depuis son canal d’injection plutôt que de référencer un Secret par son nom, comme le font compose/mcp et compose/mcp-stdio-bridge depuis la 1.1.0 pour le server_env d’un serveur Model Context Protocol.
Un nom de FeatureRecipe livré pour plus d’une cible, comme provided-secret, s’écrit avec sa cible dans le Manifest, compose/provided-secret:1.0.0, puisque le nom seul correspond aux deux.
Un nom, publié une seule fois
La Recipe d’un consommateur ne dérive jamais le nom du Secret que produisent des informations d’identification : elle lit le localisateur qu’elles publient, existingSecret: "{{ .features.root_password.provides.name }}". Le nom est rédigé une seule fois, dans le provides de la FeatureRecipe, donc changer la façon dont il est composé est une modification à cet endroit seulement. Livraison des informations d’identification — secretKeyRef de bout en bout construit le chemin référençable sur Kubernetes et le chemin injecté sur Docker Compose, et Partager des informations d’identification — par consommateur, partagées, et les deux à la fois montre plusieurs consommateurs qui détiennent chacun leur propre clé ou en partagent une.