Un contrat, trois réalisations
Une base de données PostgreSQL et l’application qui la lit, déployées de trois façons différentes à partir d’un seul Aggregate inchangé : PostgreSQL exécuté dans le cluster, PostgreSQL en tant qu’instance cloud managée, et un serveur PostgreSQL qui existait déjà avant que cette Release ne soit déployée.
La leçon est ce qui ne change pas. L’application nomme une seule fois les clés qu’elle veut de la base de données et comment les appeler. Elle n’apprend jamais laquelle des trois a répondu. Le compilateur ne l’apprend pas non plus : il lit les clés que la Recipe sélectionnée a publiées et achemine les chaînes.
La seule chose qui varie
.-- helm/postgres ---------- a StatefulSet in the cluster /core/datastore/postgres --- terraform/postgres-rds -- an RDS instance in Terraform one Component \ one contract '- helm/postgres-external -- a server that already existsTrois Recipes implémentent le même Component. Chacune publie les mêmes clés provides — host, port, user, database, protocol, et les clés qui indiquent où un scraper trouve les métriques de la base de données, vides pour les trois. Celle qui s’exécute tient en une seule ligne du Manifest.
Fichiers
aggregate.yaml— l’intention du développeur, et le même document pour les trois Releases : un composantdbde typecore/datastore/postgres, uneappqui l’utilise viauses, et les cinq clés que l’application demande. Rien ici ne nomme une cible, un cloud ou une Recipe.manifest-selfhosted.yaml,manifest-managed.yaml,manifest-external.yaml— les correspondances Ops. Chacune choisit sa réalisation en une ligne : la Recipe à laquelle se lie le type de composant PostgreSQL. Celle de la variante managée lie aussi la Feature de sauvegarde que ses Releases rattachent.release-selfhosted.yaml,release-managed.yaml,release-external.yaml— le dimensionnement de l’opérateur dans chaque Release : stockage et version du moteur pour celle dans le cluster, stockage, HA et un rattachementcore/backuppour celle managée, et l’adresse du serveur existant pour celle référencée.release-managed-dns.yaml— la Release managée une fois de plus, avec le nom DNS que l’opérateur donne à l’instance, si bien que l’application reçoit un nom qu’elle peut résoudre.catalog/— le Component propre à l’application et l’unique Recipe qui le rend. Tout ce qui se trouve du côté de la base de données provient de la bibliothèque standard sans modification.
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 postgres-three-realizationsElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd postgres-three-realizationsBuild
aggrega build --release release-selfhosted.yaml --auto-pullaggrega build --release release-managed.yaml --auto-pullaggrega build --release release-managed-dns.yaml --auto-pullaggrega build --release release-external.yaml --auto-pull--auto-pull écrit le fichier de verrouillage de chaque Release lors de son premier build ; les builds suivants n’ont besoin d’aucun flag. Chacun écrit dans dist/, et un build ajoute ses fichiers au lieu d’effacer ce qu’un build précédent a laissé. Supprimez dist/ entre les exécutions pour lire la sortie d’une seule réalisation :
rm -rf dist && aggrega build --release release-managed.yamlAvec 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 Workspace ne contient pas encore de dossier `postgres-three-realizations`, appelez une fois l’outil `scaffold` avec `example` défini sur `postgres-three-realizations` et sans `dir` : il écrit l’exemple dans un nouveau dossier `postgres-three-realizations`. Appelez ensuite l’outil `build` une fois pour chaque Release, dans cet ordre — `release-selfhosted.yaml`, `release-managed.yaml`, `release-managed-dns.yaml` et `release-external.yaml` — en définissant à chaque fois `workspace_root` sur `postgres-three-realizations`, `release` sur ce fichier, `auto_pull` sur true et `write` sur true. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `postgres-three-realizations/dist/`.Ce que rend chacune
Auto-hébergé — la Release exécute le serveur
helm/postgres synthétise la base de données dans le cluster : un StatefulSet, un Service ClusterIP et un Service headless. provides.host est le nom nu de ce Service, si bien que l’application l’atteint par le DNS interne au cluster.
- name: DB_HOST value: db-defaultManagé — un fournisseur de cloud exécute le serveur
terraform/postgres-rds émet un aws_db_instance en HCL Terraform, et le dimensionnement ha et le rattachement core/backup de l’opérateur se reportent sur les paramètres natifs de l’instance : le retention_days: 14 du rattachement devient le backup_retention_period = 14 de l’instance. L’application est toujours rendue pour Kubernetes : les deux côtés de cette Release se rejoignent au contrat publié de la base de données, et non à une cible partagée.
- name: DB_HOST value: ${module.db.address}Cette valeur n’est pas un nom d’hôte, et rien dans ce build n’en fait un. L’adresse d’une instance RDS n’existe pas tant que l’instance n’est pas créée, si bien qu’il n’y a rien à rechercher pour un compilateur qui s’exécute en amont. Ce que publie la Recipe est une référence Terraform à une sortie du module propre à la base de données ; le compilateur la fait passer par l’arête sans la toucher, la Recipe de l’application la reçoit telle quelle, et elle est rendue dans le manifeste Kubernetes sous la forme des caractères littéraux montrés ci-dessus. C’est ce texte qui est remis au conteneur.
DB_PORT est différent : il est rendu comme "5432", parce que la Recipe définit le port de l’instance à partir de la Release et publie cette même valeur, qui est connue avant que quoi que ce soit n’existe.
Le câblage natif entre deux composants est quelque chose qu’une cible fait à l’intérieur de sa propre sortie, il n’y en a donc aucun à faire ici. Les deux extrémités de cette arête sont rendues via des cibles différentes — la base de données en HCL Terraform, l’application en manifeste Kubernetes — et une référence Terraform n’a de sens qu’à l’intérieur d’une configuration Terraform. En franchissant cette jonction, la valeur publiée est livrée sous forme de texte comme n’importe quelle autre chaîne. Un consommateur rendu sur Terraform en tant que Recipe source:, dans la même configuration racine que la base de données, reçoit la même référence comme l’un des arguments de son module, et c’est là que Terraform la résout.
C’est la règle générale et non un cas particulier pour RDS : tout ce qui dépend de l’état d’un système en cours d’exécution est exprimé comme un pointeur déterministe que le runtime résout, jamais comme une valeur que le compilateur récupère. Le rôle du compilateur est de livrer le pointeur inchangé. Faire en sorte qu’il se résolve là où il arrive revient à l’auteur de la Recipe : publier une adresse que le côté consommateur peut utiliser, ou donner aux deux composants des Recipes qui rendent vers la même cible.
Donner à l’instance un nom que l’application peut résoudre
terraform/postgres-rds accepte la première de ces solutions sous forme d’une option que l’opérateur définit. release-managed-dns.yaml est la Release managée avec un ajout, le nom DNS que l’opérateur donne à l’instance :
db: infra: overrides: host: db.internal.example.netLa Recipe publie ce nom comme host à la place de la référence Terraform, et l’application le reçoit :
- name: DB_HOST value: db.internal.example.net| variable | release-managed.yaml | release-managed-dns.yaml |
|---|---|---|
DB_HOST | ${module.db.address} | db.internal.example.net |
DB_PORT | 5432 | 5432 |
C’est la seule ligne de la sortie qui change. La Recipe n’émet aucun enregistrement DNS ni aucun alias pour le nom, et le build ne le résout pas : le compilateur le fait passer exactement comme il a fait passer la référence. Faire pointer db.internal.example.net vers l’instance une fois qu’elle existe — un enregistrement dans la zone DNS propre à l’opérateur, dirigé vers l’adresse de l’instance — revient à l’opérateur, en dehors de la Release. La clé est celle que la réalisation référencée ci-dessous lit pour la même adresse ; cette Recipe l’accepte comme un nom nu ou un littéral IP, et une valeur portant un schéma, un chemin, un utilisateur ou un port arrête le build, puisque le port est l’infra.port de la Release et qu’un consommateur compose sa connexion à partir des deux.
Un consommateur rendu dans la même configuration Terraform que la base de données reçoit lui aussi le nom, et perd avec lui l’ordre que la référence lui donnait : Terraform traite un module après un module qu’il référence, et un nom ne référence rien. Placer ce consommateur dans une frontière à lui qui partage le directory: de la base de données et porte un syncWave: ultérieur rétablit l’ordre.
Externe — personne dans cette Release n’exécute le serveur
helm/postgres-external ne provisionne absolument rien. Toute sa sortie est un Service qui associe un nom interne au cluster à l’adresse que fournit la Release :
[… omitted: the Service's apiVersion, kind and metadata — its name, db, and the labels and annotations every rendered document carries]spec: type: ExternalName externalName: postgres.data.example.net ports: - port: 5432Aucun StatefulSet, aucun volume, aucun conteneur — le cycle de vie du serveur se situe entièrement en dehors de cette Release. L’adresse vient de la Release :
db: infra: overrides: host: postgres.data.example.net- name: DB_HOST value: postgres.data.example.netRéférencer un serveur n’est pas la même chose que d’en prendre le contrôle. Cette Recipe atteint un serveur qui reste détenu en externe ; rien ici ne le place sous la gestion de la Release, et rien ici ne le modifiera.
Omettez l’adresse, et le build s’arrête et le dit. Un serveur référencé a une adresse ou n’a rien, si bien que la Recipe refuse plutôt que d’émettre un Service qui sert d’alias à un nom vide :
[… omitted: what resolving the lockfile prints, the same halt among it, then [CATALOG_ERROR E0033], the Recipe's assertion external_host_supplied, its template position and source, and "error calling fail:"]assertion failed: the Manifest selects the referenced realization ofPostgreSQL, which addresses a server it does not provision, but no address wassupplied: set infra.overrides.host on this component in the Release to the DNSname or IP literal the existing server answers onLa comparaison qui est l’essentiel
L’environnement rendu de l’application, les trois côte à côte :
| variable | auto-hébergé | managé | externe |
|---|---|---|---|
POOL_SIZE | 10 | 10 | 10 |
DB_HOST | db-default | ${module.db.address} | postgres.data.example.net |
DB_NAME | appdb | appdb | appdb |
DB_PORT | 5432 | 5432 | 5432 |
DB_PROTOCOL | postgres | postgres | postgres |
DB_USER | appuser | appuser | appuser |
Mêmes variables, même ordre, à chaque fois. Seule change la chaîne derrière l’une d’elles. La Recipe de l’application ne nomme aucune des variables DB_ : elle émet ce que l’arête uses a résolu, quoi que ce soit, et c’est pourquoi une seule Recipe se rend inchangée face aux trois bases de données.
Et le compilateur ne sait pas ce que sont ces chaînes. db-default est un nom de Service Kubernetes, ${module.db.address} est une référence Terraform, postgres.data.example.net est un nom DNS — pour le compilateur, ce sont trois chaînes qu’une Recipe a publiées sous la clé host et qu’une arête a demandé de livrer comme DB_HOST. Il ne vérifie pas que l’une d’elles est routable, ni qu’un port est un nombre, ni qu’un composant appelé db est une base de données. Il a fait correspondre l’arête sur le label que porte le Component, lu la clé que déclare le contrat, et déplacé le texte.
Où se trouve la jointure
Chacune des trois Releases a été choisie par une correspondance Ops, et le document du développeur n’a pas été touché par ce choix. C’est la séparation que tout l’exemple existe pour rendre concrète :
- le développeur dit ce dont l’application a besoin d’une base de données ;
- Ops dit de quoi est faite une base de données — une Recipe par réalisation ;
- l’opérateur dit laquelle reçoit cette Release, et la dimensionne.
Ajoutez demain une quatrième réalisation — un autre cloud, un autre opérateur, un service Compose pour le travail local — et il s’agit d’une Recipe de plus publiant les mêmes clés, plus une ligne de Manifest. Le aggregate.yaml de ce répertoire ne change pas.