MariaDB + Adminer — un exemple exécutable à deux cibles
Cet exemple compile une petite stack réelle — une base de données MariaDB avec une interface web Adminer devant elle — à partir d’un seul Aggregate écrit par le développeur vers deux plateformes :
- Docker Compose pour le développement local, et
- Kubernetes pour un cluster local (kind / minikube / k3d), rendu de trois façons.
Le même Aggregate pilote les deux. Seuls la Release, son Manifest et la couche de Recipe chargée au moment du build changent. Chaque fichier ici se compile avec la CLI aggrega livrée, et la sortie rendue s’exécute : démarrez la stack, ouvrez Adminer dans un navigateur et connectez-vous à la base de données en cours d’exécution.
aggregate.yamlécrit une seule fois
Sur un ordinateur portable
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlSur un cluster Kubernetes
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildManifestes Kubernetes
Chaque plateforme est compilée à partir de sa propre Release et de son propre Manifest. L’Aggregate, qui décrit votre application, reste le même.
Ce qu’il démontre
- Une seule surface de rédaction, plusieurs cibles. Un seul
aggregate.yamlest la source de vérité sur ce qu’est la stack. Chaque cible est une fine couche de catalogue qui dit comment la réaliser. - Le String Pipe. Adminer déclare une utilisation
databasesde MariaDB ; leprovides.hostde la Recipe de la base de données est acheminé dans la variable d’environnementADMINER_DEFAULT_SERVERd’Adminer. Le compilateur achemine la chaîne sans l’interpréter — ainsi le build compose câble un nom de service compose et le build Kubernetes câble un nom DNS de Service, à partir de la même arête. - Synthèse de Workload. Les Recipes compose et Kubernetes autonome déclarent un
Workloadagnostique vis-à-vis des capacités ; le fournisseur synthétise un servicedocker-compose.yaml, ou les objets Kubernetes que demande leformdu Workload — unDeploymentet unServicepour l’interface web sans état, et pour la base de donnéesform: statefulunStatefulSetdont le modèle de demande de volume par réplica porte le répertoire de données, à côté duServiceheadless qui le gouverne et duServiceClusterIPque contactent les consommateurs. - Le sous-système des informations d’identification. Les mots de passe de la base de données sont rattachés dans le pilier
features:du composant — chacun uneFeatureétiquetéefeature.aggrega.ai/kind: secret, tenue à l’écart desvaluesde l’application. LefeaturesSchemadu Component déclare deux types de slot, et l’exemple exerce les deux : un slot en boîte noire dont la FeatureRecipe livre la valeur en interne, et un slot transparent dont le développeur livre la valeur explicitement avec un blocinject:sur le rattachement. - Des sources de chart distantes. La cible Kubernetes gérée prend comme source le chart MariaDB upstream de Bitnami par référence OCI.
aggrega pullépingle le chart dans un fichier de verrouillage et le récupère dans un cache adressé par contenu ;aggrega buildrend à partir de ce cache, si bien que le moment du verrouillage et celui du build résolvent le même chart. La version du chart provient de la valeurinfra.source_versionde l’opérateur lorsque la Release en épingle une, et sinon d’une valeur écrite par le développeur (une valeur qui alimente la résolution de la source). Les fichiers de verrouillage par release épinglent les identités et les digests des entités : après que des entités du catalogue ont été renommées ou que leur contenu a changé, rafraîchissez un fichier de verrouillage local obsolète avecaggrega pull --release release-<variant>.yaml. Chaque variante de release se résout par rapport à son propre répertoire de catalogue voisin, que.aggrega-config.yamlnomme pour elle sousworkspace.releases, si bien qu’aucun--catalogn’est nécessaire dans un terminal, dans un éditeur ou via un assistant. - La provenance sous forme d’annotations. Chaque objet Kubernetes rendu porte une annotation
aggrega.ai/recipe-uriqui enregistre la Recipe qui l’a produit — une annotation, et non une étiquette, car la valeur URI contient des caractères que la valeur d’une étiquette Kubernetes ne peut pas contenir. - Composition de chart (par opposition à la synthèse). Le même Aggregate peut produire un chart Helm redistribuable au lieu de manifestes rendus. Le fournisseur
helm-chartcompose un chart parapluie : le sous-chart local de chaque composant y est copié tel quel (ses{{ }}Helm préservés intacts), et levalues.yamldu chart parapluie achemine les valeurs mappées de chaque composant — y compris l’hôte de base de données acheminé — sous l’alias de ce composant. - Sélection du Provider par type de composant. La Recipe qui rend chaque composant est celle vers laquelle le Manifest de la cible mappe le type du composant, tirée de la couche de catalogue que charge le build.
Rédaction et consommation — un espace de travail mixte
Cet exemple travaille les deux extrémités du catalogue à la fois : il rédige certaines entités localement et en consomme d’autres depuis la bibliothèque standard d’Aggrega. Le Component de base de données MariaDB, ses Features d’informations d’identification et les Recipes par cible sont construits de zéro dans les répertoires locaux catalog-*/ — un seul Aggregate rend cette base de données rédigée localement sur quatre cibles. L’interface web Adminer, en revanche, est consommée : le composant web référence directement le Component livré core/devtool/adminer, et chaque cible ne rédige qu’une Recipe locale qui l’implémente. Le même espace de travail montre donc la rédaction d’entités côté base de données à côté de la consommation du catalogue côté interface. Les entités que vous construisez ici sont du même type que celles livrées dans la bibliothèque standard : un Component de base de données, des Features d’informations d’identification, des Recipes de fournisseur.
L’exemple catalog-only se situe à l’extrémité de la consommation pure du même parcours : il assemble cette même stack — une base de données MariaDB avec une interface Adminer — en référençant des entités de la bibliothèque standard, sans en rédiger aucune. Lisez le côté base de données de cet exemple pour apprendre comment les entités de catalogue sont construites ; lisez les exemples de consommation pour apprendre comment une stack entière est utilisée à partir du catalogue livré.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example mariadb-adminerElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd mariadb-adminerBuild
Chaque cible est une Release, compilée une par exécution ; le pull écrit le lockfile que lit le build. Docker Compose d’abord — la section de chaque cible ci-dessous donne ses propres commandes :
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlAvec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `mariadb-adminer`, appelez une fois l’outil `scaffold` avec `example` défini sur `mariadb-adminer` et sans `dir` : il écrit l’exemple dans un nouveau dossier `mariadb-adminer`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `mariadb-adminer`, `release` défini sur `release-compose.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `mariadb-adminer/dist/`.Organisation
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)Chaque répertoire catalog-* porte les définitions du Component MariaDB et de la Feature rédigées localement, ainsi que les Recipes pour cette seule cible. Le Component Adminer n’en fait pas partie — il est résolu depuis la bibliothèque standard. Un build charge une couche catalog-* par-dessus cette bibliothèque standard, et le Manifest de la cible mappe chaque type de composant vers une Recipe qu’elle contient.
La Release, son aggregate: et son manifest: sont voisins dans ce répertoire ; le répertoire de catalogue sur lequel chaque Release est construite est nommé pour elle dans .aggrega-config.yaml.
L’Aggregate partagé
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 déclare une utilisation databases de db. Le bloc inject lie le provides.host de la Recipe de la base de données à la variable d’environnement ADMINER_DEFAULT_SERVER du conteneur Adminer. Rien dans l’Aggregate ne nomme un fournisseur ; ce choix réside entièrement dans la couche de catalogue que charge le build.
Une note sur les informations d’identification
L’image MariaDB a besoin d’un mot de passe root pour démarrer, et l’utilisateur de l’application a besoin du sien. Les deux sont rattachés dans le pilier features: du composant de base de données — à l’écart des values de l’application — sous forme de Features étiquetées feature.aggrega.ai/kind: secret. Le featuresSchema du Component core/datastore/mariadb déclare un slot pour chacun, et l’exemple exerce les deux modèles de livraison :
root_passwordest un slot en boîte noire (inject: []) : la FeatureRecipe livre la valeur dans le canal du composant. Le développeur ne dicte pas — et ne peut pas dicter — comment.user_passwordest un slot transparent (inject: [env, file]) : l’information d’identification expose sa valeur, et le développeur la mappe vers une variable d’environnement avec le blocinject:sur le rattachement.
Les valeurs sont ici des littéraux en ligne afin que la stack s’exécute avec une seule commande — ce qui convient au développement local et aux démonstrations. Pour des environnements partagés ou de production, les mêmes rattachements résolvent leurs valeurs depuis un magasin de secrets : le catalogue de la cible charge une FeatureRecipe qui les récupère, et l’Aggregate ne change pas.
Cible 1 — Docker Compose
D’abord le pull, puis le build — le pull écrit release-compose.lock, que le build lit :
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlSortie : dist/app/compose/docker-compose.yaml — deux services sur un seul réseau. db exécute mariadb:11.4 avec la base de données, l’utilisateur, le jeu de caractères et les mots de passe injectés ; web exécute adminer:4, publie le port 8080, dépend de db et porte ADMINER_DEFAULT_SERVER: db (le nom de service compose qu’a émis la Recipe de la base de données).
L’exécuter :
docker compose -f dist/app/compose/docker-compose.yaml up -dOuvrez http://localhost:8080 et connectez-vous :
| Champ | Valeur |
|---|---|
| Système | MySQL / MariaDB |
| Serveur | db (déjà renseigné) |
| Nom d’utilisateur | appuser |
| Mot de passe | dev-app-pw-change-me |
| Base de données | appdb |
(ou root / dev-root-pw-change-me). Pour tout arrêter, utilisez docker compose -f dist/app/compose/docker-compose.yaml down -v.
Cible 2 — Kubernetes (autonome)
Cette cible rend des manifestes Kubernetes simples directement à partir du Workload, sans chart externe — un seul build hors ligne.
Le Workload de la base de données déclare form: stateful, si bien qu’il synthétise un StatefulSet dont le répertoire de données est un modèle de volume claim par réplica plutôt qu’un Deployment partageant un seul claim. Deux compagnons accompagnent cette forme : le volume est déclaré comme persistentTemplate, et un Service headless fournit l’identité DNS stable par pod que le StatefulSet désigne comme son service de gouvernance. Adminer ne conserve aucun état, si bien que son Workload laisse form à la valeur par défaut et reste un Deployment — la persistance est une propriété du Workload, pas un composant différent.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlSortie sous 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 8080Notez ADMINER_DEFAULT_SERVER: db-default — pour Kubernetes, la Recipe de la base de données émet le nom DNS du Service interne au cluster, si bien que la même arête de l’Aggregate se résout en une adresse routable sur cette cible.
L’appliquer et l’ouvrir :
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080Ouvrez http://localhost:8080 et connectez-vous avec Server db-default, le nom d’utilisateur appuser, le mot de passe dev-app-pw-change-me et la base de données appdb. Pour le supprimer, utilisez kubectl delete -f dist/app/helm/.
Cible 3 — Kubernetes (chart Bitnami géré)
La troisième couche implémente le même Component core/datastore/mariadb sur le chart Helm MariaDB de Bitnami en amont au lieu de synthétiser des manifestes. La Recipe prend comme source le chart par référence OCI et associe les valeurs du Component au schéma de valeurs du 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 …Le source.version de la Recipe privilégie le infra.source_version de l’opérateur et se rabat sur le .values.chart_version écrit par le développeur. L’épinglage de la version du chart relève de l’infrastructure, si bien que l’épinglage de l’opérateur l’emporte partout où une Release en définit un ; cette Release n’en définit délibérément aucun, si bien que la clé .values est la version qui se résout réellement — et c’est tout l’intérêt de cette cible, car une valeur du développeur qui atteint la résolution de la source n’est observable dans la sortie rendue que tant que l’épinglage opérationnel est absent. Épinglez source_version sur le composant db dans release-helm-bitnami.yaml et l’étiquette helm.sh/chart rendue suit alors cette version.
optional lit l’épinglage par son nom plutôt que comme un chemin pointé, ce qui permet à un épinglage absent de retomber sur la valeur du développeur plutôt que de se résoudre en une version vide — voir optional pour la sémantique de la vérification de présence.
Construire cette cible est un flux en deux étapes : aggrega pull résout le chart, l’épingle dans release-helm-bitnami.lock et le récupère dans le cache de build adressé par contenu (la seule étape en ligne) ; aggrega build rend ensuite à partir du cache, si bien que le moment du verrouillage et celui du build résolvent le même chart. Les informations d’identification injectées alimentent les valeurs auth du chart, et le chart génère le Secret Kubernetes que la base de données lit. Adminer est rendu par la même Recipe synthétisée que dans la Cible 2 et se connecte au Service primaire du chart (db-mariadb). Les deux cibles autonomes ci-dessus sont la manière sans dépendance d’exécuter la stack de bout en bout.
Cible 4 — Kubernetes (chart Helm composé)
La quatrième couche implémente les mêmes composants sur le fournisseur helm-chart, qui compose un chart Helm parapluie redistribuable au lieu de rendre des manifestes (Cible 2) ou de rendre un chart en amont (Cible 3). Chaque Recipe prend comme source un petit chart local :
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" }Le construire :
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamlSortie sous 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]L’installer (les sous-charts sont embarqués sous charts/, si bien qu’aucun helm dependency build n’est nécessaire au préalable) :
helm install mariadb-adminer dist/app/helm-chart/Le values.yaml du chart parapluie contient déjà les valeurs résolues de chaque composant, si bien que la base de données démarre avec ses informations d’identification et qu’Adminer est câblé au Service MariaDB — la même connexion que les autres cibles expriment, désormais livrée sous forme d’un chart que vous pouvez installer ou embarquer.
Deux régimes de délimiteurs distincts s’appliquent, et ils ne se chevauchent pas :
- Les sous-charts à source sont copiés, à l’exception de leur nom. Les fichiers sous
./charts/mariadbet./charts/adminersont regroupés dans le chart parapluie sans modification — leurs directives Helm{{ }}ne sont pas touchées par le compilateur et se résolvent au moment dehelm install. Le seul rôle du compositeur à cet endroit est l’assemblage, pas le templating. Le seul champ qu’il définit est lenamede chaqueChart.yamlplacé, qui devient l’identité de l’instance du composant (db,web), afin que deux composants embarquant des charts qui déclarent le même nom restent distinguables ; voirproviders/helm-chart.md. - Les artefacts
$import:utilisent deux délimiteurs. Une Recipe peut injecter des fichiers de template supplémentaires viaartifacts: { name: { $import: ... } }. Ces fichiers — et seulement eux — sont pré-rendus par le compilateur avec les délimiteurs[[ ]]avant d’être déposés, tandis que leur{{ }}est préservé pour Helm. L’artefactnetpol.yaml— de clénetpol.yamlet importé depuis./extras/mariadb-netpol.yaml, puisque la clé nomme le fichier émis et que l’import en sélectionne le contenu — montre le mélange :[[ .context.instance_id ]](rempli au build) et{{ .Release.Namespace }}(laissé pour l’installation).
Le String Pipe s’exprime en termes de chart : l’utilisation databases de MariaDB par Adminer résout le provides.host de la Recipe de la base de données dans le values.yaml du chart parapluie sous l’alias web (adminerDefaultServer: db-mariadb), que le sous-chart Adminer lit comme {{ .Values.adminerDefaultServer }}. La même valeur nomme le Service du sous-chart MariaDB, si bien que le câblage se résout de manière cohérente à l’installation. La sortie est un chart à passer à helm install ou à embarquer — pas un ensemble de manifestes appliqués.
Comment une cible est sélectionnée
La sélection de la Recipe se fait par type de composant : le Manifest de chaque cible associe chaque type à une Recipe de la couche de catalogue que charge sa Release, si bien que manifest-compose.yaml lie core/datastore/mariadb à la Recipe compose, tandis que manifest-helm-synth.yaml le lie à celle pour Kubernetes. Un type que le Manifest n’associe pas arrête le build, en nommant les Recipes qui l’implémentent, même lorsque la couche chargée n’en contient qu’une. Le fournisseur qui rend un nœud est le spec.capability de la Recipe liée, quelle qu’elle soit. Changer de cible revient à changer de Release, avec son Manifest et le répertoire de catalogue que .aggrega-config.yaml nomme pour elle — l’Aggregate ne change jamais.