Rete tra confini — un intento, due distribuzioni
Uno stack di due componenti — un’interfaccia di database Adminer e un database PostgreSQL — suddiviso su due confini, dove Adminer deve raggiungere il database attraverso la giunzione del confine. Lo stesso intento dello sviluppatore viene distribuito in due modi, e il contrasto è la lezione:
- Locale (Docker Compose): ogni confine è una rete compose a sé, e un servizio in uno non può raggiungere per nome un servizio nell’altro. La FeatureRecipe compose della Feature
core/compose-bridgedella libreria standard genera un gatewayaggrega-gwper attraversare quella giunzione. - Kubernetes (Helm): ogni confine è un proprio namespace, e un pod in uno raggiunge un Service in un altro tramite il DNS nativo tra namespace (
db-default.backend) — nessun ponte. Il database pubblica un nome di servizio nudo; la funzionalità di instradamentocore/k8s-dns-resolverdel consumatore lo qualifica con il namespace di destinazione.
Il compose-bridge è ciò che i namespace Kubernetes + il DNS tra namespace ti danno nativamente. L’attraversamento della giunzione è una questione di Ops/operatore che varia a seconda della destinazione; l’intento dello sviluppatore non cambia. La stessa identica annotazione di confine aggrega.ai/namespace guida il posizionamento nella rete compose in una variante e il posizionamento nel namespace Kubernetes nell’altra.
L’intento dello sviluppatore condiviso
aggregate.yaml è identico per entrambe le varianti:
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/postgresL’unico arco uses inietta l’host del database in ADMINER_DEFAULT_SERVER. Ciò in cui si risolve quell’host è una questione di Ops decisa al di sotto dell’Aggregate — quindi lo stesso arco produce aggrega-gw:5432 con compose e db-default.backend con helm, senza alcuna modifica all’intento dello sviluppatore.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example cross-boundary-networkingPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd cross-boundary-networkingBuild
Ogni variante è una Release, compilata rispetto alla propria directory di catalogo, una Release per esecuzione:
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeaggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmCon un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella dell’area di lavoro non contiene ancora una cartella `cross-boundary-networking`, chiama una volta lo strumento `scaffold` con `example` impostato a `cross-boundary-networking` e senza `dir`: scrive l’esempio in una nuova cartella `cross-boundary-networking`. Poi chiama lo strumento `build` con `workspace_root` impostato a `cross-boundary-networking`, `release` impostato a `release-compose.yaml`, `catalog_dirs` impostato a un elenco contenente `catalog-compose`, `auto_pull` impostato a true e `write` impostato a true. Poi chiama lo strumento `build` nello stesso modo con `release` impostato a `release-helm.yaml` e `catalog_dirs` impostato a un elenco contenente `catalog-helm`. Dimmi quali file ha scritto ciascuna build; si trovano in `cross-boundary-networking/dist/`.Variante A — locale (Docker Compose): il ponte
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeUn confine padre bridge contiene due figli, frontend (adminer) e backend (db), che condividono un’unica directory e quindi confluiscono in un unico dist/bridge/compose/docker-compose.yaml. L’annotazione aggrega.ai/namespace di ciascun figlio diventa una rete compose. core/compose-bridge, associata al padre (ambito di confine), ricava un gateway aggrega-gw dall’arco uses tra reti. La sua FeatureRecipe della libreria standard calcola, una sola volta per il confine, una tabella degli archi da collegare tramite il ponte — entrambi i capi in quest’unico file compose, su reti diverse — e tutto ciò che segue viene letto da quella tabella dai suoi stessi template:
- il suo
valuesMappingscrive la configurazionestreamdi nginx del gateway, consegnata come config compose montata (configs:di primo livello, montata in/etc/nginx/nginx.conf); porta unresolvere unproxy_passcon variabile per arco, così l’upstream si risolve al momento della connessione (il$è sottoposto a escape come$$così l’interpolazione di Compose lo lascia intatto per nginx); - lo stesso
valuesMappingnomina entrambi i capi sottox-aggrega-networks-ofdel gateway, che il provider compose risolve, così il gateway si unisce a entrambe le reti collegate dal ponte; - il suo
injectMapping, eseguito per adminer, riscriveADMINER_DEFAULT_SERVERdel consumatore inaggrega-gw:5432. La riscrittura sostituisce ciò che aveva consegnato la connessionedatabasespropria di adminer; se a consegnare quella variabile fosse stata un’altra Feature associata ad adminer, il build si arresterebbe nominando entrambe anziché sostituirla.
Così il traffico scorre adminer → aggrega-gw:5432 → proxy_pass db:5432, attraversando la giunzione di rete tramite il gateway.
Esecuzione
cd dist/bridge/composedocker compose upApri http://localhost:8080 (server precompilato con aggrega-gw:5432) e accedi:
| Campo | Valore |
|---|---|
| Sistema | PostgreSQL |
| Server | aggrega-gw:5432 (precompilato) |
| Nome utente | appuser |
| Password | apppass |
| Database | appdb |
Le credenziali sono solo dimostrative (impostate inline nella recipe del db così lo stack funziona subito); una distribuzione reale usa il sottosistema delle credenziali.
Variante B — Kubernetes (Helm): namespace + DNS tra namespace
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmLo stesso Aggregate, distribuito su Kubernetes. Due confini fratelli, ciascuno con un’annotazione aggrega.ai/namespace distinta che si propaga a ogni risorsa come metadata.namespace:
dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontenddist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontenddist/backend/helm/db-statefulset.yaml # metadata.namespace: backenddist/backend/helm/db-default-service.yaml # metadata.namespace: backenddist/backend/helm/db-headless-service.yaml # metadata.namespace: backendNon c’è alcun aggrega-gw. La recipe helm db pubblica un nome di servizio nudo in provides.host — il provider helm chiama il Service sintetizzato <rendered_name>-<service-key> (db-default), senza namespace. Il consumatore associa la funzionalità di instradamento core/k8s-dns-resolver (la Release la punta su ADMINER_DEFAULT_SERVER), e la funzionalità qualifica quell’host nudo con il namespace della destinazione dal lato del consumatore stesso — producendo il nome DNS tra namespace db-default.backend prima che Adminer venga renderizzato. L’host è derivato, non scritto a mano nel produttore:
- name: ADMINER_DEFAULT_SERVER value: db-default.backend # == the rendered db Service <name>.<namespace>Quel valore corrisponde byte per byte a metadata.name + metadata.namespace del Service db renderizzato, e questa è l’intera prova: il DNS tra namespace di Kubernetes è un contratto deterministico, quindi se l’host renderizzato è uguale all’identità del Service renderizzato, si risolve in fase di esecuzione — nessun gateway, nessun cluster attivo necessario per verificare il cablaggio.
La dualità
| compose (Variante A) | helm (Variante B) | |
|---|---|---|
| giunzione del confine | reti compose separate | namespace separati |
| meccanismo di attraversamento | gateway di core/compose-bridge (aggrega-gw) | DNS nativo tra namespace |
ADMINER_DEFAULT_SERVER si risolve in | aggrega-gw:5432 (riscritto) | db-default.backend (qualificato dal lato del chiamante) |
| risorsa aggiuntiva | il servizio aggrega-gw + la sua configurazione | nessuna |
lo stesso aggrega.ai/namespace guida | il posizionamento nella rete compose | il posizionamento nel namespace k8s |
Un solo intento dello sviluppatore; l’attraversamento della giunzione è un meccanismo di Ops/operatore specifico del provider. Il ponte compose esiste perché una rete compose piatta non ha un DNS con ambito di namespace; Kubernetes te lo dà nativamente.
Quando i due capi vengono renderizzati con provider diversi
Entrambe le varianti sopra mantengono un solo intento dello sviluppatore e lasciano che l’attraversamento si affidi a una stringa puntatore deterministica: il provides.host del database scorre attraverso la giunzione del confine come puntatore stabile, e ogni destinazione risolve quel puntatore a modo suo — l’indirizzo di un gateway compose, oppure un nome DNS tra namespace. Il puntatore attraversa sempre, perché il compilatore instrada stringhe tra un produttore e un consumatore senza interpretarle.
Un provider può spingersi oltre e cablare un riferimento incrociato nativo tra due dei suoi artefatti assemblati propri ai due lati della giunzione — un riferimento nel vocabolario proprio di quel provider che la piattaforma di destinazione risolve al momento della distribuzione. Il provider CloudFormation lo fa per un arco uses che attraversa gli stack: lo stack produttore pubblica un Export e lo stack consumatore lo legge con Fn::ImportValue (vedi providers/cloudformation.md). Un riferimento incrociato nativo è un miglioramento all’interno dello stesso provider — funziona perché entrambi i capi parlano lo stesso vocabolario di artefatti, così un lato può pubblicare un riferimento che l’altro lato sa risolvere.
Quando un arco uses attraversa un confine tra due provider diversi — il produttore viene assemblato con un provider e il consumatore con un altro — non è possibile alcun riferimento incrociato nativo. Un riferimento coniato nel vocabolario di un provider non significa nulla per l’altro, e il compilatore non traduce tra i due: instrada stringhe, non deduce significati né riscrive il riferimento di un provider nella forma di un altro. Quindi il puntatore deterministico del produttore attraversa la giunzione invariato; dove uno dei due provider cabla riferimenti incrociati nativi propri, come fa CloudFormation, il compilatore emette un avvertimento che nomina entrambi gli endpoint, i nomi di entrambi i provider e il socket; e il build si completa su quel puntatore. Il compilatore si fida dell’autore e non si arresta: un puntatore deterministico fornito dall’autore può benissimo essere risolvibile attraverso la giunzione — un nome DNS stabile o una stringa di interpolazione dell’infrastruttura — e solo l’autore conosce la topologia di destinazione.
Questo mantiene l’attraversamento della giunzione dove deve stare. Se un puntatore tra provider diversi sia utilizzabile è una questione di distribuzione che spetta all’autore; tradurre il riferimento nativo di un provider nella forma consumatrice di un altro provider è un lavoro con opinioni proprie e specifico del provider, che vive al di fuori del nucleo neutrale.
Struttura
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)Questo esempio consuma la libreria standard. Ogni variante esegue il build con --catalog catalog-<variant>, la sua directory locale, e risolve ciò che quella directory non dichiara da hub.aggrega.ai, il registry predefinito che .aggrega-config.yaml nomina, così le entità locali si risolvono prima di quelle condivise. core/datastore/postgres, il componente di interfaccia condiviso core/devtool/adminer, le Features core/compose-bridge e core/k8s-dns-resolver con le loro FeatureRecipes compose e helm, e i provider compose/helm provengono dal catalogo standard. Ciò che resta locale è il contenuto didattico specifico dell’esempio: le recipe di Adminer per ciascuna destinazione. La recipe helm db è helm/postgres della libreria standard, il cui provides.host è un nome di servizio nudo e autosufficiente. Il consumatore lo qualifica con il namespace di destinazione dal lato del chiamante tramite la funzionalità di instradamento core/k8s-dns-resolver della libreria standard, così la recipe non codifica in modo fisso alcun namespace di confine.
In una variante compilata si incontrano due categorie di file: input scritti (tutto quanto sopra) e output generato dal compilatore sotto dist/ (il docker-compose.yaml unito, oppure i manifest helm per namespace) — di quest’ultimo non scrivi nulla. dist/ viene rigenerato da aggrega build ed è ignorato da git.