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

MariaDB + Adminer — un esempio eseguibile a doppio target

Questo esempio compila uno stack piccolo e reale — un database MariaDB con davanti un’interfaccia web Adminer — a partire da un unico Aggregate scritto dallo sviluppatore per due piattaforme:

  • Docker Compose per lo sviluppo locale, e
  • Kubernetes per un cluster locale (kind / minikube / k3d), renderizzato in tre modi.

Lo stesso Aggregate guida entrambe. Cambiano solo la Release, il suo Manifest e il livello di Recipe caricato in fase di build. Ogni file qui presente si compila con la CLI aggrega distribuita, e l’output renderizzato funziona: avvia lo stack, apri Adminer in un browser ed effettua l’accesso al database in esecuzione.

aggregate.yaml

scritto una sola volta

Su un laptop

release-compose.yaml
manifest-compose.yaml
aggrega build
docker-compose.yaml

Su un cluster Kubernetes

release-helm-synth.yaml
manifest-helm-synth.yaml
aggrega build

Manifest di Kubernetes

Ogni piattaforma è compilata dalla propria Release e dal proprio Manifest. L’Aggregate, che descrive la tua applicazione, resta lo stesso.

Che cosa dimostra

  • Un’unica superficie di authoring, molti target. Un unico aggregate.yaml è la fonte di verità su che cosa è lo stack. Ogni target è un sottile livello di catalogo che dice come realizzarlo.
  • Lo String Pipe. Adminer dichiara un uso databases di MariaDB; il provides.host della Recipe del database viene convogliato nella variabile d’ambiente ADMINER_DEFAULT_SERVER di Adminer. Il compilatore instrada la stringa senza interpretarla — così il build compose cabla un nome di servizio compose e il build Kubernetes cabla un nome DNS di Service, a partire dallo stesso arco.
  • Sintesi del Workload. Le Recipes per compose e per Kubernetes autonomo dichiarano un Workload agnostico rispetto alle capacità; il provider sintetizza un servizio docker-compose.yaml, oppure gli oggetti Kubernetes che il form del Workload richiede — un Deployment e un Service per l’interfaccia web stateless, e per il database form: stateful uno StatefulSet il cui template di volume claim per replica contiene la directory dei dati, accanto al Service headless che lo governa e al Service ClusterIP che i consumatori contattano.
  • Il sottosistema delle credenziali. Le password del database vengono associate nel pilastro features: del componente — ciascuna una Feature etichettata feature.aggrega.ai/kind: secret, tenuta separata dai values dell’applicazione. Il featuresSchema del Component dichiara due tipi di slot, e l’esempio li mette alla prova entrambi: uno slot a scatola nera la cui FeatureRecipe consegna il valore internamente, e uno slot trasparente il cui valore lo sviluppatore consegna esplicitamente con un blocco inject: sull’associazione.
  • Sorgenti di chart remote. Il target Kubernetes gestito prende come sorgente il chart MariaDB upstream di Bitnami tramite riferimento OCI. aggrega pull fissa il chart in un lockfile e lo scarica in una cache indirizzata per contenuto; aggrega build renderizza da quella cache, così il momento del lock e il momento del build risolvono lo stesso chart. La versione del chart proviene da infra.source_version dell’operatore quando la Release ne fissa una, e altrimenti da un valore scritto dallo sviluppatore (un valore che confluisce nella risoluzione della sorgente). I lockfile per release fissano le identità e i digest delle entità: dopo che le entità del catalogo vengono rinominate o il loro contenuto cambia, aggiorna un lockfile locale obsoleto con aggrega pull --release release-<variant>.yaml. Ogni variante di release si risolve rispetto alla propria directory di catalogo sorella, che .aggrega-config.yaml nomina per essa sotto workspace.releases, quindi non serve alcun --catalog in un terminale, in un editor o tramite un assistente.
  • Provenienza come annotazioni. Ogni oggetto Kubernetes renderizzato porta un’annotazione aggrega.ai/recipe-uri che registra la Recipe che lo ha prodotto — un’annotazione, non un’etichetta, perché il valore URI contiene caratteri che il valore di un’etichetta Kubernetes non può contenere.
  • Composizione di chart (rispetto alla sintesi). Lo stesso Aggregate può produrre un chart Helm ridistribuibile invece di manifest renderizzati. Il provider helm-chart compone un chart ombrello: il subchart locale di ogni componente viene copiato così com’è (con i suoi {{ }} di Helm lasciati intatti), e il values.yaml del chart ombrello instrada i valori mappati di ogni componente — compreso l’host del database convogliato — sotto l’alias di quel componente.
  • Selezione del Provider per tipo di componente. La Recipe che renderizza ogni componente è quella su cui il Manifest del target mappa il tipo del componente, presa da qualunque livello di catalogo il build carichi.

