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

Réseau entre frontières — une intention, deux déploiements

Une stack de deux composants — une interface de base de données Adminer et une base de données PostgreSQL — répartie sur deux frontières, où Adminer doit atteindre la base de données à travers la jointure de frontière. La même intention du développeur se déploie de deux façons, et le contraste est la leçon :

  • Local (Docker Compose) : chaque frontière est son propre réseau compose, et un service dans l’une ne peut pas atteindre par son nom un service dans l’autre. La FeatureRecipe compose de la Feature core/compose-bridge de la bibliothèque standard génère une passerelle aggrega-gw pour franchir cette jointure.
  • Kubernetes (Helm) : chaque frontière est son propre namespace, et un pod dans l’un atteint un Service dans un autre par le DNS natif inter-namespaces (db-default.backend) — pas de pont. La base de données publie un nom de service nu ; la fonctionnalité de routage core/k8s-dns-resolver du consommateur le qualifie avec le namespace cible.

Le compose-bridge, c’est ce que les namespaces Kubernetes + le DNS inter-namespaces vous donnent nativement. Le franchissement de la jointure est une préoccupation Ops/opérateur qui diffère selon la cible ; l’intention du développeur ne change pas. La même annotation de frontière aggrega.ai/namespace pilote le placement dans un réseau compose dans une variante et le placement dans un namespace Kubernetes dans l’autre.

L’intention du développeur partagée

aggregate.yaml est identique pour les deux variantes :

components:
adminer:
type: core/devtool/adminer
uses:
databases:
primary:
target: db
inject:
env:
- in: ADMINER_DEFAULT_SERVER # rewritten/resolved per variant
from: host # ← the target db's provides.host
db:
type: core/datastore/postgres

L’unique arête uses injecte le host de la base de données dans ADMINER_DEFAULT_SERVER. Ce vers quoi se résout cet hôte est une préoccupation Ops décidée en dessous de l’Aggregate — si bien que la même arête donne aggrega-gw:5432 sous compose et db-default.backend sous helm, sans aucun changement de l’intention du développeur.

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 cross-boundary-networking

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

Terminal window
cd cross-boundary-networking

Build

Chaque variante est une Release, compilée avec son propre répertoire de catalogue, une Release par exécution :

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

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 `cross-boundary-networking`, appelez une fois l’outil `scaffold` avec `example` défini sur `cross-boundary-networking` et sans `dir` : il écrit l’exemple dans un nouveau dossier `cross-boundary-networking`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `cross-boundary-networking`, `release` défini sur `release-compose.yaml`, `catalog_dirs` défini sur une liste contenant `catalog-compose`, `auto_pull` défini sur true et `write` défini sur true. Appelez ensuite l’outil `build` de la même manière avec `release` défini sur `release-helm.yaml` et `catalog_dirs` défini sur une liste contenant `catalog-helm`. Indiquez-moi les fichiers écrits par chaque build ; ils se trouvent sous `cross-boundary-networking/dist/`.

Variante A — local (Docker Compose) : le pont

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose

Une frontière parente bridge contient deux enfants, frontend (adminer) et backend (db), qui partagent un même répertoire si bien qu’ils fusionnent en un seul dist/bridge/compose/docker-compose.yaml. L’annotation aggrega.ai/namespace de chaque enfant devient un réseau compose. core/compose-bridge, rattachée au parent (portée de frontière), dérive une passerelle aggrega-gw de l’arête uses qui traverse les réseaux. Sa FeatureRecipe de la bibliothèque standard calcule, une seule fois pour la frontière, une table des arêtes à relier par le pont — les deux extrémités dans cet unique fichier compose, sur des réseaux différents — et tout ce qui suit est lu dans cette table par ses propres templates :

  • son valuesMapping écrit la configuration stream nginx de la passerelle, livrée sous forme de config compose montée (configs: de premier niveau, montée sur /etc/nginx/nginx.conf) ; elle porte un resolver et un proxy_pass à variable par arête pour que l’upstream se résolve au moment de la connexion (le $ est échappé en $$ pour que l’interpolation de Compose le laisse intact pour nginx) ;
  • le même valuesMapping nomme les deux extrémités sous le x-aggrega-networks-of de la passerelle, que résout le fournisseur compose, si bien que la passerelle rejoint les deux réseaux reliés par le pont ;
  • son injectMapping, exécuté pour adminer, réécrit le ADMINER_DEFAULT_SERVER du consommateur en aggrega-gw:5432. La réécriture remplace ce qu’avait livré la propre connexion databases d’adminer ; si une autre Feature rattachée à adminer avait livré cette variable, le build s’arrêterait en nommant les deux plutôt que de la remplacer.

