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

Un contratto, tre realizzazioni

Un database PostgreSQL e l’applicazione che lo legge, distribuiti in tre modi diversi a partire da un unico Aggregate invariato: PostgreSQL in esecuzione nel cluster, PostgreSQL come istanza cloud gestita e un server PostgreSQL che esisteva già prima che questa Release fosse distribuita.

La lezione è ciò che non cambia. L’applicazione nomina, una sola volta, le chiavi che vuole dal database e come chiamarle. Non sa mai quale delle tre ha risposto. Non lo sa nemmeno il compilatore: legge le chiavi che la Recipe selezionata ha pubblicato e instrada le stringhe.

L’unica cosa che varia

.-- 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 exists

Tre Recipes implementano lo stesso Component. Ciascuna pubblica le stesse chiavi provides — host, port, user, database, protocol e le chiavi che dicono dove uno scraper trova le metriche del database, vuote in tutte e tre. Quale viene eseguita è una singola riga nel Manifest.

File

  • aggregate.yaml — l’intento dello sviluppatore, e lo stesso documento per tutte e tre le Releases: un componente db di tipo core/datastore/postgres, un app che lo referenzia tramite uses, e le cinque chiavi che l’applicazione richiede. Nulla qui nomina un target, un cloud o una Recipe.
  • manifest-selfhosted.yaml, manifest-managed.yaml, manifest-external.yaml — le mappature Ops. Ciascuna sceglie la propria realizzazione in una riga: a quale Recipe si lega il tipo di componente PostgreSQL. Quella gestita lega anche la Feature di backup che le sue Releases associano.
  • release-selfhosted.yaml, release-managed.yaml, release-external.yaml — il dimensionamento dell’operatore in ciascuna Release: storage e versione del motore per quella nel cluster, storage, HA e un’associazione core/backup per quella gestita, e l’indirizzo del server esistente per quella referenziata.
  • release-managed-dns.yaml — ancora la Release gestita, con il nome DNS che l’operatore assegna all’istanza, così all’applicazione viene consegnato un nome che può risolvere.
  • catalog/ — il Component proprio dell’applicazione e l’unica Recipe che lo renderizza. Tutto ciò che sta dal lato del database proviene dalla libreria standard senza modifiche.

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 postgres-three-realizations

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

Terminal window
cd postgres-three-realizations

Build

Terminal window
aggrega build --release release-selfhosted.yaml --auto-pull
aggrega build --release release-managed.yaml --auto-pull
aggrega build --release release-managed-dns.yaml --auto-pull
aggrega build --release release-external.yaml --auto-pull

--auto-pull scrive il lockfile di ciascuna Release alla sua prima build; le build successive non hanno bisogno del flag. Ciascuna scrive in dist/, e una build aggiunge i propri file anziché ripulire ciò che una precedente ha lasciato. Rimuovi dist/ tra un’esecuzione e l’altra per leggere da solo l’output di una realizzazione:

Terminal window
rm -rf dist && aggrega build --release release-managed.yaml

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 Workspace non contiene ancora una cartella `postgres-three-realizations`, chiama una volta lo strumento `scaffold` con `example` impostato a `postgres-three-realizations` e senza `dir`: scrive l’esempio in una nuova cartella `postgres-three-realizations`. Poi chiama lo strumento `build` una volta per ogni Release, in quest’ordine — `release-selfhosted.yaml`, `release-managed.yaml`, `release-managed-dns.yaml` e `release-external.yaml` — ogni volta con `workspace_root` impostato a `postgres-three-realizations`, `release` impostato a quel file, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto ogni build; si trovano in `postgres-three-realizations/dist/`.

Che cosa renderizza ciascuna

In self-hosting — la Release esegue il server

helm/postgres sintetizza il database nel cluster: uno StatefulSet, un Service ClusterIP e un Service headless. provides.host è il nome semplice di quel Service, quindi l’applicazione lo raggiunge tramite il DNS interno al cluster.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db-default

Gestito — un provider cloud esegue il server

terraform/postgres-rds emette un aws_db_instance come HCL di Terraform, e il dimensionamento ha e l’associazione core/backup dell’operatore si mappano sulle impostazioni native dell’istanza: il retention_days: 14 dell’associazione diventa il backup_retention_period = 14 dell’istanza. L’applicazione viene comunque renderizzata su Kubernetes: i due lati di questa Release si incontrano nel contratto pubblicato del database, non in un target condiviso.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: ${module.db.address}

Quel valore non è un hostname, e nulla in questa build lo trasforma in uno. L’indirizzo di un’istanza RDS non esiste finché l’istanza non viene creata, quindi non c’è nulla da cercare per un compilatore che viene eseguito in anticipo. Ciò che la Recipe pubblica è un riferimento Terraform a un output del modulo proprio del database; il compilatore lo convoglia attraverso l’arco senza toccarlo, la Recipe dell’applicazione lo riceve alla lettera, e viene renderizzato nel manifest Kubernetes come i caratteri letterali mostrati sopra. Al container viene consegnato quel testo.

DB_PORT è diverso: viene renderizzato come "5432", perché la Recipe imposta la porta dell’istanza dalla Release e pubblica quello stesso valore, che è noto prima che qualcosa esista.

Il cablaggio nativo tra due componenti è qualcosa che un target fa all’interno del proprio output, quindi qui non ce n’è da fare. Le due estremità di questo arco vengono renderizzate tramite target diversi — il database in HCL di Terraform, l’applicazione in un manifest Kubernetes — e un riferimento Terraform ha significato solo all’interno di una configurazione Terraform. Attraversando quella giuntura, il valore pubblicato viene consegnato come testo, come qualsiasi altra stringa. Un consumatore renderizzato su Terraform come Recipe source:, nella stessa configurazione radice del database, riceve lo stesso riferimento come uno degli argomenti del suo modulo, e lì Terraform lo risolve.

