MySQL — um Aggregate, dois destinos
Este exemplo enxuto compila um único banco de dados MySQL a partir de Aggregate escritos pelo desenvolvedor para dois destinos:
- Kubernetes por meio da síntese de Workload do provedor helm (um StatefulSet renderizado diretamente sobre a imagem oficial
mysql, sem chart externo), e - Docker Compose para o desenvolvimento local.
A mesma intenção do desenvolvedor conduz cada destino. Só muda por destino a camada de Recipe selecionada pelo Manifest.
Arquivos
| Arquivo | Papel |
|---|---|
aggregate-helm-synth.yaml | Intenção do desenvolvedor para a variante Kubernetes base: um componente db do tipo core/datastore/mysql, os seus valores e apenas a credencial obrigatória root_password. |
aggregate-helm-synth-auth.yaml | Intenção do desenvolvedor para a variante Kubernetes completa: os dois slots de credencial, root_password e user_password. |
manifest-helm-synth.yaml | Mapeia o tipo MySQL para a Recipe helm sintetizada (helm/mysql) e cada credencial para a sua FeatureRecipe (env-secret, k8s-secret-from-parameter). |
release-helm-synth.yaml | Documento do operador para a variante Kubernetes base, com o dimensionamento operacional (engine_version, storage). |
release-helm-synth-auth.yaml | Documento do operador para a variante Kubernetes completa. |
aggregate.yaml | Intenção do desenvolvedor para o destino Compose local: o mesmo componente db com os dois slots de credencial entregues como credenciais inject-value. |
manifest-compose.yaml | Mapeia o tipo MySQL para a Recipe do Compose (mysql) e a credencial para dotenv-secret. |
release-compose.yaml | Documento do operador para o destino Compose local, incluindo uma entrada infra.overrides específica do provedor que fixa a imagem exata do contêiner. |
O que ele demonstra
- Uma única superfície de autoria, muitos destinos. Um Aggregate é a fonte da verdade sobre o que o stack é. Cada Manifest diz como realizá-lo.
- Síntese de Workload no Kubernetes (preferida). A Recipe
helm/mysqldeclara umWorkloadagnóstico em relação às capacidades comform: stateful; o provedor helm sintetiza um StatefulSet, um Service ClusterIP, um Service headless (a identidade de rede estável do StatefulSet) e um volumeClaimTemplate para o diretório de dados. O ambiente do contêiner trazMYSQL_DATABASE,MYSQL_USER,MYSQL_ROOT_PASSWORDeMYSQL_PASSWORD. O conjunto de caracteres e a collation são respeitados como argumentos de linha de comando do servidormysqld(--character-set-server,--collation-server), porque a imagem oficialmysqlos recebe como flags do servidor em vez de variáveis de ambiente. - Síntese de Workload no Compose. A Recipe do Compose declara um
Workloadagnóstico em relação às capacidades; o provedor compose sintetiza um serviço emdocker-compose.yamlcom a imagem do MySQL, o seu ambiente, um volume de dados nomeado e uma verificação de integridade. - Uma via de escape para o operador. A release do Compose define
infra.overrides.image, o pilar aberto para os fatos específicos do provedor que o schema próprio do Component não nomeia, e o serviço renderizado executa exatamente essa referência de imagem. Veja Sobrescritas específicas do Provider. - Modelo de credenciais com dois slots. As senhas são vinculações no pilar
features:do componente, cada uma uma Feature rotuladafeature.aggrega.ai/kind: secret, mantidas separadas dosvaluesda aplicação. OfeaturesSchemado Component declara um slot Black-Boxroot_passworde um slot transparenteuser_password.
Entrega de credenciais no Kubernetes
root_password é um slot Black-Box (inject: []): a Recipe controla a entrega. A credencial inject-value vinculada coloca o valor no canal de injeção do componente, e a Recipe o lê como .context.inject.env.MYSQL_ROOT_PASSWORD, emitindo uma variável de ambiente simples do contêiner. Nenhum Secret do Kubernetes é gerado para ele.
user_password é um slot transparente (inject: [env, file]). A variante completa vincula uma credencial referenciável, que materializa um Secret do Kubernetes e publica a sua identidade; a Recipe referencia o slot por meio de containers.attachments, que o sintetizador renderiza como um secretKeyRef de env. O Secret gerado e a referência do contêiner nomeiam o mesmo recurso porque ambos leem .features.user_password.provides.name. Deixar user_password sem vínculo (a variante base) também é válido: a Recipe recorre a um valor padrão de desenvolvimento escrito inline (MYSQL_PASSWORD: apppass) e nenhum Secret é gerado, então uma implantação mínima ainda é renderizada e executada.
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 mysql-standaloneEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd mysql-standaloneBuild
Este workspace não traz nenhum .aggrega-config.yaml, então as entidades da biblioteca padrão são resolvidas a partir do registro do hub, hub.aggrega.ai, e nenhuma flag de catálogo é necessária; --auto-pull escreve durante o build o lockfile que falta a um clone novo:
# 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-pullOs artefatos renderizados ficam em dist/.
Com 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 `mysql-standalone`, chame a ferramenta `scaffold` uma vez com `example` definido como `mysql-standalone` e sem `dir`: ela grava o exemplo em uma nova pasta `mysql-standalone`. Depois chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-helm-synth.yaml`, `release-helm-synth-auth.yaml` e `release-compose.yaml` —, cada vez com `workspace_root` definido como `mysql-standalone`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `mysql-standalone/dist/`.Dimensionamento pelo operador
As releases do Kubernetes preenchem o pilar do dimensionamento pelo operador por ambiente: a tag da imagem do contêiner vem de infra.engine_version (mysql:8.4), e a solicitação e a classe de armazenamento do volumeClaimTemplate vêm de infra.storage. O Aggregate do desenvolvedor nunca contém esses campos.
Sobrescritas específicas do Provider
Os pilares de dimensionamento são campos nomeados: o Component declara engine_version e storage, então um operador que define qualquer um deles está preenchendo um campo que o Component previu. infra.overrides é o pilar para o que um Component não pode prever — ele é declarado como um objeto que aceita qualquer estrutura aninhada, e cada Recipe documenta quais chaves lê.
release-compose.yaml o usa. A Recipe do Compose lê uma chave, image, e quando ela está definida o contêiner executa exatamente essa referência em vez da que a Recipe compõe a partir de engine_version:
infra: engine_version: "8.4" overrides: image: "registry.internal.example/library/mysql:8.4"O serviço renderizado traz a sobrescrita literalmente:
services: db: image: registry.internal.example/library/mysql:8.4 [… omitted: the service's environment, labels, volume, network and health check]Esse é o caminho para um build da mesma versão do servidor espelhado em um registro ou fixado por digest — um dado de implantação que pertence ao ambiente de destino, não ao contrato do Component. Como o conjunto de chaves é por Recipe e não por Component, é na Recipe que se deve procurar quais chaves se aplicam: a Recipe do Compose aqui lê image, e uma Recipe que não lê nenhuma diz isso.