Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

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

escrito una sola vez

En un portátil

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

En un clúster de Kubernetes

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

Manifiestos 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.yaml es 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 databases de MariaDB; el provides.host de la Recipe de la base de datos se canaliza a la variable de entorno ADMINER_DEFAULT_SERVER de 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 Workload agnóstico respecto a las capacidades; el proveedor sintetiza un servicio de docker-compose.yaml, o los objetos de Kubernetes que pide el form del Workload — un Deployment y un Service para la UI web sin estado, y para la base de datos form: stateful un StatefulSet cuya plantilla de reclamación de volumen por réplica lleva el directorio de datos, junto al Service headless que lo gobierna y al Service ClusterIP al 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 una Feature etiquetada feature.aggrega.ai/kind: secret, separada de los values de la aplicación. El featuresSchema del 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 bloque inject: 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 pull fija el chart en un archivo de bloqueo y lo descarga en una caché direccionada por contenido; aggrega build renderiza 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 del infra.source_version del 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 con aggrega pull --release release-<variant>.yaml. Cada variante de release se resuelve contra su propio directorio de catálogo hermano, que .aggrega-config.yaml nombra para ella bajo workspace.releases, así que no se necesita ningún --catalog en 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-uri que 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-chart compone un chart paraguas: el subchart local de cada componente se copia tal cual (con sus {{ }} de Helm intactos), y el values.yaml del 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:

Terminal window
aggrega scaffold --example mariadb-adminer

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd mariadb-adminer

Compilació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:

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

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

web 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_password es 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_password es un slot transparente (inject: [env, file]): la credencial expone su valor, y el desarrollador lo asigna a una variable de entorno con el bloque inject: 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:

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

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

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

Abre http://localhost:8080 e inicia sesión:

CampoValor
SistemaMySQL / MariaDB
Servidordb (ya rellenado)
Nombre de usuarioappuser
Contraseñadev-app-pw-change-me
Base de datosappdb

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

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

Salida en 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

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

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

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

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

Salida en 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]

Instalarlo (los subcharts están incluidos en charts/, así que no hace falta un helm dependency build antes):

Terminal window
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/mariadb y ./charts/adminer se empaquetan en el chart paraguas sin cambios — el compilador no toca sus directivas Helm {{ }}, que se resuelven en el momento de helm install. La única tarea del compositor ahí es el ensamblaje, no el templating. El único campo que sí establece es el name de cada Chart.yaml colocado, 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; consulta providers/helm-chart.md.
  • Los artefactos $import: usan dos delimitadores. Una Recipe puede inyectar archivos de plantilla adicionales mediante artifacts: { 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 artefacto netpol.yaml — con clave netpol.yaml e 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.