Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

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

einmal geschrieben

Auf einem Laptop

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

Auf einem Kubernetes-Cluster

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

Kubernetes-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.yaml ist 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 databases von MariaDB; der Wert provides.host des Datenbank-Recipe wird in die Umgebungsvariable ADMINER_DEFAULT_SERVER von 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 in docker-compose.yaml oder die Kubernetes-Objekte, die die form der Workload verlangt — ein Deployment und einen Service für die zustandslose Web-UI und für die Datenbank mit form: stateful ein StatefulSet, dessen Volume-Claim-Vorlage pro Replica das Datenverzeichnis trägt, neben dem headless Service, der es steuert, und dem Service vom Typ ClusterIP, den Konsumenten ansprechen.
  • Das Zugangsdaten-Subsystem. Datenbankpasswörter werden in der Säule features: der Komponente angebunden — jedes ein Feature mit dem Label feature.aggrega.ai/kind: secret, getrennt von den values der Anwendung. Das featuresSchema der 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 Block inject: an der Anbindung liefert.
  • Entfernte Chart-Quellen. Das verwaltete Kubernetes-Ziel bezieht das Upstream-MariaDB-Chart von Bitnami per OCI-Referenz. aggrega pull fixiert das Chart in einem Lockfile und ruft es in einen inhaltsadressierten Cache ab; aggrega build rendert aus diesem Cache, sodass Lock-Zeit und Build-Zeit dasselbe Chart auflösen. Die Chart-Version stammt aus infra.source_version des 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 mit aggrega pull --release release-<variant>.yaml. Jede Release-Variante wird gegen ihr eigenes benachbartes Katalogverzeichnis aufgelöst, das .aggrega-config.yaml für sie unter workspace.releases nennt, sodass weder im Terminal noch in einem Editor noch über einen Assistenten ein --catalog nö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-chart setzt ein Umbrella-Chart zusammen: Das lokale Subchart jeder Komponente wird unverändert hineinkopiert (seine Helm-Ausdrücke {{ }} bleiben unangetastet), und die values.yaml des 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:

Terminal window
aggrega scaffold --example mariadb-adminer

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd mariadb-adminer

Build

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:

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

Mit 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: host

web 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_password ist ein Blackbox-Slot (inject: []): Das FeatureRecipe liefert den Wert in den Kanal der Komponente. Der Entwickler bestimmt nicht — und darf nicht bestimmen —, wie.
  • user_password ist ein transparenter Slot (inject: [env, file]): Die Zugangsdaten legen ihren Wert offen, und der Entwickler ordnet ihn mit dem Block inject: 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:

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

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

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

Öffnen Sie http://localhost:8080 und melden Sie sich an:

FeldWert
SystemMySQL / MariaDB
Serverdb (bereits ausgefüllt)
Benutzernameappuser
Passwortdev-app-pw-change-me
Datenbankappdb

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

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

Ausgabe unter 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

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

Terminal window
kubectl apply -f dist/app/helm/
kubectl rollout status statefulset/db
kubectl 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:

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

Ausgabe unter 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]

Installieren (die Subcharts sind unter charts/ mitgeliefert, daher ist vorher kein helm dependency build nötig):

Terminal window
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/mariadb und ./charts/adminer werden unverändert in das Umbrella-Chart gebündelt — ihre Helm-Direktiven {{ }} werden vom Compiler nicht angetastet und zum Zeitpunkt von helm install aufgelöst. Die einzige Aufgabe des Composers ist dort das Zusammenstellen, nicht das Templating. Das einzige Feld, das er setzt, ist name in jeder platzierten Chart.yaml, das zur Identität der Komponenteninstanz wird (db, web), sodass zwei Komponenten, die Charts mit demselben deklarierten Namen mitliefern, unterscheidbar bleiben; siehe providers/helm-chart.md.
  • Artefakte mit $import: haben zwei Delimiter. Ein Recipe kann über artifacts: { 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 Artefakt netpol.yaml — mit dem Schlüssel netpol.yaml und 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.