Le trafic circule donc adminer → aggrega-gw:5432 → proxy_pass db:5432, en franchissant la jointure réseau par la passerelle.

Exécution

Terminal window
cd dist/bridge/compose
docker compose up

Ouvrez http://localhost:8080 (serveur prérempli avec aggrega-gw:5432) et connectez-vous :

ChampValeur
SystèmePostgreSQL
Serveuraggrega-gw:5432 (prérempli)
Nom d’utilisateurappuser
Mot de passeapppass
Base de donnéesappdb

Les informations d’identification sont réservées à la démonstration (définies en ligne dans la recipe du db pour que la stack fonctionne d’emblée) ; un déploiement réel utilise le sous-système d’identification.

Variante B — Kubernetes (Helm) : namespaces + DNS inter-namespaces

Terminal window
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

Le même Aggregate, déployé sur Kubernetes. Deux frontières sœurs, chacune avec une annotation aggrega.ai/namespace distincte qui se propage à chaque ressource sous forme de metadata.namespace :

dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontend
dist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontend
dist/backend/helm/db-statefulset.yaml # metadata.namespace: backend
dist/backend/helm/db-default-service.yaml # metadata.namespace: backend
dist/backend/helm/db-headless-service.yaml # metadata.namespace: backend

Il n’y a pas d’aggrega-gw. La recipe helm db publie un nom de service nu dans provides.host — le fournisseur helm nomme le Service synthétisé <rendered_name>-<service-key> (db-default), sans namespace. Le consommateur rattache la fonctionnalité de routage core/k8s-dns-resolver (la Release la dirige vers ADMINER_DEFAULT_SERVER), et la fonctionnalité qualifie cet hôte nu avec le namespace de la cible du côté du consommateur lui-même — produisant le nom DNS inter-namespaces db-default.backend avant le rendu d’Adminer. L’hôte est dérivé, et non écrit à la main dans le producteur :

dist/frontend/helm/adminer-deployment.yaml
- name: ADMINER_DEFAULT_SERVER
value: db-default.backend # == the rendered db Service <name>.<namespace>

Cette valeur correspond à l’octet près au metadata.name + metadata.namespace du Service db rendu, et c’est là toute la preuve : le DNS inter-namespaces de Kubernetes est un contrat déterministe, si bien que si l’hôte rendu est égal à l’identité du Service rendu, il se résout à l’exécution — pas de passerelle, pas de cluster actif nécessaire pour vérifier le câblage.

La dualité

compose (Variante A)helm (Variante B)
jointure de frontièreréseaux compose distinctsnamespaces distincts
mécanisme de franchissementpasserelle core/compose-bridge (aggrega-gw)DNS natif inter-namespaces
ADMINER_DEFAULT_SERVER se résout enaggrega-gw:5432 (réécrit)db-default.backend (qualifié côté appelant)
ressource supplémentairele service aggrega-gw + sa configurationaucune
le même aggrega.ai/namespace pilotele placement dans le réseau composele placement dans le namespace k8s

Une seule intention du développeur ; le franchissement de la jointure est une mécanique Ops/opérateur propre au fournisseur. Le pont compose existe parce qu’un réseau compose plat n’a pas de DNS à portée de namespace ; Kubernetes vous le donne nativement.

Quand les deux extrémités sont rendues par des fournisseurs différents

Les deux variantes ci-dessus conservent une seule intention du développeur et laissent le franchissement reposer sur une chaîne pointeur déterministe : le provides.host de la base de données traverse la jointure de frontière comme un pointeur stable, et chaque cible résout ce pointeur à sa manière — une adresse de passerelle compose, ou un nom DNS inter-namespaces. Le pointeur traverse toujours, parce que le compilateur achemine des chaînes entre un producteur et un consommateur sans les interpréter.

