MariaDB + Adminer — un ejemplo ejecutable con dos destinos
Este ejemplo compila un stack pequeño y real — una base de datos MariaDB con una UI web Adminer delante — a partir de un único Aggregate escrito por el desarrollador para dos plataformas:
- Docker Compose para el desarrollo local, y
- Kubernetes para un clúster local (kind / minikube / k3d), renderizado de tres maneras.
El mismo Aggregate impulsa ambas. Solo cambian la Release, su Manifest y la capa de Recipe cargada en tiempo de compilación. Todos los archivos de aquí se compilan con la CLI aggrega publicada, y la salida renderizada se ejecuta: levanta el stack, abre Adminer en un navegador e inicia sesión en la base de datos en ejecución.
aggregate.yamlescrito una sola vez
En un portátil
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlEn un clúster de Kubernetes
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildManifiestos de Kubernetes
Cada plataforma se compila a partir de su propia Release y su propio Manifest. El Aggregate, que describe tu aplicación, sigue siendo el mismo.
Lo que demuestra
- Una única superficie de autoría, muchos destinos. Un único
aggregate.yamles la fuente de verdad sobre qué es el stack. Cada destino es una fina capa de catálogo que dice cómo realizarlo. - El String Pipe. Adminer declara un uso
databasesde MariaDB; elprovides.hostde la Recipe de la base de datos se canaliza a la variable de entornoADMINER_DEFAULT_SERVERde Adminer. El compilador enruta la cadena sin interpretarla — así, la compilación de compose conecta un nombre de servicio de compose y la compilación de Kubernetes conecta un nombre DNS de Service, a partir de la misma arista. - Síntesis de Workload. Las Recipes de compose y de Kubernetes autónomo declaran un
Workloadagnóstico respecto a las capacidades; el proveedor sintetiza un servicio dedocker-compose.yaml, o los objetos de Kubernetes que pide elformdel Workload — unDeploymenty unServicepara la UI web sin estado, y para la base de datosform: statefulunStatefulSetcuya plantilla de reclamación de volumen por réplica lleva el directorio de datos, junto alServiceheadless que lo gobierna y alServiceClusterIPal que llaman los consumidores. - El subsistema de credenciales. Las contraseñas de la base de datos se vinculan en el pilar
features:del componente — cada una unaFeatureetiquetadafeature.aggrega.ai/kind: secret, separada de losvaluesde la aplicación. ElfeaturesSchemadel Component declara dos tipos de slot, y el ejemplo ejercita ambos: un slot de caja negra cuya FeatureRecipe entrega el valor internamente, y un slot transparente cuyo valor el desarrollador entrega explícitamente con un bloqueinject:en la vinculación. - Fuentes de chart remotas. El destino Kubernetes gestionado toma como origen el chart upstream de MariaDB de Bitnami mediante referencia OCI.
aggrega pullfija el chart en un archivo de bloqueo y lo descarga en una caché direccionada por contenido;aggrega buildrenderiza desde esa caché, así que el momento del bloqueo y el de la compilación resuelven el mismo chart. La versión del chart procede delinfra.source_versiondel operador cuando la Release fija una, y en caso contrario de un valor escrito por el desarrollador (un valor que fluye hacia la resolución del origen). Los archivos de bloqueo por release fijan las identidades y los digests de las entidades: después de que se renombren entidades del catálogo o cambie su contenido, actualiza un archivo de bloqueo local obsoleto conaggrega pull --release release-<variant>.yaml. Cada variante de release se resuelve contra su propio directorio de catálogo hermano, que.aggrega-config.yamlnombra para ella bajoworkspace.releases, así que no se necesita ningún--catalogen una terminal, en un editor ni a través de un asistente. - Procedencia como anotaciones. Cada objeto de Kubernetes renderizado lleva una anotación
aggrega.ai/recipe-urique registra la Recipe que lo produjo — una anotación, no una etiqueta, porque el valor URI contiene caracteres que el valor de una etiqueta de Kubernetes no puede contener. - Composición de charts (frente a síntesis). El mismo Aggregate puede producir un chart de Helm redistribuible en lugar de manifiestos renderizados. El proveedor
helm-chartcompone un chart paraguas: el subchart local de cada componente se copia tal cual (con sus{{ }}de Helm intactos), y elvalues.yamldel chart paraguas enruta los valores asignados de cada componente — incluido el host de la base de datos canalizado — bajo el alias de ese componente. - Selección del Provider por tipo de componente. La Recipe que renderiza cada componente es aquella a la que el Manifest del destino asigna el tipo del componente, tomada de la capa de catálogo que cargue la compilación.
Autoría y consumo — un espacio de trabajo mixto
Este ejemplo trabaja ambos extremos del catálogo a la vez: escribe algunas entidades localmente y consume otras de la biblioteca estándar de Aggrega. El Component de base de datos MariaDB, sus Features de credencial y las Recipes por destino se construyen desde cero en los directorios locales catalog-*/ — un único Aggregate renderiza esa base de datos escrita localmente en cuatro destinos. La UI web Adminer, en cambio, se consume: el componente web hace referencia directamente al Component publicado core/devtool/adminer, y cada destino escribe solo una Recipe local que lo implementa. Por tanto, el mismo espacio de trabajo muestra la autoría de entidades en el lado de la base de datos junto al consumo del catálogo en el lado de la UI. Las entidades que construyes aquí son del mismo tipo que las que se publican en la biblioteca estándar: un Component de base de datos, Features de credencial, Recipes de proveedor.
El ejemplo catalog-only se sitúa en el extremo del consumo puro del mismo itinerario: ensambla este mismo stack — una base de datos MariaDB con una UI Adminer — haciendo referencia a entidades de la biblioteca estándar, sin escribir ninguna propia. Lee el lado de la base de datos de este ejemplo para aprender cómo se construyen las entidades del catálogo; lee los ejemplos de consumo para aprender cómo se usa un stack completo a partir del catálogo publicado.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example mariadb-adminerDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd mariadb-adminerCompilación
Cada destino es una Release, compilada una por ejecución; el pull escribe el lockfile que lee el build. Primero Docker Compose — la sección de cada destino, más abajo, da sus propios comandos:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlCon un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees tú ninguna carpeta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `mariadb-adminer`, llama una vez a la herramienta `scaffold` con `example` establecido en `mariadb-adminer` y sin `dir`: escribe el ejemplo en una nueva carpeta `mariadb-adminer`. Después llama a la herramienta `build` con `workspace_root` establecido en `mariadb-adminer`, `release` establecido en `release-compose.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `mariadb-adminer/dist/`.Estructura
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)Cada directorio catalog-* lleva las definiciones del Component MariaDB y de la Feature escritas localmente, más las Recipes para ese único destino. El Component Adminer no está entre ellas — se resuelve desde la biblioteca estándar. Una compilación carga una capa catalog-* sobre esa biblioteca estándar, y el Manifest del destino asigna cada tipo de componente a una Recipe de esa capa.
La Release, su aggregate: y su manifest: son hermanos en este directorio; el directorio de catálogo contra el que se compila cada Release se nombra para ella en .aggrega-config.yaml.
El Aggregate compartido
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 declara un uso databases de db. El bloque inject enlaza el provides.host de la Recipe de la base de datos con la variable de entorno ADMINER_DEFAULT_SERVER del contenedor de Adminer. Nada en el Aggregate nombra un proveedor; esa elección reside por completo en la capa de catálogo que carga la compilación.
Una nota sobre las credenciales
La imagen de MariaDB necesita una contraseña de root para arrancar, y el usuario de la aplicación necesita la suya. Ambas se vinculan en el pilar features: del componente de base de datos — separadas de los values de la aplicación — como Features etiquetadas feature.aggrega.ai/kind: secret. El featuresSchema del Component core/datastore/mariadb declara un slot para cada una, y el ejemplo ejercita ambos modelos de entrega:
root_passwordes un slot de caja negra (inject: []): la FeatureRecipe entrega el valor en el canal del componente. El desarrollador no dicta — ni puede dictar — cómo.user_passwordes un slot transparente (inject: [env, file]): la credencial expone su valor, y el desarrollador lo asigna a una variable de entorno con el bloqueinject:en la vinculación.
Aquí los valores son literales en línea para que el stack se ejecute con un solo comando — adecuado para el desarrollo local y las demos. Para entornos compartidos o de producción, las mismas vinculaciones resuelven sus valores desde un almacén de secretos: el catálogo del destino carga una FeatureRecipe que los obtiene, y el Aggregate no cambia.
Destino 1 — Docker Compose
Primero el pull, después la compilación — el pull escribe release-compose.lock, que la compilación lee:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlSalida: dist/app/compose/docker-compose.yaml — dos servicios en una red. db ejecuta mariadb:11.4 con la base de datos, el usuario, el juego de caracteres y las contraseñas inyectadas; web ejecuta adminer:4, publica el puerto 8080, depende de db y lleva ADMINER_DEFAULT_SERVER: db (el nombre de servicio de compose que emitió la Recipe de la base de datos).
Ejecutarlo:
docker compose -f dist/app/compose/docker-compose.yaml up -dAbre http://localhost:8080 e inicia sesión:
| Campo | Valor |
|---|---|
| Sistema | MySQL / MariaDB |
| Servidor | db (ya rellenado) |
| Nombre de usuario | appuser |
| Contraseña | dev-app-pw-change-me |
| Base de datos | appdb |
(o root / dev-root-pw-change-me). Para desmontarlo, usa docker compose -f dist/app/compose/docker-compose.yaml down -v.
Destino 2 — Kubernetes (autónomo)
Este destino renderiza manifiestos de Kubernetes simples directamente a partir del Workload, sin chart externo — una única compilación sin conexión.
El Workload de la base de datos declara form: stateful, así que sintetiza un StatefulSet cuyo directorio de datos es una plantilla de volume claim por réplica en lugar de un Deployment que comparte un único claim. Dos acompañantes viajan con esa forma: el volumen se declara como persistentTemplate, y un Service headless proporciona la identidad DNS estable por pod que el StatefulSet nombra como su servicio de gobierno. Adminer no guarda estado, así que su Workload deja form en el valor predeterminado y sigue siendo un Deployment — la persistencia es una propiedad del Workload, no un componente diferente.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlSalida en 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 8080Observa ADMINER_DEFAULT_SERVER: db-default — para Kubernetes, la Recipe de la base de datos emite el nombre DNS del Service interno del clúster, así que la misma arista del Aggregate se resuelve en una dirección enrutable en este destino.
Aplicarlo y abrirlo:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080Abre http://localhost:8080 e inicia sesión con Server db-default, nombre de usuario appuser, contraseña dev-app-pw-change-me y base de datos appdb. Para eliminarlo, usa kubectl delete -f dist/app/helm/.
Destino 3 — Kubernetes (chart de Bitnami gestionado)
La tercera capa implementa el mismo Component core/datastore/mariadb sobre el chart de Helm de MariaDB de Bitnami de upstream en lugar de sintetizar manifiestos. La Recipe toma como origen el chart mediante referencia OCI y asigna los valores del Component al esquema de valores 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 …El source.version de la Recipe prefiere el infra.source_version del operador y recurre al .values.chart_version escrito por el desarrollador. Fijar la versión del chart es un asunto de infraestructura, así que la fijación del operador prevalece dondequiera que una Release establezca una; esta Release deliberadamente no establece ninguna, así que la clave .values es la versión que realmente se resuelve — que es justamente el propósito de este destino, porque un valor del desarrollador que llega a la resolución del origen solo es observable en la salida renderizada mientras la fijación operativa esté ausente. Fija source_version en el componente db de release-helm-bitnami.yaml y la etiqueta helm.sh/chart renderizada sigue esa versión en su lugar.
optional lee la fijación por nombre en lugar de como una ruta con puntos, que es lo que permite que una fijación ausente recurra al valor del desarrollador en lugar de resolverse en una versión vacía — consulta optional para la semántica de la comprobación de presencia.
Compilar este destino es un flujo de dos pasos: aggrega pull resuelve el chart, lo fija en release-helm-bitnami.lock y lo descarga en la caché de compilación direccionada por contenido (el único paso en línea); aggrega build luego renderiza desde la caché, así que el momento del bloqueo y el de la compilación resuelven el mismo chart. Las credenciales inyectadas fluyen a los valores auth del chart, y el chart genera el Secret de Kubernetes que lee la base de datos. Adminer se renderiza con la misma Recipe sintetizada que en el Destino 2 y se conecta al Service primario del chart (db-mariadb). Los dos destinos autónomos anteriores son la forma sin dependencias de ejecutar el stack de extremo a extremo.
Destino 4 — Kubernetes (chart de Helm compuesto)
La cuarta capa implementa los mismos componentes sobre el proveedor helm-chart, que compone un chart paraguas de Helm redistribuible en lugar de renderizar manifiestos (Destino 2) o renderizar un chart de upstream (Destino 3). Cada Recipe toma como origen un pequeño 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" }Compilarlo:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamlSalida en 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]Instalarlo (los subcharts están incluidos en charts/, así que no hace falta un helm dependency build antes):
helm install mariadb-adminer dist/app/helm-chart/El values.yaml del chart paraguas ya lleva los valores resueltos de cada componente, así que la base de datos arranca con sus credenciales y Adminer queda conectado al Service de MariaDB — la misma conexión que expresan los demás destinos, ahora entregada como un chart que puedes instalar o incluir en tu proyecto.
Se aplican dos regímenes de delimitadores distintos, y no se solapan:
- Los subcharts con origen se copian, salvo su propio nombre. Los archivos de
./charts/mariadby./charts/adminerse empaquetan en el chart paraguas sin cambios — el compilador no toca sus directivas Helm{{ }}, que se resuelven en el momento dehelm install. La única tarea del compositor ahí es el ensamblaje, no el templating. El único campo que sí establece es elnamede cadaChart.yamlcolocado, que se convierte en la identidad de la instancia del componente (db,web) para que dos componentes que incluyen charts que declaran un mismo nombre sigan siendo distinguibles; consultaproviders/helm-chart.md. - Los artefactos
$import:usan dos delimitadores. Una Recipe puede inyectar archivos de plantilla adicionales medianteartifacts: { name: { $import: ... } }. Esos archivos — y solo esos — los prerenderiza el compilador con los delimitadores[[ ]]antes de que se depositen, mientras que su{{ }}se conserva para Helm. El artefactonetpol.yaml— con clavenetpol.yamle importado desde./extras/mariadb-netpol.yaml, ya que la clave nombra el archivo emitido y la importación selecciona su contenido — muestra la mezcla:[[ .context.instance_id ]](rellenado en la compilación) y{{ .Release.Namespace }}(dejado para la instalación).
El String Pipe se expresa en términos de chart: el uso databases de MariaDB por parte de Adminer resuelve el provides.host de la Recipe de la base de datos en el values.yaml del chart paraguas bajo el alias web (adminerDefaultServer: db-mariadb), que el subchart de Adminer lee como {{ .Values.adminerDefaultServer }}. El mismo valor nombra el Service del subchart de MariaDB, así que el cableado se resuelve de forma coherente en la instalación. La salida es un chart para helm install o para incluir — no un conjunto de manifiestos aplicados.
Cómo se selecciona un destino
La selección de la Recipe se hace por tipo de componente: el Manifest de cada destino asigna cada tipo a una Recipe de la capa de catálogo que carga su Release, así que manifest-compose.yaml enlaza core/datastore/mariadb con la Recipe de compose, mientras que manifest-helm-synth.yaml lo enlaza con la de Kubernetes. Un tipo que el Manifest no asigna detiene la compilación, nombrando las Recipes que lo implementan, incluso cuando la capa cargada contiene solo una. El proveedor que renderiza un nodo es el spec.capability de la Recipe que se haya enlazado. Cambiar de destino es cambiar la Release, con su Manifest y el directorio de catálogo que .aggrega-config.yaml nombra para ella — el Aggregate nunca cambia.