Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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-bridge della libreria standard genera un gateway aggrega-gw per 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 instradamento core/k8s-dns-resolver del 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/postgres

L’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:

Terminal window
aggrega scaffold --example cross-boundary-networking

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd cross-boundary-networking

Build

Ogni variante è una Release, compilata rispetto alla propria directory di catalogo, una Release per esecuzione:

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

Con 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

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

Un 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 valuesMapping scrive la configurazione stream di nginx del gateway, consegnata come config compose montata (configs: di primo livello, montata in /etc/nginx/nginx.conf); porta un resolver e un proxy_pass con 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 valuesMapping nomina entrambi i capi sotto x-aggrega-networks-of del gateway, che il provider compose risolve, così il gateway si unisce a entrambe le reti collegate dal ponte;
  • il suo injectMapping, eseguito per adminer, riscrive ADMINER_DEFAULT_SERVER del consumatore in aggrega-gw:5432. La riscrittura sostituisce ciò che aveva consegnato la connessione databases propria 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

Terminal window
cd dist/bridge/compose
docker compose up

Apri http://localhost:8080 (server precompilato con aggrega-gw:5432) e accedi:

CampoValore
SistemaPostgreSQL
Serveraggrega-gw:5432 (precompilato)
Nome utenteappuser
Passwordapppass
Databaseappdb

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

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

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

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

dist/frontend/helm/adminer-deployment.yaml
- 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 confinereti compose separatenamespace separati
meccanismo di attraversamentogateway di core/compose-bridge (aggrega-gw)DNS nativo tra namespace
ADMINER_DEFAULT_SERVER si risolve inaggrega-gw:5432 (riscritto)db-default.backend (qualificato dal lato del chiamante)
risorsa aggiuntivail servizio aggrega-gw + la sua configurazionenessuna
lo stesso aggrega.ai/namespace guidail posizionamento nella rete composeil 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.