Une seule intention du développeur, deux formes de livraison des informations d’identification
La façon dont une information d’identification atteint un conteneur en cours d’exécution est une propriété de l’endroit où vous déployez, et non de l’application. Un cluster n’a pas de magasin de secrets, si bien que le déploiement livre le contenu lui-même dans un Secret Kubernetes. Un autre exécute un opérateur de magasin de secrets, si bien que le déploiement ne livre qu’un pointeur et que le cluster récupère le contenu au moment de la réconciliation.
Cet espace de travail contient un Aggregate et le construit pour deux cibles. L’Aggregate ne change pas de l’une à l’autre. La référence de la base de données à son mot de passe non plus. Ce qui change, c’est une ligne dans un Manifest.
Ce qui bouge, et ce qui reste fixe
| fichier | cible locale | cible avec magasin |
|---|---|---|
aggregate.yaml | le même fichier | le même fichier |
| Manifest | manifest-local.yaml | manifest-store.yaml |
| Release | release-local.yaml | release-store.yaml |
Les deux Manifests diffèrent par leur propre nom et par une entrée de mappage :
$ diff manifest-local.yaml manifest-store.yaml7c7< name: credential-shape-local-manifest---> name: credential-shape-store-manifest16c16< core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0---> core/referenced-secret:1.0.0: helm/k8s-external-secret:1.0.0Les deux Releases diffèrent par leur propre nom et par le Manifest vers lequel elles pointent :
$ diff release-local.yaml release-store.yaml7c7< name: credential-shape-local---> name: credential-shape-store12c12< manifest: credential-shape-local-manifest---> manifest: credential-shape-store-manifestLes deux Releases déclarent le même environment. C’est délibéré : le nom de l’environnement est apposé sur chaque document rendu sous forme de label, si bien que le maintenir fixe ne laisse libre de bouger qu’une seule chose — la FeatureRecipe que lie le Manifest. Une vraie paire de Releases nommerait bien sûr ses propres environnements, et les formes des informations d’identification différeraient exactement de la même façon.
Le côté du développeur, une seule fois
aggregate.yaml remplit les deux slots d’identification du Component PostgreSQL avec la même Feature d’identification référençable :
features: password: type: core/referenced-secret values: key: POSTGRES_PASSWORD origin: postgres-superuser-password app_user_password: type: core/referenced-secret values: key: APP_USER_PASSWORD origin: postgres-app-passwordcore/referenced-secret nomme une ressource de secret, créée par la sortie de sa FeatureRecipe ou déjà existante, et publie le localisateur de cette ressource — son name et la key de données qu’elle contient — par son contrat provides. La Recipe consommatrice lit ce localisateur. Elle ne dérive jamais de nom de ressource qui lui soit propre, et elle ne demande jamais quelle FeatureRecipe l’a produite.
Ce qu’émet chaque cible
Chaque build écrit six fichiers. Quatre d’entre eux — le StatefulSet, les deux Services et la ConfigMap d’initialisation — sortent identiques à l’octet près des deux cibles. Les deux autres sont les ressources d’identification, une par slot rempli, et c’est là que les cibles diffèrent.
Cible locale, issue de k8s-secret-from-parameter, dans dist/helm/helm/db--password--db-secret-db-password.yaml :
apiVersion: v1kind: Secretmetadata: name: db-password [… omitted: the labels and annotations naming the aggregate, component, environment, compiler and provider versions, boundary and Recipe — the same set every rendered document carries]stringData: POSTGRES_PASSWORD: "postgres-superuser-password"Cible avec magasin, issue de k8s-external-secret, dans dist/helm/helm/db--password--db-externalsecret-db-password.yaml :
apiVersion: external-secrets.io/v1kind: ExternalSecretmetadata: name: db-password [… omitted: the same label and annotation set as above]spec: refreshInterval: "1h" secretStoreRef: name: platform-secret-store kind: ClusterSecretStore target: name: db-password creationPolicy: Owner data: - secretKey: POSTGRES_PASSWORD remoteRef: key: "postgres-superuser-password"Groupe d’API différent, kind différent, corps différent. Sur la cible locale, le contenu de l’information d’identification se trouve dans le document rendu, lisible par quiconque peut lire les ressources déployées — c’est pourquoi cette forme convient aux clusters locaux et de développement plutôt qu’à un cluster de production. Sur la cible avec magasin, le document rendu ne porte que le nom de l’entrée ; le contenu reste dans le magasin et l’opérateur le réconcilie en un Secret nommé db-password.
Comparer les deux arborescences de sortie montre la différence et montre où elle s’arrête (la section Build ci-dessous contient les commandes qui produisent local/ et store/) :
$ diff -r local storeOnly in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yamlOnly in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yamlOnly in store/helm/helm: db--password--db-externalsecret-db-password.yamlOnly in local/helm/helm: db--password--db-secret-db-password.yamlQuatre lignes, toutes dans un même répertoire, parce que sur cette cible les fichiers d’un rattachement se trouvent à côté de ceux du composant plutôt que dans un sous-répertoire. C’est le nom de fichier qui porte les deux coordonnées : db--password-- est le rattachement password sur db, et db--app-zuuser-zupassword-- est celui de app_user_password — le tiret bas encodé en -zu, parce que la coordonnée et le nom propre du fichier partagent ici une seule chaîne.
Quatre lignes, et rien d’autre : deux ressources d’identification présentes uniquement dans l’arborescence de la cible locale, deux présentes uniquement dans celle de la cible avec magasin. diff -r ne signale aucune différence de contenu dans aucun fichier que partagent les deux arborescences, si bien que les quatre documents communs sont identiques et pas seulement similaires.
La référence qui ne bouge pas
Le conteneur de la base de données lit les deux informations d’identification comme des variables d’environnement adossées à un secretKeyRef. Ce bloc est identique à l’octet près sur les deux cibles :
- name: POSTGRES_PASSWORD valueFrom: secretKeyRef: name: db-password key: POSTGRES_PASSWORD- name: APP_USER_PASSWORD valueFrom: secretKeyRef: name: db-app-user-password key: APP_USER_PASSWORDIl est identique parce que la Recipe consommatrice ne bifurque pas. Elle demande au slot son name et sa key publiés et les écrit. Les deux FeatureRecipes publient les deux mêmes clés parce que la Feature les déclare, si bien que l’une ou l’autre satisfait le consommateur — et sur la cible avec magasin, la référence se résout une fois que l’opérateur a réconcilié l’ExternalSecret en un Secret sous ce nom.
C’est cette invariance qui rend les deux formes substituables. Si le côté consommateur avait dérivé lui-même le nom du Secret, changer de liaison l’aurait laissé pointer vers une ressource qui n’existait plus sous ce nom.
origin signifie ce que la FeatureRecipe dit qu’il signifie
core/referenced-secret déclare origin comme la provenance du contenu, et en laisse l’interprétation à la FeatureRecipe :
k8s-secret-from-parameterl’écrit dans le Secret comme contenu.k8s-external-secretle lit comme la clé à récupérer depuis le magasin.
Le compilateur achemine la chaîne sans la modifier ; il est agnostique vis-à-vis de celle de ces deux lectures que représente une chaîne donnée. C’est ce qui permet à un seul rattachement de servir les deux formes sans aucune modification du côté du développeur — et c’est ce qu’il faut vérifier avant de changer de liaison, parce que la même chaîne écrite doit avoir un sens pour la FeatureRecipe qui la lit, quelle qu’elle soit.
Le nom publié, et le tiret bas dans un nom de slot
Le Component nomme son second slot d’identification app_user_password. Un nom d’objet Kubernetes ne peut pas contenir de tiret bas, si bien que le provides.name publié normalise les tirets bas en traits d’union, et la ressource aboutit sous le nom db-app-user-password :
- name: APP_USER_PASSWORD valueFrom: secretKeyRef: name: db-app-user-passwordLes deux FeatureRecipes normalisent de façon identique, c’est pourquoi changer de liaison ne déplace pas la référence du consommateur. Le nom est publié une seule fois, du côté producteur, et la ressource émise comme la référence du consommateur se résolvent à partir de cette unique valeur publiée.
Ce que la cible avec magasin attend du cluster
ExternalSecret est une ressource personnalisée. Appliquer la sortie de la cible avec magasin à un cluster exige qu’un opérateur de magasin de secrets y soit en cours d’exécution, et qu’un ClusterSecretStore nommé platform-secret-store existe. Rien dans cet espace de travail n’installe l’un ou l’autre : l’exemple rend ce qu’un tel cluster consomme, et enseigne comment la forme est choisie.
Le magasin qu’exécute un cluster, et sous quel nom, est une propriété de la cible plutôt que de l’application, si bien que k8s-external-secret ne porte aucune clé de rédaction pour cela. Un cluster dont le magasin porte un autre nom est servi par une FeatureRecipe qui nomme ce magasin.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example credential-shape-per-targetElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd credential-shape-per-targetBuild
aggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pull--auto-pull résout le catalogue dans un lockfile à côté de la Release lors du premier build ; les builds suivants de la même Release n’ont besoin d’aucun flag.
Les deux cibles écrivent dans dist/, et aggrega build ne le vide pas, mettez donc de côté la sortie de chaque exécution pour comparer les deux :
out=$(mktemp -d)rm -rf dist && aggrega build --release release-local.yaml --auto-pull && cp -r dist "$out/local"rm -rf dist && aggrega build --release release-store.yaml --auto-pull && cp -r dist "$out/store"( cd "$out" && diff -r local store )Pour confirmer que chaque cible rend de façon déterministe, ajoutez --verify-determinism : chaque nœud est rendu deux fois et le build s’arrête si les deux rendus d’un nœud diffèrent.
aggrega build --release release-local.yaml --verify-determinismaggrega build --release release-store.yaml --verify-determinismAvec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `credential-shape-per-target`, appelez une fois l’outil `scaffold` avec `example` défini sur `credential-shape-per-target` et sans `dir` : il écrit l’exemple dans un nouveau dossier `credential-shape-per-target`. Appelez ensuite l’outil `build` une fois pour chaque Release, dans cet ordre — `release-local.yaml`, `release-store.yaml` — en définissant à chaque fois `workspace_root` sur `credential-shape-per-target`, `release` sur ce fichier, `auto_pull` sur true et `write` sur true. Indiquez-moi les fichiers écrits par chaque build ; ils se trouvent sous `credential-shape-per-target/dist/`.Fichiers
aggregate.yaml— intention du développeur : un composantdbde typecore/datastore/postgres, dont les deux slots d’identification sont remplis parcore/referenced-secret. Utilisé sans modification par les deux Releases.manifest-local.yaml— liecore/referenced-secretàk8s-secret-from-parameter, qui rend un Secret Kubernetes à partir du contenu écrit.manifest-store.yaml— lie la même Feature àk8s-external-secret, qui rend un ExternalSecret nommant l’entrée du magasin. Identique àmanifest-local.yamlà part son propre nom et cette unique ligne.release-local.yaml,release-store.yaml— les deux Releases. Identiques à part leurs propres noms et le Manifest vers lequel chacune pointe..aggrega-config.yaml— nomme le registre du hub depuis lequel se résolvent les entités du catalogue.
Les valeurs de origin ici sont des espaces réservés. Ce ne sont des informations d’identification pour aucun service réel, et sur la cible locale, les deux sont rendues en clair dans la sortie.