Authoring e consumo — un workspace misto

Questo esempio lavora contemporaneamente su entrambe le estremità del catalogo: scrive alcune entità in locale e ne consuma altre dalla libreria standard di Aggrega. Il Component del database MariaDB, le sue Features di credenziale e le Recipes per ogni target sono costruiti da zero nelle directory locali catalog-*/ — un unico Aggregate renderizza quel database scritto in locale su quattro target. L’interfaccia web Adminer, invece, viene consumata: il componente web fa riferimento direttamente al Component distribuito core/devtool/adminer, e ogni target scrive solo una Recipe locale che lo implementa. Lo stesso workspace mostra quindi l’authoring di entità sul lato del database accanto al consumo del catalogo sul lato dell’interfaccia. Le entità che costruisci qui sono dello stesso tipo di quelle distribuite nella libreria standard: un Component di database, Features di credenziale, Recipes di provider.

L’esempio catalog-only si colloca all’estremità del puro consumo dello stesso percorso didattico: assembla proprio questo stack — un database MariaDB con un’interfaccia Adminer — facendo riferimento a entità della libreria standard, senza scriverne alcuna propria. Leggi il lato database di questo esempio per imparare come si costruiscono le entità del catalogo; leggi gli esempi di consumo per imparare come si usa un intero stack dal catalogo distribuito.

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 mariadb-adminer

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

Terminal window
cd mariadb-adminer

Build

Ogni target è una Release, compilata una per esecuzione; il pull scrive il lockfile che la build legge. Prima Docker Compose — la sezione di ciascun target più sotto fornisce i propri comandi:

