MariaDB + Adminer — ein ausführbares Beispiel mit zwei Zielen
Dieses Beispiel kompiliert einen kleinen, realen Stack — eine MariaDB-Datenbank mit einer vorgeschalteten Adminer-Web-UI — aus einem einzigen vom Entwickler verfassten Aggregate für zwei Plattformen:
- Docker Compose für die lokale Entwicklung und
- Kubernetes für einen lokalen Cluster (kind / minikube / k3d), auf drei Arten gerendert.
Dasselbe Aggregate steuert beide. Nur das Release, sein Manifest und die zur Build-Zeit geladene Recipe-Schicht ändern sich. Jede Datei hier kompiliert mit der ausgelieferten CLI aggrega, und die gerenderte Ausgabe läuft: Starten Sie den Stack, öffnen Sie Adminer in einem Browser und melden Sie sich bei der laufenden Datenbank an.
aggregate.yamleinmal geschrieben
Auf einem Laptop
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlAuf einem Kubernetes-Cluster
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildKubernetes-Manifeste
Jede Plattform wird aus ihrem eigenen Release und Manifest gebaut. Das Aggregate, das Ihre Anwendung beschreibt, bleibt dasselbe.
Was es zeigt
- Eine Authoring-Oberfläche, viele Ziele. Ein einziges
aggregate.yamlist die maßgebliche Quelle dafür, was der Stack ist. Jedes Ziel ist eine dünne Katalogschicht, die sagt, wie er zu realisieren ist. - Die String Pipe. Adminer deklariert eine Nutzung
databasesvon MariaDB; der Wertprovides.hostdes Datenbank-Recipe wird in die UmgebungsvariableADMINER_DEFAULT_SERVERvon Adminer durchgereicht. Der Compiler leitet den String weiter, ohne ihn zu interpretieren — so verdrahtet der Compose-Build einen Compose-Servicenamen und der Kubernetes-Build einen Service-DNS-Namen, aus derselben Kante. - Workload-Synthese. Die Recipes für Compose und für das in sich geschlossene Kubernetes deklarieren eine gegenüber Fähigkeiten agnostische
Workload; der Provider synthetisiert einen Service indocker-compose.yamloder die Kubernetes-Objekte, die dieformder Workload verlangt — einDeploymentund einenServicefür die zustandslose Web-UI und für die Datenbank mitform: statefuleinStatefulSet, dessen Volume-Claim-Vorlage pro Replica das Datenverzeichnis trägt, neben dem headlessService, der es steuert, und demServicevom TypClusterIP, den Konsumenten ansprechen. - Das Zugangsdaten-Subsystem. Datenbankpasswörter werden in der Säule
features:der Komponente angebunden — jedes einFeaturemit dem Labelfeature.aggrega.ai/kind: secret, getrennt von denvaluesder Anwendung. DasfeaturesSchemader Component deklariert zwei Slot-Typen, und das Beispiel nutzt beide: einen Blackbox-Slot, dessen FeatureRecipe den Wert intern liefert, und einen transparenten Slot, dessen Wert der Entwickler explizit mit einem Blockinject:an der Anbindung liefert. - Entfernte Chart-Quellen. Das verwaltete Kubernetes-Ziel bezieht das Upstream-MariaDB-Chart von Bitnami per OCI-Referenz.
aggrega pullfixiert das Chart in einem Lockfile und ruft es in einen inhaltsadressierten Cache ab;aggrega buildrendert aus diesem Cache, sodass Lock-Zeit und Build-Zeit dasselbe Chart auflösen. Die Chart-Version stammt ausinfra.source_versiondes Betreibers, wo das Release eine festlegt, und andernfalls aus einem vom Entwickler verfassten Wert (einem Wert, der in die Quellauflösung einfließt). Die Lockfiles pro Release fixieren Entitätsidentitäten und Digests: Nachdem Katalogentitäten umbenannt wurden oder sich ihr Inhalt geändert hat, aktualisieren Sie ein veraltetes lokales Lockfile mitaggrega pull --release release-<variant>.yaml. Jede Release-Variante wird gegen ihr eigenes benachbartes Katalogverzeichnis aufgelöst, das.aggrega-config.yamlfür sie unterworkspace.releasesnennt, sodass weder im Terminal noch in einem Editor noch über einen Assistenten ein--catalognötig ist. - Herkunft als Annotationen. Jedes gerenderte Kubernetes-Objekt trägt eine Annotation
aggrega.ai/recipe-uri, die das Recipe verzeichnet, das es erzeugt hat — eine Annotation, kein Label, weil der URI-Wert Zeichen enthält, die ein Kubernetes-Labelwert nicht enthalten darf. - Chart-Komposition (statt Synthese). Dasselbe Aggregate kann statt gerenderter Manifeste ein weiterverteilbares Helm-Chart erzeugen. Der Provider
helm-chartsetzt ein Umbrella-Chart zusammen: Das lokale Subchart jeder Komponente wird unverändert hineinkopiert (seine Helm-Ausdrücke{{ }}bleiben unangetastet), und dievalues.yamldes Umbrella-Charts leitet die zugeordneten Werte jeder Komponente — einschließlich des durchgereichten Datenbank-Hosts — unter den Alias dieser Komponente. - Provider-Auswahl nach Komponententyp. Das Recipe, das jede Komponente rendert, ist dasjenige, auf das das Manifest des Ziels den Typ der Komponente abbildet, entnommen aus der Katalogschicht, die der Build lädt.
Authoring und Nutzung — ein gemischter Workspace
Dieses Beispiel bearbeitet beide Enden des Katalogs zugleich: Es verfasst einige Entitäten lokal und nutzt andere aus der Standardbibliothek von Aggrega. Die MariaDB-Datenbank-Component, ihre Zugangsdaten-Features und die Recipes pro Ziel werden in den lokalen Verzeichnissen catalog-*/ von Grund auf erstellt — ein einziges Aggregate rendert diese lokal verfasste Datenbank über vier Ziele hinweg. Die Adminer-Web-UI wird dagegen genutzt: Die Komponente web referenziert direkt die ausgelieferte Component core/devtool/adminer, und jedes Ziel verfasst nur ein lokales Recipe, das sie implementiert. Derselbe Workspace zeigt daher das Verfassen von Entitäten auf der Datenbankseite neben der Nutzung des Katalogs auf der UI-Seite. Die Entitäten, die Sie hier erstellen, sind vom selben Typ wie die in der Standardbibliothek ausgelieferten: eine Datenbank-Component, Zugangsdaten-Features, Provider-Recipes.
Das Beispiel catalog-only steht am Ende reiner Nutzung desselben Lehrplans: Es stellt genau diesen Stack zusammen — eine MariaDB-Datenbank mit einer Adminer-UI —, indem es Entitäten der Standardbibliothek referenziert, ohne eigene zu verfassen. Lesen Sie die Datenbankseite dieses Beispiels, um zu lernen, wie Katalogentitäten erstellt werden; lesen Sie die Nutzungsbeispiele, um zu lernen, wie ein ganzer Stack aus dem ausgelieferten Katalog verwendet wird.
Das Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example mariadb-adminerDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd mariadb-adminerBuild
Jedes Ziel ist ein Release, eines pro Lauf gebaut; der Pull schreibt die Lockfile, die der Build liest. Zuerst Docker Compose — der Abschnitt jedes Ziels weiter unten nennt seine eigenen Befehle:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlMit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `mariadb-adminer` enthält, rufen Sie das Tool `scaffold` einmal mit `example` auf `mariadb-adminer` gesetzt und ohne `dir` auf: Es schreibt das Beispiel in einen neuen Ordner `mariadb-adminer`. Rufen Sie anschließend das Tool `build` mit `workspace_root` auf `mariadb-adminer`, `release` auf `release-compose.yaml`, `auto_pull` auf true und `write` auf true gesetzt auf. Nennen Sie mir, welche Dateien der Build geschrieben hat; sie liegen unter `mariadb-adminer/dist/`.Aufbau
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)Jedes Verzeichnis catalog-* enthält die lokal verfassten Definitionen von MariaDB-Component und Feature sowie die Recipes für genau dieses Ziel. Die Adminer-Component ist nicht darunter — sie wird aus der Standardbibliothek aufgelöst. Ein Build lädt eine Schicht catalog-* über diese Standardbibliothek, und das Manifest des Ziels bildet jeden Komponententyp auf ein Recipe darin ab.
Das Release, sein aggregate: und sein manifest: liegen nebeneinander in diesem Verzeichnis; das Katalogverzeichnis, gegen das jedes Release gebaut wird, ist in .aggrega-config.yaml für es genannt.
Das gemeinsame Aggregate
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 deklariert eine Nutzung databases von db. Der Block inject bindet provides.host des Datenbank-Recipe an die Umgebungsvariable ADMINER_DEFAULT_SERVER im Adminer-Container. Nichts im Aggregate nennt einen Provider; diese Wahl liegt vollständig in der Katalogschicht, die der Build lädt.
Ein Hinweis zu Zugangsdaten
Das MariaDB-Image benötigt zum Starten ein Root-Passwort, und der Anwendungsbenutzer benötigt ein eigenes. Beide werden in der Säule features: der Datenbankkomponente angebunden — getrennt von den values der Anwendung — als Features mit dem Label feature.aggrega.ai/kind: secret. Das featuresSchema der Component core/datastore/mariadb deklariert für jedes einen Slot, und das Beispiel nutzt beide Bereitstellungsmodelle:
root_passwordist ein Blackbox-Slot (inject: []): Das FeatureRecipe liefert den Wert in den Kanal der Komponente. Der Entwickler bestimmt nicht — und darf nicht bestimmen —, wie.user_passwordist ein transparenter Slot (inject: [env, file]): Die Zugangsdaten legen ihren Wert offen, und der Entwickler ordnet ihn mit dem Blockinject:an der Anbindung einer Umgebungsvariablen zu.
Die Werte hier sind Inline-Literale, damit der Stack mit einem einzigen Befehl läuft — geeignet für lokale Entwicklung und Demos. Für gemeinsam genutzte oder Produktionsumgebungen lösen dieselben Anbindungen ihre Werte aus einem Secret-Store auf: Der Katalog des Ziels lädt ein FeatureRecipe, das sie abruft, und das Aggregate ändert sich nicht.
Ziel 1 — Docker Compose
Erst Pull, dann Build — der Pull schreibt release-compose.lock, das der Build liest:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlAusgabe: dist/app/compose/docker-compose.yaml — zwei Dienste in einem Netzwerk. db führt mariadb:11.4 mit Datenbank, Benutzer, Zeichensatz und injizierten Passwörtern aus; web führt adminer:4 aus, veröffentlicht Port 8080, hängt von db ab und trägt ADMINER_DEFAULT_SERVER: db (den Compose-Servicenamen, den das Datenbank-Recipe ausgegeben hat).
Ausführen:
docker compose -f dist/app/compose/docker-compose.yaml up -dÖffnen Sie http://localhost:8080 und melden Sie sich an:
| Feld | Wert |
|---|---|
| System | MySQL / MariaDB |
| Server | db (bereits ausgefüllt) |
| Benutzername | appuser |
| Passwort | dev-app-pw-change-me |
| Datenbank | appdb |
(oder root / dev-root-pw-change-me). Abbauen mit docker compose -f dist/app/compose/docker-compose.yaml down -v.
Ziel 2 — Kubernetes (in sich geschlossen)
Dieses Ziel rendert einfache Kubernetes-Manifeste direkt aus der Workload, ohne externes Chart — ein einziger Offline-Build.
Die Workload der Datenbank deklariert form: stateful, daher synthetisiert sie ein StatefulSet, dessen Datenverzeichnis eine Volume-Claim-Vorlage pro Replica ist statt eines Deployment, das sich einen einzigen Claim teilt. Zwei Begleiter gehören zu dieser Form: Das Volume wird als persistentTemplate deklariert, und ein headless Service liefert die stabile DNS-Identität pro Pod, die das StatefulSet als seinen steuernden Service benennt. Adminer hält keinen Zustand, daher belässt seine Workload form beim Standardwert und bleibt ein Deployment — Persistenz ist eine Eigenschaft der Workload, keine andere Komponente.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlAusgabe unter 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 8080Beachten Sie ADMINER_DEFAULT_SERVER: db-default — für Kubernetes gibt das Datenbank-Recipe den clusterinternen Service-DNS-Namen aus, sodass dieselbe Kante des Aggregate auf diesem Ziel zu einer routbaren Adresse aufgelöst wird.
Anwenden und öffnen:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080Öffnen Sie http://localhost:8080 und melden Sie sich mit Server db-default, Benutzername appuser, Passwort dev-app-pw-change-me und Datenbank appdb an. Entfernen Sie es mit kubectl delete -f dist/app/helm/.
Ziel 3 — Kubernetes (verwaltetes Bitnami-Chart)
Die dritte Schicht implementiert dieselbe Component core/datastore/mariadb gegen das Bitnami-MariaDB-Helm-Chart aus dem Upstream, statt Manifeste zu synthetisieren. Das Recipe bezieht das Chart über eine OCI-Referenz und bildet die Werte der Component auf das Werteschema des Charts ab:
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 …Die source.version des Recipe bevorzugt die infra.source_version des Betreibers und greift ersatzweise auf den vom Entwickler verfassten .values.chart_version zurück. Das Fixieren der Chart-Version ist ein Infrastrukturbelang, daher gewinnt die Fixierung des Betreibers überall dort, wo ein Release eine setzt; dieses Release setzt bewusst keine, sodass der Schlüssel .values die tatsächlich aufgelöste Version ist — und genau das ist der Sinn dieses Ziels, denn ein Entwicklerwert, der die Quellauflösung erreicht, ist in der gerenderten Ausgabe nur beobachtbar, solange die betriebliche Fixierung fehlt. Fixieren Sie source_version an der Komponente db in release-helm-bitnami.yaml, und das gerenderte Label helm.sh/chart folgt stattdessen dieser Version.
optional liest die Fixierung über ihren Namen statt als gepunkteten Pfad, und genau das lässt eine fehlende Fixierung auf den Entwicklerwert zurückfallen, statt zu einer leeren Version aufgelöst zu werden — siehe optional für die Semantik der Präsenzprüfung.
Das Bauen dieses Ziels ist ein zweistufiger Ablauf: aggrega pull löst das Chart auf, fixiert es in release-helm-bitnami.lock und holt es in den inhaltsadressierten Build-Cache (der einzige Online-Schritt); aggrega build rendert dann aus dem Cache, sodass Lock-Zeit und Build-Zeit dasselbe Chart auflösen. Die injizierten Zugangsdaten fließen in die Werte auth des Charts, und das Chart erzeugt das Secret von Kubernetes, das die Datenbank liest. Adminer wird vom selben synthetisierten Recipe gerendert wie in Ziel 2 und verbindet sich mit dem primären Service des Charts (db-mariadb). Die beiden in sich geschlossenen Ziele oben sind der Weg ohne Abhängigkeiten, den Stack durchgängig zu betreiben.
Ziel 4 — Kubernetes (zusammengesetztes Helm-Chart)
Die vierte Schicht implementiert dieselben Komponenten gegen den Provider helm-chart, der ein weiterverteilbares Helm-Umbrella-Chart zusammensetzt, statt Manifeste zu rendern (Ziel 2) oder ein Upstream-Chart zu rendern (Ziel 3). Jedes Recipe bezieht ein kleines lokales Chart:
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" }Bauen:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamlAusgabe unter 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]Installieren (die Subcharts sind unter charts/ mitgeliefert, daher ist vorher kein helm dependency build nötig):
helm install mariadb-adminer dist/app/helm-chart/Die values.yaml des Umbrella-Charts enthält bereits die aufgelösten Werte jeder Komponente, sodass die Datenbank mit ihren Zugangsdaten startet und Adminer mit dem MariaDB-Service verbunden ist — dieselbe Verbindung, die die anderen Ziele ausdrücken, nun als Chart ausgeliefert, das Sie installieren oder mitliefern können.
Es gelten zwei unterschiedliche Delimiter-Regime, und sie überschneiden sich nicht:
- Bezogene Subcharts werden kopiert, bis auf ihren Namen. Die Dateien unter
./charts/mariadbund./charts/adminerwerden unverändert in das Umbrella-Chart gebündelt — ihre Helm-Direktiven{{ }}werden vom Compiler nicht angetastet und zum Zeitpunkt vonhelm installaufgelöst. Die einzige Aufgabe des Composers ist dort das Zusammenstellen, nicht das Templating. Das einzige Feld, das er setzt, istnamein jeder platziertenChart.yaml, das zur Identität der Komponenteninstanz wird (db,web), sodass zwei Komponenten, die Charts mit demselben deklarierten Namen mitliefern, unterscheidbar bleiben; sieheproviders/helm-chart.md. - Artefakte mit
$import:haben zwei Delimiter. Ein Recipe kann überartifacts: { name: { $import: ... } }zusätzliche Template-Dateien injizieren. Diese Dateien — und nur diese — werden vom Compiler mit den Delimitern[[ ]]vorgerendert, bevor sie abgelegt werden, während ihr{{ }}für Helm erhalten bleibt. Das Artefaktnetpol.yaml— mit dem Schlüsselnetpol.yamlund importiert aus./extras/mariadb-netpol.yaml, da der Schlüssel die ausgegebene Datei benennt und der Import ihren Inhalt auswählt — zeigt die Mischung:[[ .context.instance_id ]](beim Build gefüllt) und{{ .Release.Namespace }}(für die Installation belassen).
Die String Pipe wird in Chart-Begriffen ausgedrückt: Die Nutzung databases von MariaDB durch Adminer löst provides.host des Datenbank-Recipe in die values.yaml des Umbrella-Charts unter dem Alias web auf (adminerDefaultServer: db-mariadb), was das Adminer-Subchart als {{ .Values.adminerDefaultServer }} liest. Derselbe Wert benennt den Service des MariaDB-Subcharts, sodass die Verdrahtung bei der Installation konsistent aufgelöst wird. Die Ausgabe ist ein Chart für helm install oder zum Mitliefern — keine Menge angewendeter Manifeste.
Wie ein Ziel ausgewählt wird
Die Auswahl des Recipe erfolgt nach Komponententyp: Das Manifest jedes Ziels ordnet jeden Typ einem Recipe in der Katalogschicht zu, die sein Release lädt, sodass manifest-compose.yaml core/datastore/mariadb an das Compose-Recipe bindet, während manifest-helm-synth.yaml es an jenes für Kubernetes bindet. Ein Typ, den das Manifest nicht zuordnet, bricht den Build ab und nennt die Recipes, die ihn implementieren, selbst wenn die geladene Schicht nur eines enthält. Der Provider, der einen Knoten rendert, ist die spec.capability des jeweils gebundenen Recipe. Ziele zu wechseln heißt, das Release zu wechseln, mit seinem Manifest und dem Katalogverzeichnis, das .aggrega-config.yaml dafür benennt — das Aggregate ändert sich nie.