Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

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.yaml
manifest-compose.yaml
aggrega build
docker-compose.yaml

Sur un cluster Kubernetes

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

Manifestes 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.yaml est 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 databases de MariaDB ; le provides.host de la Recipe de la base de données est acheminé dans la variable d’environnement ADMINER_DEFAULT_SERVER d’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 Workload agnostique vis-à-vis des capacités ; le fournisseur synthétise un service docker-compose.yaml, ou les objets Kubernetes que demande le form du Workload — un Deployment et un Service pour l’interface web sans état, et pour la base de données form: stateful un StatefulSet dont le modèle de demande de volume par réplica porte le répertoire de données, à côté du Service headless qui le gouverne et du Service ClusterIP que 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 une Feature étiquetée feature.aggrega.ai/kind: secret, tenue à l’écart des values de l’application. Le featuresSchema du 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 bloc inject: 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 build rend à 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 valeur infra.source_version de 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 avec aggrega pull --release release-<variant>.yaml. Chaque variante de release se résout par rapport à son propre répertoire de catalogue voisin, que .aggrega-config.yaml nomme pour elle sous workspace.releases, si bien qu’aucun --catalog n’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-uri qui 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-chart compose un chart parapluie : le sous-chart local de chaque composant y est copié tel quel (ses {{ }} Helm préservés intacts), et le values.yaml du 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 :

Terminal window
aggrega scaffold --example mariadb-adminer

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd mariadb-adminer

Build

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 :

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

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

web 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_password est 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_password est 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 bloc inject: 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 :

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

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

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

Ouvrez http://localhost:8080 et connectez-vous :

ChampValeur
SystèmeMySQL / MariaDB
Serveurdb (déjà renseigné)
Nom d’utilisateurappuser
Mot de passedev-app-pw-change-me
Base de donnéesappdb

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

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

Sortie sous 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

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

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

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

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

Sortie sous 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]

L’installer (les sous-charts sont embarqués sous charts/, si bien qu’aucun helm dependency build n’est nécessaire au préalable) :

Terminal window
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/mariadb et ./charts/adminer sont 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 de helm install. Le seul rôle du compositeur à cet endroit est l’assemblage, pas le templating. Le seul champ qu’il définit est le name de chaque Chart.yaml placé, 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 ; voir providers/helm-chart.md.
  • Les artefacts $import: utilisent deux délimiteurs. Une Recipe peut injecter des fichiers de template supplémentaires via artifacts: { 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’artefact netpol.yaml — de clé netpol.yaml et 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.