Terminal window
aggrega pull --release release-compose.yaml
aggrega build --release release-compose.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 del workspace non contiene ancora una cartella `mariadb-adminer`, chiama una volta lo strumento `scaffold` con `example` impostato su `mariadb-adminer` e senza `dir`: scrive l’esempio in una nuova cartella `mariadb-adminer`. Poi chiama lo strumento `build` con `workspace_root` impostato su `mariadb-adminer`, `release` impostato su `release-compose.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `mariadb-adminer/dist/`.

Struttura

mariadb-adminer/
├── aggregate.yaml # Developer intent — shared by every target
│
├── manifest-compose.yaml # Ops mapping, Docker Compose target
├── release-compose.yaml # Operator release, Docker Compose target
├── catalog-compose/ # Recipe layer: compose
│
├── manifest-helm-synth.yaml # Ops mapping, self-contained Kubernetes target
├── release-helm-synth.yaml # Operator release, self-contained Kubernetes target
├── catalog-helm-synth/ # Recipe layer: helm (Workload synthesis)
│
├── manifest-helm-bitnami.yaml # Ops mapping, managed-chart Kubernetes target
├── release-helm-bitnami.yaml # Operator release, managed-chart Kubernetes target
├── catalog-helm-bitnami/ # Recipe layer: helm (upstream Bitnami chart)
│
├── manifest-helm-chart.yaml # Ops mapping, composed-Helm-chart target
├── release-helm-chart.yaml # Operator release, composed-Helm-chart target
└── catalog-helm-chart/ # Recipe layer: helm-chart (umbrella composition)

Ogni directory catalog-* contiene le definizioni del Component MariaDB e della Feature scritte in locale, più le Recipes per quel singolo target. Il Component Adminer non è tra queste — si risolve dalla libreria standard. Un build carica un livello catalog-* sopra quella libreria standard, e il Manifest del target mappa ogni tipo di componente su una Recipe al suo interno.

La Release, il suo aggregate: e il suo manifest: sono fratelli in questa directory; la directory di catalogo su cui viene eseguito il build di ciascuna Release è indicata per essa in .aggrega-config.yaml.

L’Aggregate condiviso

spec:
components:
db:
type: core/datastore/mariadb
values:
database: appdb
user: appuser
charset: utf8mb4
collation: utf8mb4_general_ci
chart_version: "25.0.8" # the managed-chart target's chart, absent an operator pin
features:
root_password: # black-box slot: the FeatureRecipe delivers it
type: core/secret-value
values: { key: MARIADB_ROOT_PASSWORD, origin: dev-root-pw-change-me }
user_password: # transparent slot: the developer delivers it
type: core/secret-provided
values: { origin: dev-app-pw-change-me }
inject:
env: [{ in: MARIADB_PASSWORD, from: value }]
web:
type: core/devtool/adminer
values:
design: pepa-linha-dark
uses:
databases:
db:
target: db
inject:
env:
- in: ADMINER_DEFAULT_SERVER
from: host

web dichiara un uso databases di db. Il blocco inject lega il provides.host della Recipe del database alla variabile d’ambiente ADMINER_DEFAULT_SERVER sul container di Adminer. Nulla nell’Aggregate nomina un provider; quella scelta risiede interamente nel livello di catalogo che il build carica.

Una nota sulle credenziali

L’immagine di MariaDB ha bisogno di una password di root per avviarsi, e l’utente dell’applicazione ha bisogno della propria. Entrambe sono associate nel pilastro features: del componente del database — tenute separate dai values dell’applicazione — come Features etichettate feature.aggrega.ai/kind: secret. Il featuresSchema del Component core/datastore/mariadb dichiara uno slot per ciascuna, e l’esempio mette alla prova entrambi i modelli di consegna:

  • root_password è uno slot a scatola nera (inject: []): la FeatureRecipe consegna il valore nel canale del componente. Lo sviluppatore non stabilisce — e non può stabilire — come.
  • user_password è uno slot trasparente (inject: [env, file]): la credenziale espone il proprio valore, e lo sviluppatore lo mappa su una variabile d’ambiente con il blocco inject: sull’associazione.

Qui i valori sono letterali inline, così lo stack si avvia con un solo comando — adatto allo sviluppo locale e alle demo. Per ambienti condivisi o di produzione, le stesse associazioni risolvono i propri valori da uno store di segreti: il catalogo del target carica una FeatureRecipe che li recupera, e l’Aggregate non cambia.


Target 1 — Docker Compose

Prima il pull, poi il build — il pull scrive release-compose.lock, che il build legge:

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

Output: dist/app/compose/docker-compose.yaml — due servizi su un’unica rete. db esegue mariadb:11.4 con il database, l’utente, il charset e le password iniettate; web esegue adminer:4, pubblica la porta 8080, dipende da db e porta ADMINER_DEFAULT_SERVER: db (il nome del servizio compose che la Recipe del database ha emesso).

Eseguirlo:

Terminal window
docker compose -f dist/app/compose/docker-compose.yaml up -d

Apri http://localhost:8080 ed effettua l’accesso:

CampoValore
SistemaMySQL / MariaDB
Serverdb (già compilato)
Nome utenteappuser
Passworddev-app-pw-change-me
Databaseappdb

(oppure root / dev-root-pw-change-me). Per smontarlo, usa docker compose -f dist/app/compose/docker-compose.yaml down -v.


Target 2 — Kubernetes (autonomo)

Questo target renderizza semplici manifest Kubernetes direttamente dal Workload, senza alcun chart esterno — un unico build offline.

Il Workload del database dichiara form: stateful, quindi sintetizza uno StatefulSet la cui directory dei dati è un template di volume claim per replica anziché un Deployment che condivide un’unica claim. Due elementi accompagnano quella forma: il volume è dichiarato come persistentTemplate, e un Service headless fornisce l’identità DNS stabile per pod che lo StatefulSet indica come proprio servizio di governo. Adminer non mantiene alcuno stato, quindi il suo Workload lascia form al valore predefinito e resta un Deployment — la persistenza è una proprietà del Workload, non un componente diverso.

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

Output in dist/app/helm/:

db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysql
db-default-service.yaml # ClusterIP Service "db-default" on 3306
db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceName
web-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-default
web-default-service.yaml # NodePort Service "web-default" on 8080

Nota ADMINER_DEFAULT_SERVER: db-default — per Kubernetes la Recipe del database emette il nome DNS del Service interno al cluster, quindi lo stesso arco dell’Aggregate si risolve in un indirizzo instradabile su questo target.

Applicarlo e aprirlo:

Terminal window
kubectl apply -f dist/app/helm/
kubectl rollout status statefulset/db
kubectl port-forward svc/web-default 8080:8080

Apri http://localhost:8080 ed effettua l’accesso con Server db-default, nome utente appuser, password dev-app-pw-change-me e database appdb. Per rimuoverlo, usa kubectl delete -f dist/app/helm/.


Target 3 — Kubernetes (chart Bitnami gestito)

Il terzo livello implementa lo stesso Component core/datastore/mariadb sul chart Helm MariaDB di Bitnami upstream invece di sintetizzare manifest. La Recipe prende come sorgente il chart tramite riferimento OCI e mappa i valori del Component sullo schema dei valori del chart:

spec:
capability: helm
implements: core/datastore/mariadb
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` .values.chart_version }}" # operator pin, else the value
valuesMapping: |
auth:
database: "{{ .values.database }}"
rootPassword: "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}"
username: "{{ .values.user }}"
password: "{{ .context.inject.env.MARIADB_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}"
primary:
persistence:
size: "{{ .infra.storage.size }}"
# … resources, read replicas, metrics mapped from infra …