Questa è la regola generale anziché un caso speciale per RDS: tutto ciò che dipende dallo stato di un sistema in esecuzione viene espresso come un puntatore deterministico che il runtime risolve, mai come un valore che il compilatore recupera. La parte del compilatore è consegnare il puntatore invariato. Fare in modo che si risolva dove arriva spetta all’autore della Recipe: pubblicare un indirizzo che il lato che consuma può usare, oppure dare a entrambi i componenti Recipes che renderizzano nello stesso target.

Dare all’istanza un nome che l’applicazione può risolvere

terraform/postgres-rds accetta la prima di queste come opzione impostata dall’operatore. release-managed-dns.yaml è la Release gestita con un’aggiunta, il nome DNS che l’operatore assegna all’istanza:

db:
infra:
overrides:
host: db.internal.example.net

La Recipe pubblica quel nome come host al posto del riferimento Terraform, e l’applicazione lo riceve:

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db.internal.example.net
variabilerelease-managed.yamlrelease-managed-dns.yaml
DB_HOST${module.db.address}db.internal.example.net
DB_PORT54325432

È l’unica riga dell’output che cambia. La Recipe non emette alcun record DNS né alcun alias per il nome, e la build non lo risolve: il compilatore lo convoglia esattamente come ha convogliato il riferimento. Far puntare db.internal.example.net all’istanza una volta che esiste — un record nella zona DNS propria dell’operatore, diretto all’indirizzo dell’istanza — spetta all’operatore, al di fuori della Release. La chiave è quella che la realizzazione referenziata più sotto legge per lo stesso indirizzo; questa Recipe la accetta come nome semplice o letterale IP, e un valore che contiene uno schema, un percorso, un utente o una porta arresta la build, poiché la porta è l’infra.port della Release e un consumatore compone la propria connessione a partire dai due.

Anche un consumatore renderizzato nella stessa configurazione Terraform del database riceve il nome, e con esso perde l’ordinamento che il riferimento gli dava: Terraform agisce su un modulo dopo un modulo che esso referenzia, e un nome non referenzia nulla. Collocare quel consumatore in un confine proprio che condivide la directory: del database e porta un syncWave: successivo ripristina l’ordine.

Esterno — nessuno in questa Release esegue il server

helm/postgres-external non effettua alcun provisioning. Il suo intero output è un Service che mappa un nome interno al cluster sull’indirizzo fornito dalla Release:

dist/stack/helm/db-service.yaml
[… 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: 5432

Nessuno StatefulSet, nessun volume, nessun container — il ciclo di vita del server sta interamente al di fuori di questa Release. L’indirizzo proviene dalla Release:

db:
infra:
overrides:
host: postgres.data.example.net
dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: postgres.data.example.net

Referenziare un server non equivale a prenderne il controllo. Questa Recipe raggiunge un server che resta di proprietà esterna; nulla qui lo porta sotto la gestione della Release, e nulla qui lo modificherà.

Se si omette l’indirizzo, la build si ferma e lo dice. Un server referenziato ha un indirizzo oppure non ha nulla, quindi la Recipe rifiuta anziché emettere un Service che fa da alias a un nome vuoto:

[… 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 of
PostgreSQL, which addresses a server it does not provision, but no address was
supplied: set infra.overrides.host on this component in the Release to the DNS
name or IP literal the existing server answers on

Il confronto che è il nocciolo

L’ambiente renderizzato dell’applicazione, tutti e tre affiancati:

variabilein self-hostinggestitoesterno
POOL_SIZE101010
DB_HOSTdb-default${module.db.address}postgres.data.example.net
DB_NAMEappdbappdbappdb
DB_PORT543254325432
DB_PROTOCOLpostgrespostgrespostgres
DB_USERappuserappuserappuser

Stesse variabili, stesso ordine, ogni volta. Cambia solo la stringa dietro una di esse. La Recipe dell’applicazione non nomina nessuna delle variabili DB_: emette qualunque cosa l’arco uses abbia risolto, ed è per questo che una sola Recipe viene renderizzata invariata contro tutti e tre i database.

E il compilatore non sa che cosa sia nessuna di quelle stringhe. db-default è il nome di un Service Kubernetes, ${module.db.address} è un riferimento Terraform, postgres.data.example.net è un nome DNS — per il compilatore sono tre stringhe che una Recipe ha pubblicato sotto la chiave host e che un arco ha chiesto di consegnare come DB_HOST. Non verifica che nessuna di esse sia instradabile, né che una porta sia un numero, né che un componente chiamato db sia un database. Ha abbinato l’arco in base all’etichetta che il Component porta, ha letto la chiave che il contratto dichiara e ha spostato il testo.

Dov’è la giuntura

Ciascuna delle tre Releases è stata scelta da una mappatura Ops, e il documento dello sviluppatore non è stato toccato da quella scelta. È questa la separazione che l’intero esempio esiste per rendere concreta:

  • lo sviluppatore dice di cosa l’applicazione ha bisogno da un database;
  • Ops dice di che cosa è fatto un database — una Recipe per realizzazione;
  • l’operatore dice quale riceve questa Release, e la dimensiona.

Aggiungi domani una quarta realizzazione — un cloud diverso, un operatore diverso, un servizio Compose per il lavoro locale — e si tratta di una Recipe in più che pubblica le stesse chiavi, più una riga di Manifest. L’aggregate.yaml in questa directory non cambia.