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.yamlscritto una sola volta
Su un laptop
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlSu un cluster Kubernetes
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildManifest 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
databasesdi MariaDB; ilprovides.hostdella Recipe del database viene convogliato nella variabile d’ambienteADMINER_DEFAULT_SERVERdi 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
Workloadagnostico rispetto alle capacità; il provider sintetizza un serviziodocker-compose.yaml, oppure gli oggetti Kubernetes che ilformdel Workload richiede — unDeploymente unServiceper l’interfaccia web stateless, e per il databaseform: statefulunoStatefulSetil cui template di volume claim per replica contiene la directory dei dati, accanto alServiceheadless che lo governa e alServiceClusterIPche i consumatori contattano. - Il sottosistema delle credenziali. Le password del database vengono associate nel pilastro
features:del componente — ciascuna unaFeatureetichettatafeature.aggrega.ai/kind: secret, tenuta separata daivaluesdell’applicazione. IlfeaturesSchemadel 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 bloccoinject:sull’associazione. - Sorgenti di chart remote. Il target Kubernetes gestito prende come sorgente il chart MariaDB upstream di Bitnami tramite riferimento OCI.
aggrega pullfissa il chart in un lockfile e lo scarica in una cache indirizzata per contenuto;aggrega buildrenderizza da quella cache, così il momento del lock e il momento del build risolvono lo stesso chart. La versione del chart proviene dainfra.source_versiondell’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 conaggrega pull --release release-<variant>.yaml. Ogni variante di release si risolve rispetto alla propria directory di catalogo sorella, che.aggrega-config.yamlnomina per essa sottoworkspace.releases, quindi non serve alcun--catalogin un terminale, in un editor o tramite un assistente. - Provenienza come annotazioni. Ogni oggetto Kubernetes renderizzato porta un’annotazione
aggrega.ai/recipe-uriche 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-chartcompone un chart ombrello: il subchart locale di ogni componente viene copiato così com’è (con i suoi{{ }}di Helm lasciati intatti), e ilvalues.yamldel 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:
aggrega scaffold --example mariadb-adminerPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd mariadb-adminerBuild
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:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlCon 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: hostweb 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 bloccoinject: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:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlOutput: 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:
docker compose -f dist/app/compose/docker-compose.yaml up -dApri http://localhost:8080 ed effettua l’accesso:
| Campo | Valore |
|---|---|
| Sistema | MySQL / MariaDB |
| Server | db (già compilato) |
| Nome utente | appuser |
| Password | dev-app-pw-change-me |
| Database | appdb |
(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.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlOutput in dist/app/helm/:
db-statefulset.yaml # mariadb:11.6, env + mount, volumeClaimTemplate for /var/lib/mysqldb-default-service.yaml # ClusterIP Service "db-default" on 3306db-headless-service.yaml # Headless Service "db-headless" — the StatefulSet's serviceNameweb-deployment.yaml # adminer:4, ADMINER_DEFAULT_SERVER: db-defaultweb-default-service.yaml # NodePort Service "web-default" on 8080Nota 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:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080Apri 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:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamlOutput in dist/app/helm-chart/:
Chart.yaml # umbrella; lists db and web as sub-chart dependenciesvalues.yaml # alias-keyed: db.* and web.* value blockscharts/├── 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):
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/mariadbe./charts/adminervengono inclusi nel chart ombrello senza modifiche — le loro direttive Helm{{ }}non vengono toccate dal compilatore e si risolvono al momento dihelm install. Lì il compito del compositore è solo l’assemblaggio, non il templating. L’unico campo che imposta è ilnamedi ogniChart.yamlcollocato, che diventa l’identità dell’istanza del componente (db,web), così due componenti che includono chart che dichiarano lo stesso nome restano distinguibili; vediproviders/helm-chart.md. - Gli artefatti
$import:usano due delimitatori. Una Recipe può iniettare file di template aggiuntivi tramiteartifacts: { 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’artefattonetpol.yaml— con chiavenetpol.yamle 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.