Il source.version della Recipe preferisce infra.source_version dell’operatore e ripiega su .values.chart_version, scritto dallo sviluppatore. Il fissaggio della versione del chart è una questione di infrastruttura, quindi il fissaggio dell’operatore prevale ovunque una Release ne imposti uno; questa Release di proposito non ne imposta alcuno, quindi la chiave .values è la versione che viene effettivamente risolta — ed è proprio lo scopo di questo target, perché un valore dello sviluppatore che raggiunge la risoluzione della sorgente è osservabile nell’output renderizzato solo finché il fissaggio operativo è assente. Fissa source_version sul componente db in release-helm-bitnami.yaml e l’etichetta helm.sh/chart renderizzata segue invece quella versione.

optional legge il fissaggio per nome anziché come percorso puntato, ed è questo che permette a un fissaggio assente di ricadere sul valore dello sviluppatore anziché risolversi in una versione vuota — vedi optional per la semantica del controllo di presenza.

Il build di questo target è un flusso in due passaggi: aggrega pull risolve il chart, lo fissa in release-helm-bitnami.lock e lo scarica nella cache di build indirizzata per contenuto (l’unico passaggio online); aggrega build poi renderizza dalla cache, così il momento del lock e quello del build risolvono lo stesso identico chart. Le credenziali iniettate confluiscono nei valori auth del chart, e il chart genera il Secret Kubernetes che il database legge. Adminer è renderizzato dalla stessa Recipe sintetizzata del Target 2 e si connette al Service primario del chart (db-mariadb). I due target autonomi qui sopra sono il modo senza dipendenze per eseguire lo stack da un capo all’altro.


Target 4 — Kubernetes (chart Helm composto)

Il quarto livello implementa gli stessi componenti sul provider helm-chart, che compone un chart Helm ombrello ridistribuibile anziché renderizzare manifest (Target 2) o renderizzare un chart upstream (Target 3). Ogni Recipe prende come sorgente un piccolo chart locale:

