MariaDB + Adminer — um exemplo executável com dois destinos
Este exemplo compila um stack pequeno e real — um banco de dados MariaDB com uma UI web Adminer na frente — a partir de um único Aggregate escrito pelo desenvolvedor para duas plataformas:
- Docker Compose para o desenvolvimento local, e
- Kubernetes para um cluster local (kind / minikube / k3d), renderizado de três maneiras.
O mesmo Aggregate conduz ambas. Só mudam a Release, o seu Manifest e a camada de Recipe carregada em tempo de build. Todos os arquivos aqui compilam com a CLI aggrega publicada, e a saída renderizada funciona: suba o stack, abra o Adminer em um navegador e faça login no banco de dados em execução.
aggregate.yamlescrito uma vez
Em um laptop
release-compose.yamlmanifest-compose.yamlaggrega builddocker-compose.yamlEm um cluster Kubernetes
release-helm-synth.yamlmanifest-helm-synth.yamlaggrega buildManifestos Kubernetes
Cada plataforma é compilada a partir de sua própria Release e de seu próprio Manifest. O Aggregate, que descreve sua aplicação, continua o mesmo.
O que ele demonstra
- Uma única superfície de autoria, muitos destinos. Um único
aggregate.yamlé a fonte da verdade sobre o que o stack é. Cada destino é uma camada fina de catálogo que diz como realizá-lo. - O String Pipe. O Adminer declara um uso
databasesdo MariaDB; oprovides.hostda Recipe do banco de dados é canalizado para a variável de ambienteADMINER_DEFAULT_SERVERdo Adminer. O compilador roteia a string sem interpretá-la — assim, o build do compose liga um nome de serviço do compose e o build do Kubernetes liga um nome DNS de Service, a partir da mesma aresta. - Síntese de Workload. As Recipes do compose e do Kubernetes autônomo declaram um
Workloadagnóstico em relação às capacidades; o provedor sintetiza um serviço dodocker-compose.yaml, ou os objetos do Kubernetes que oformdo Workload pede — umDeploymente umServicepara a UI web sem estado e, para o banco de dadosform: stateful, umStatefulSetcujo template de claim de volume por réplica traz o diretório de dados, ao lado doServiceheadless que o governa e doServiceClusterIPque os consumidores chamam. - O subsistema de credenciais. As senhas do banco de dados são vinculadas no pilar
features:do componente — cada uma umaFeaturerotuladafeature.aggrega.ai/kind: secret, mantida separada dosvaluesda aplicação. OfeaturesSchemado Component declara dois tipos de slot, e o exemplo exercita ambos: um slot de caixa preta cuja FeatureRecipe entrega o valor internamente, e um slot transparente cujo valor o desenvolvedor entrega explicitamente com um blocoinject:na vinculação. - Fontes de chart remotas. O destino Kubernetes gerenciado obtém o chart upstream do MariaDB da Bitnami por referência OCI.
aggrega pullfixa o chart em um arquivo de bloqueio e o baixa para um cache endereçado por conteúdo;aggrega buildrenderiza a partir desse cache, então o momento do bloqueio e o do build resolvem o mesmo chart. A versão do chart vem doinfra.source_versiondo operador quando a Release fixa uma, e caso contrário de um valor escrito pelo desenvolvedor (um valor que flui para a resolução da origem). Os arquivos de bloqueio por release fixam as identidades e os digests das entidades: depois que entidades do catálogo forem renomeadas ou o seu conteúdo mudar, atualize um arquivo de bloqueio local desatualizado comaggrega pull --release release-<variant>.yaml. Cada variante de release é resolvida em relação ao seu próprio diretório de catálogo irmão, que.aggrega-config.yamlnomeia para ela emworkspace.releases, então nenhum--catalogé necessário em um terminal, em um editor ou por meio de um assistente. - Proveniência como anotações. Todo objeto do Kubernetes renderizado traz uma anotação
aggrega.ai/recipe-urique registra a Recipe que o produziu — uma anotação, não um rótulo, porque o valor URI contém caracteres que o valor de um rótulo do Kubernetes não pode conter. - Composição de chart (em vez de síntese). O mesmo Aggregate pode produzir um chart Helm redistribuível em vez de manifestos renderizados. O provedor
helm-chartcompõe um chart guarda-chuva: o subchart local de cada componente é copiado literalmente (com os seus{{ }}do Helm preservados intactos), e ovalues.yamldo chart guarda-chuva roteia os valores mapeados de cada componente — incluindo o host do banco de dados canalizado — sob o alias desse componente. - Seleção do Provider por tipo de componente. A Recipe que renderiza cada componente é aquela para a qual o Manifest do destino mapeia o tipo do componente, extraída de qualquer camada de catálogo que o build carregue.
Autoria e consumo — um espaço de trabalho misto
Este exemplo trabalha as duas pontas do catálogo ao mesmo tempo: ele escreve algumas entidades localmente e consome outras da biblioteca padrão do Aggrega. O Component de banco de dados MariaDB, as suas Features de credencial e as Recipes por destino são construídos do zero nos diretórios locais catalog-*/ — um único Aggregate renderiza esse banco de dados escrito localmente em quatro destinos. A UI web Adminer, por outro lado, é consumida: o componente web referencia diretamente o Component publicado core/devtool/adminer, e cada destino escreve apenas uma Recipe local que o implementa. O mesmo espaço de trabalho mostra, portanto, a autoria de entidades no lado do banco de dados ao lado do consumo do catálogo no lado da UI. As entidades que você constrói aqui são do mesmo tipo que as publicadas na biblioteca padrão: um Component de banco de dados, Features de credencial, Recipes de provedor.
O exemplo catalog-only fica na ponta do consumo puro do mesmo percurso: ele monta este mesmo stack — um banco de dados MariaDB com uma UI Adminer — referenciando entidades da biblioteca padrão, sem escrever nenhuma própria. Leia o lado do banco de dados deste exemplo para aprender como as entidades do catálogo são construídas; leia os exemplos de consumo para aprender como um stack inteiro é usado a partir do catálogo publicado.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example mariadb-adminerEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd mariadb-adminerBuild
Cada destino é uma Release, compilada uma por execução; o pull escreve o lockfile que o build lê. Docker Compose primeiro — a seção de cada destino abaixo dá os seus próprios comandos:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlCom um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use somente as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `mariadb-adminer`, chame a ferramenta `scaffold` uma vez com `example` definido como `mariadb-adminer` e sem `dir`: ela grava o exemplo em uma nova pasta `mariadb-adminer`. Depois chame a ferramenta `build` com `workspace_root` definido como `mariadb-adminer`, `release` definido como `release-compose.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `mariadb-adminer/dist/`.Estrutura
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 diretório catalog-* traz as definições do Component MariaDB e da Feature escritas localmente, mais as Recipes para esse único destino. O Component Adminer não está entre elas — ele é resolvido a partir da biblioteca padrão. Um build carrega uma camada catalog-* sobre essa biblioteca padrão, e o Manifest do destino mapeia cada tipo de componente para uma Recipe dessa camada.
A Release, o seu aggregate: e o seu manifest: são irmãos neste diretório; o diretório de catálogo com base no qual cada Release é compilada é nomeado para ela em .aggrega-config.yaml.
O Aggregate compartilhado
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 um uso databases de db. O bloco inject associa o provides.host da Recipe do banco de dados à variável de ambiente ADMINER_DEFAULT_SERVER no contêiner do Adminer. Nada no Aggregate nomeia um provedor; essa escolha fica inteiramente na camada de catálogo que o build carrega.
Uma nota sobre as credenciais
A imagem do MariaDB precisa de uma senha de root para iniciar, e o usuário da aplicação precisa da sua própria. Ambas são vinculadas no pilar features: do componente de banco de dados — mantidas separadas dos values da aplicação — como Features rotuladas feature.aggrega.ai/kind: secret. O featuresSchema do Component core/datastore/mariadb declara um slot para cada uma, e o exemplo exercita os dois modelos de entrega:
root_passwordé um slot de caixa preta (inject: []): a FeatureRecipe entrega o valor no canal do componente. O desenvolvedor não dita — e não pode ditar — como.user_passwordé um slot transparente (inject: [env, file]): a credencial expõe o seu valor, e o desenvolvedor o mapeia para uma variável de ambiente com o blocoinject:na vinculação.
Os valores aqui são literais inline para que o stack seja executado com um único comando — adequado para desenvolvimento local e demonstrações. Para ambientes compartilhados ou de produção, as mesmas vinculações resolvem os seus valores a partir de um repositório de segredos: o catálogo do destino carrega uma FeatureRecipe que os obtém, e o Aggregate não muda.
Destino 1 — Docker Compose
Primeiro o pull, depois o build — o pull escreve release-compose.lock, que o build lê:
aggrega pull --release release-compose.yamlaggrega build --release release-compose.yamlSaída: dist/app/compose/docker-compose.yaml — dois serviços em uma rede. db executa mariadb:11.4 com o banco de dados, o usuário, o charset e as senhas injetadas; web executa adminer:4, publica a porta 8080, depende de db e traz ADMINER_DEFAULT_SERVER: db (o nome de serviço do compose que a Recipe do banco de dados emitiu).
Executá-lo:
docker compose -f dist/app/compose/docker-compose.yaml up -dAbra http://localhost:8080 e faça login:
| Campo | Valor |
|---|---|
| Sistema | MySQL / MariaDB |
| Servidor | db (já preenchido) |
| Nome de usuário | appuser |
| Senha | dev-app-pw-change-me |
| Banco de dados | appdb |
(ou root / dev-root-pw-change-me). Para desmontar, use docker compose -f dist/app/compose/docker-compose.yaml down -v.
Destino 2 — Kubernetes (autônomo)
Este destino renderiza manifestos Kubernetes simples diretamente a partir do Workload, sem chart externo — um único build offline.
O Workload do banco de dados declara form: stateful, então sintetiza um StatefulSet cujo diretório de dados é um template de volume claim por réplica em vez de um Deployment que compartilha um único claim. Dois acompanhantes vêm com essa forma: o volume é declarado como persistentTemplate, e um Service headless fornece a identidade DNS estável por pod que o StatefulSet nomeia como o seu serviço de governo. O Adminer não mantém estado, então o seu Workload deixa form no valor padrão e continua sendo um Deployment — a persistência é uma propriedade do Workload, não um componente diferente.
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yamlSaída em 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 8080Observe ADMINER_DEFAULT_SERVER: db-default — para Kubernetes, a Recipe do banco de dados emite o nome DNS do Service interno ao cluster, então a mesma aresta do Aggregate se resolve em um endereço roteável neste destino.
Aplicá-lo e abri-lo:
kubectl apply -f dist/app/helm/kubectl rollout status statefulset/dbkubectl port-forward svc/web-default 8080:8080Abra http://localhost:8080 e faça login com Server db-default, nome de usuário appuser, senha dev-app-pw-change-me e banco de dados appdb. Para removê-lo, use kubectl delete -f dist/app/helm/.
Destino 3 — Kubernetes (chart Bitnami gerenciado)
A terceira camada implementa o mesmo Component core/datastore/mariadb sobre o chart Helm do MariaDB da Bitnami de upstream em vez de sintetizar manifestos. A Recipe obtém o chart por referência OCI e mapeia os valores do Component para o esquema de valores do 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 …O source.version da Recipe prefere o infra.source_version do operador e recorre ao .values.chart_version escrito pelo desenvolvedor. Fixar a versão do chart é uma questão de infraestrutura, então a fixação do operador prevalece onde quer que uma Release defina uma; esta Release deliberadamente não define nenhuma, então a chave .values é a versão que de fato se resolve — que é justamente o objetivo deste destino, porque um valor do desenvolvedor que chega à resolução da origem só é observável na saída renderizada enquanto a fixação operacional está ausente. Fixe source_version no componente db em release-helm-bitnami.yaml e o rótulo helm.sh/chart renderizado passa a seguir essa versão.
optional lê a fixação pelo nome em vez de como um caminho com pontos, o que permite que uma fixação ausente recaia no valor do desenvolvedor em vez de se resolver em uma versão vazia — veja optional para a semântica da verificação de presença.
Fazer o build deste destino é um fluxo em duas etapas: aggrega pull resolve o chart, fixa-o em release-helm-bitnami.lock e o busca para o cache de build endereçado por conteúdo (a única etapa online); aggrega build então renderiza a partir do cache, de modo que o momento do lock e o do build resolvem o mesmo chart. As credenciais injetadas fluem para os valores auth do chart, e o chart gera o Secret do Kubernetes que o banco de dados lê. O Adminer é renderizado pela mesma Recipe sintetizada do Destino 2 e se conecta ao Service primário do chart (db-mariadb). Os dois destinos autônomos acima são a forma sem dependências de executar o stack de ponta a ponta.
Destino 4 — Kubernetes (chart Helm composto)
A quarta camada implementa os mesmos componentes sobre o provedor helm-chart, que compõe um chart guarda-chuva Helm redistribuível em vez de renderizar manifestos (Destino 2) ou renderizar um chart de upstream (Destino 3). Cada Recipe obtém um pequeno 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" }Fazer o build:
aggrega pull --release release-helm-chart.yamlaggrega build --release release-helm-chart.yamlSaída em 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]Instalá-lo (os subcharts estão incluídos em charts/, então nenhum helm dependency build é necessário antes):
helm install mariadb-adminer dist/app/helm-chart/O values.yaml do chart guarda-chuva já traz os valores resolvidos de cada componente, então o banco de dados inicia com as suas credenciais e o Adminer fica conectado ao Service do MariaDB — a mesma conexão que os outros destinos expressam, agora entregue como um chart que você pode instalar ou incluir no seu projeto.
Aplicam-se dois regimes de delimitadores distintos, e eles não se sobrepõem:
- Subcharts com origem são copiados, exceto o seu próprio nome. Os arquivos em
./charts/mariadbe./charts/adminersão empacotados no chart guarda-chuva sem alterações — as suas diretivas Helm{{ }}não são tocadas pelo compilador e se resolvem no momento dohelm install. A única tarefa do compositor ali é a montagem, não o templating. O único campo que ele define é onamede cadaChart.yamlcolocado, que se torna a identidade da instância do componente (db,web), de modo que dois componentes que incluem charts declarando um mesmo nome continuem distinguíveis; vejaproviders/helm-chart.md. - Artefatos
$import:usam dois delimitadores. Uma Recipe pode injetar arquivos de template extras viaartifacts: { name: { $import: ... } }. Esses arquivos — e somente esses — são pré-renderizados pelo compilador com os delimitadores[[ ]]antes de serem colocados, enquanto o seu{{ }}é preservado para o Helm. O artefatonetpol.yaml— com a chavenetpol.yamle importado de./extras/mariadb-netpol.yaml, já que a chave nomeia o arquivo emitido e a importação seleciona o seu conteúdo — mostra a mistura:[[ .context.instance_id ]](preenchido no build) e{{ .Release.Namespace }}(deixado para a instalação).
O String Pipe se expressa em termos de chart: o uso databases do MariaDB pelo Adminer resolve o provides.host da Recipe do banco de dados no values.yaml do chart guarda-chuva sob o alias web (adminerDefaultServer: db-mariadb), que o subchart do Adminer lê como {{ .Values.adminerDefaultServer }}. O mesmo valor nomeia o Service do subchart do MariaDB, então a ligação se resolve de forma consistente na instalação. A saída é um chart para helm install ou para incluir — não um conjunto de manifestos aplicados.
Como um destino é selecionado
A seleção da Recipe é feita por tipo de componente: o Manifest de cada destino mapeia cada tipo para uma Recipe na camada de catálogo que a sua Release carrega, então manifest-compose.yaml associa core/datastore/mariadb à Recipe compose, enquanto manifest-helm-synth.yaml o associa à de Kubernetes. Um tipo que o Manifest não mapeia interrompe o build, nomeando as Recipes que o implementam, mesmo quando a camada carregada contém apenas uma. O provedor que renderiza um nó é o spec.capability da Recipe que foi associada. Trocar de destino é trocar a Release, com o seu Manifest e o diretório de catálogo que .aggrega-config.yaml nomeia para ela — o Aggregate nunca muda.