Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

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

fichiercible localecible avec magasin
aggregate.yamlle même fichierle même fichier
Manifestmanifest-local.yamlmanifest-store.yaml
Releaserelease-local.yamlrelease-store.yaml

Les deux Manifests diffèrent par leur propre nom et par une entrée de mappage :

Terminal window
$ diff manifest-local.yaml manifest-store.yaml
7c7
< name: credential-shape-local-manifest
---
> name: credential-shape-store-manifest
16c16
< 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.0

Les deux Releases diffèrent par leur propre nom et par le Manifest vers lequel elles pointent :

Terminal window
$ diff release-local.yaml release-store.yaml
7c7
< name: credential-shape-local
---
> name: credential-shape-store
12c12
< manifest: credential-shape-local-manifest
---
> manifest: credential-shape-store-manifest

Les 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-password

core/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: v1
kind: Secret
metadata:
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/v1
kind: ExternalSecret
metadata:
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/) :

Terminal window
$ diff -r local store
Only in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yaml
Only in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yaml
Only in store/helm/helm: db--password--db-externalsecret-db-password.yaml
Only in local/helm/helm: db--password--db-secret-db-password.yaml

Quatre 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_PASSWORD

Il 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-parameter l’écrit dans le Secret comme contenu.
  • k8s-external-secret le 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-password

Les 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 :

Terminal window
aggrega scaffold --example credential-shape-per-target

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd credential-shape-per-target

Build

Terminal window
aggrega build --release release-local.yaml --auto-pull
aggrega 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 :

Terminal window
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.

Terminal window
aggrega build --release release-local.yaml --verify-determinism
aggrega build --release release-store.yaml --verify-determinism

Avec 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 composant db de type core/datastore/postgres, dont les deux slots d’identification sont remplis par core/referenced-secret. Utilisé sans modification par les deux Releases.
  • manifest-local.yaml — lie core/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.