spec:
capability: helm-chart
implements: core/datastore/mariadb
source: ./charts/mariadb # copied as the sub-chart, bar its own name
valuesMapping: |
{ "database": "{{ .values.database }}",
"rootPassword": "{{ .context.inject.env.MARIADB_ROOT_PASSWORD | replace "\\" "\\\\" | replace "\"" "\\\"" }}",
"serviceName": "{{ .context.instance_id }}-mariadb" }

Compilarlo:

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

Output in dist/app/helm-chart/:

Chart.yaml # umbrella; lists db and web as sub-chart dependencies
values.yaml # alias-keyed: db.* and web.* value blocks
charts/
├── db/ # the local ./charts/mariadb; its Chart.yaml name is `db`
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── pvc.yaml
│ └── netpol.yaml # injected artifact (see below)
└── web/ # the local ./charts/adminer; its Chart.yaml name is `web`
[… omitted: web's own Chart.yaml, values.yaml, and a templates/ holding deployment.yaml and service.yaml — Adminer keeps no state, so it has no pvc.yaml, and the injected netpol.yaml is db's alone]

Installarlo (i subchart sono inclusi in charts/, quindi non serve prima un helm dependency build):

Terminal window
helm install mariadb-adminer dist/app/helm-chart/

Il values.yaml del chart ombrello contiene già i valori risolti di ogni componente, così il database si avvia con le sue credenziali e Adminer è collegato al Service di MariaDB — la stessa connessione che esprimono gli altri target, ora fornita come un chart che puoi installare o includere nel tuo progetto.

Si applicano due regimi di delimitatori distinti, che non si sovrappongono:

  • I subchart con sorgente vengono copiati, tranne il loro nome. I file in ./charts/mariadb e ./charts/adminer vengono inclusi nel chart ombrello senza modifiche — le loro direttive Helm {{ }} non vengono toccate dal compilatore e si risolvono al momento di helm install. Lì il compito del compositore è solo l’assemblaggio, non il templating. L’unico campo che imposta è il name di ogni Chart.yaml collocato, che diventa l’identità dell’istanza del componente (db, web), così due componenti che includono chart che dichiarano lo stesso nome restano distinguibili; vedi providers/helm-chart.md.
  • Gli artefatti $import: usano due delimitatori. Una Recipe può iniettare file di template aggiuntivi tramite artifacts: { name: { $import: ... } }. Quei file — e solo quelli — vengono pre-renderizzati dal compilatore con i delimitatori [[ ]] prima di essere collocati, mentre il loro {{ }} viene preservato per Helm. L’artefatto netpol.yaml — con chiave netpol.yaml e importato da ./extras/mariadb-netpol.yaml, poiché la chiave nomina il file emesso e l’import ne seleziona il contenuto — mostra la combinazione: [[ .context.instance_id ]] (riempito al build) e {{ .Release.Namespace }} (lasciato all’installazione).

Lo String Pipe si esprime in termini di chart: l’uso databases di MariaDB da parte di Adminer risolve il provides.host della Recipe del database nel values.yaml del chart ombrello sotto l’alias web (adminerDefaultServer: db-mariadb), che il subchart di Adminer legge come {{ .Values.adminerDefaultServer }}. Lo stesso valore nomina il Service del subchart di MariaDB, così il collegamento si risolve in modo coerente all’installazione. L’output è un chart da passare a helm install o da includere — non un insieme di manifest applicati.


Come viene selezionato un target

La selezione della Recipe avviene per tipo di componente: il Manifest di ogni target mappa ogni tipo a una Recipe nel livello di catalogo che la sua Release carica, quindi manifest-compose.yaml lega core/datastore/mariadb alla Recipe compose, mentre manifest-helm-synth.yaml lo lega a quella Kubernetes. Un tipo che il Manifest non mappa interrompe il build, indicando le Recipes che lo implementano, anche dove il livello caricato ne contiene una sola. Il provider che renderizza un nodo è lo spec.capability della Recipe che è stata legata, qualunque essa sia. Cambiare target significa cambiare la Release, con il suo Manifest e la directory di catalogo che .aggrega-config.yaml indica per essa — l’Aggregate non cambia mai.