Un fournisseur peut aller plus loin et câbler une référence croisée native entre deux de ses propres artefacts assemblés de part et d’autre de la jointure — une référence dans le vocabulaire propre de ce fournisseur que la plateforme cible résout au moment du déploiement. Le fournisseur CloudFormation le fait pour une arête uses qui traverse des stacks : la stack productrice publie un Export et la stack consommatrice le lit avec Fn::ImportValue (voir providers/cloudformation.md). Une référence croisée native est une amélioration au sein d’un même fournisseur — elle fonctionne parce que les deux extrémités parlent le même vocabulaire d’artefacts, si bien qu’un côté peut publier une référence que l’autre côté sait résoudre.

Quand une arête uses traverse une frontière entre deux fournisseurs différents — le producteur est assemblé par un fournisseur et le consommateur par un autre — aucune référence croisée native n’est possible. Une référence forgée dans le vocabulaire d’un fournisseur ne signifie rien pour l’autre, et le compilateur ne traduit pas entre eux : il achemine des chaînes, il n’infère aucun sens et ne réécrit pas la référence d’un fournisseur dans la forme d’un autre. Le pointeur déterministe du producteur traverse donc la jointure sans changement ; là où l’un des deux fournisseurs câble ses propres références croisées natives, comme le fait CloudFormation, le compilateur émet un avertissement nommant les deux points de terminaison, les noms des deux fournisseurs et le socket ; et le build se termine sur ce pointeur. Le compilateur fait confiance à l’auteur et ne s’arrête pas : un pointeur déterministe fourni par l’auteur peut très bien être résoluble de part et d’autre de la jointure — un nom DNS stable ou une chaîne d’interpolation d’infrastructure — et seul l’auteur connaît la topologie cible.

Cela maintient le franchissement de la jointure là où il doit être. Savoir si un pointeur entre fournisseurs est utilisable est une question de déploiement qui revient à l’auteur ; traduire la référence native d’un fournisseur dans la forme consommatrice d’un autre fournisseur est un travail avec parti pris, propre au fournisseur, qui vit en dehors du noyau neutre.

Organisation

cross-boundary-networking/
├── .aggrega-config.yaml # marks this folder as the workspace root; names the hub registry
├── aggregate.yaml # SHARED developer intent (both variants)
├── release-compose.yaml # Variant A: parent bridge boundary + two networks
├── manifest-compose.yaml
├── catalog-compose/ # local adminer compose recipe (the component + the rest from standard)
├── release-helm.yaml # Variant B: two namespace boundaries, no bridge
├── manifest-helm.yaml
└── catalog-helm/ # local adminer helm recipe (the components + the rest from standard)

Cet exemple consomme la bibliothèque standard. Chaque variante se construit avec --catalog catalog-<variant>, son propre répertoire local, et résout ce que ce répertoire ne déclare pas depuis hub.aggrega.ai, le registre par défaut que nomme .aggrega-config.yaml, si bien que les entités locales se résolvent avant les entités partagées. core/datastore/postgres, le composant d’interface partagé core/devtool/adminer, les Features core/compose-bridge et core/k8s-dns-resolver avec leurs FeatureRecipes compose et helm, et les fournisseurs compose/helm viennent du catalogue standard. Ce qui reste local, c’est le contenu pédagogique propre à l’exemple : les recipes Adminer par cible. La recipe helm db est le helm/postgres de la bibliothèque standard, dont le provides.host est un nom de service nu et autonome. Le consommateur le qualifie avec le namespace cible côté appelant via la fonctionnalité de routage core/k8s-dns-resolver de la bibliothèque standard, si bien que la recipe ne code en dur aucun namespace de frontière.

Deux catégories de fichiers se rencontrent dans une variante construite : les entrées écrites (tout ce qui précède) et la sortie générée par le compilateur sous dist/ (le docker-compose.yaml fusionné, ou les manifests helm par namespace) — vous n’écrivez rien de cette dernière. dist/ est régénéré par aggrega build et est ignoré par git.