MySQL — one Aggregate, two targets
This lean example compiles a single MySQL database from Developer-authored
Aggregates to two targets:
- Kubernetes via the helm provider’s Workload synthesis (a StatefulSet
rendered directly on the official
mysqlimage, no external chart), and - Docker Compose for local development.
The same developer intent drives each target. Only the Recipe layer selected by the Manifest changes per target.
Files
| File | Role |
|---|---|
aggregate-helm-synth.yaml | Developer intent for the Kubernetes base variant: one db component of type core/datastore/mysql, its values, and the required root_password credential only. |
aggregate-helm-synth-auth.yaml | Developer intent for the Kubernetes full variant: both the root_password and user_password credential slots. |
manifest-helm-synth.yaml | Maps the MySQL type to the synthesized helm Recipe (helm/mysql) and each credential to its FeatureRecipe (env-secret, k8s-secret-from-parameter). |
release-helm-synth.yaml | Operator record for the Kubernetes base variant, with operational sizing (engine_version, storage). |
release-helm-synth-auth.yaml | Operator record for the Kubernetes full variant. |
aggregate.yaml | Developer intent for the local Compose target: the same db component with both credential slots delivered as inject-value credentials. |
manifest-compose.yaml | Maps the MySQL type to the Compose Recipe (mysql) and the credential to dotenv-secret. |
release-compose.yaml | Operator record for the local Compose target, including a provider-specific infra.overrides entry that pins the exact container image. |
What it demonstrates
- One authoring surface, many targets. An Aggregate is the source of truth for what the stack is. Each Manifest says how to realize it.
- Workload synthesis on Kubernetes (preferred). The
helm/mysqlRecipe declares a capability-agnosticWorkloadwithform: stateful; the helm provider synthesizes a StatefulSet, a ClusterIP Service, a Headless Service (the StatefulSet’s stable network identity), and a volumeClaimTemplate for the data directory. The container’s environment carriesMYSQL_DATABASE,MYSQL_USER,MYSQL_ROOT_PASSWORD, andMYSQL_PASSWORD. Character set and collation are honored asmysqldserver command-line arguments (--character-set-server,--collation-server), because the officialmysqlimage takes them as server flags rather than environment variables. - Workload synthesis on Compose. The Compose Recipe declares a
capability-agnostic
Workload; the compose provider synthesizes adocker-compose.yamlservice with the MySQL image, its environment, a named data volume, and a health check. - An operator escape hatch. The Compose release sets
infra.overrides.image, the open pillar for provider-specific facts the Component’s own schema does not name, and the rendered service runs that exact image reference. See Provider-specific overrides. - Two-slot credential model. Passwords are attachments on the component’s
features:pillar, each a Feature labeledfeature.aggrega.ai/kind: secret, kept apart from applicationvalues. The Component’sfeaturesSchemadeclares a Black-Boxroot_passwordslot and a transparentuser_passwordslot.
Kubernetes credential delivery
root_password is a Black-Box slot (inject: []): the Recipe controls
delivery. The attached inject-value credential puts the value on the component’s
inject pipe, and the Recipe reads it as
.context.inject.env.MYSQL_ROOT_PASSWORD, emitting a plain container env var. No
Kubernetes Secret is generated for it.
user_password is a transparent slot (inject: [env, file]). The full
variant attaches a referenceable credential, which materializes a Kubernetes
Secret and publishes its identity; the Recipe references the slot through
containers.attachments, which the synthesizer renders as an env secretKeyRef. The
generated Secret and the container’s reference name the same resource because
both read .features.user_password.provides.name. Leaving user_password
unattached (the base variant) is also valid: the Recipe falls back to an inline
development default (MYSQL_PASSWORD: apppass) and no Secret is generated, so a
minimal deployment still renders and runs.
Scaffold the example
You can build this example with the commands below, or have your AI assistant build it for you.
Write the example into a new folder named after it:
aggrega scaffold --example mysql-standaloneIt then prints the commands to run next. The first changes into the new folder:
cd mysql-standaloneBuild
This workspace carries no .aggrega-config.yaml, so the standard-library
entities resolve from the hub registry, hub.aggrega.ai, and no catalog flag is
needed; --auto-pull writes the lockfile a fresh clone lacks during the build:
# Kubernetes — synthesized helm StatefulSet (base: root credential only)aggrega build --release release-helm-synth.yaml --auto-pull
# Kubernetes — synthesized helm StatefulSet (full: both credential slots)aggrega build --release release-helm-synth-auth.yaml --auto-pull
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pullRendered artifacts land under dist/.
With an AI assistant
An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.
Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `mysql-standalone` folder yet, call the `scaffold` tool once with `example` set to `mysql-standalone` and no `dir`: it writes the example into a new `mysql-standalone` folder. Then call the `build` tool once for each Release, in this order — `release-helm-synth.yaml`, `release-helm-synth-auth.yaml` and `release-compose.yaml` — each time with `workspace_root` set to `mysql-standalone`, `release` set to that file, `auto_pull` set to true and `write` set to true. Tell me which files each build wrote; they are under `mysql-standalone/dist/`.Operator sizing
The Kubernetes releases fulfill the operator-sizing pillar per environment: the
container image tag comes from infra.engine_version (mysql:8.4), and the
volumeClaimTemplate’s request and storage class come from infra.storage. The
developer’s Aggregate never carries these fields.
Provider-specific overrides
Sizing pillars are named fields: the Component declares engine_version and
storage, so an operator setting either is filling in a field the Component
anticipated. infra.overrides is the pillar for what a Component cannot
anticipate — it is declared as an object accepting any nested structure, and
each Recipe documents which keys it reads.
release-compose.yaml uses it. The Compose Recipe reads one key, image, and
when it is set the container runs that exact reference instead of the one the
Recipe composes from engine_version:
infra: engine_version: "8.4" overrides: image: "registry.internal.example/library/mysql:8.4"The rendered service carries the override verbatim:
services: db: image: registry.internal.example/library/mysql:8.4 [… omitted: the service's environment, labels, volume, network and health check]This is the path to a registry-mirrored or digest-pinned build of the same
server version — a deployment fact that belongs to the target environment, not
to the Component’s contract. Because the key set is per-Recipe rather than
per-Component, the Recipe is where to look for which keys apply: the Compose
Recipe here reads image, and a Recipe that reads none says so.