MySQL — um Aggregate, dois destinos
Este exemplo enxuto compila uma única base de dados MySQL a partir de Aggregate escritos pelo programador em dois destinos:
- Kubernetes através da síntese de Workload do fornecedor 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 programador conduz cada destino. Só muda, de destino para destino, a camada de Recipe selecionada pelo Manifest.
Ficheiros
| Ficheiro | Papel |
|---|---|
aggregate-helm-synth.yaml | Intenção do programador 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 programador 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 respetiva 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 programador 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 fornecedor que fixa a imagem exata do contentor. |
O que demonstra
- Uma única superfície de autoria, muitos destinos. Um Aggregate é a fonte de verdade sobre o que a stack é. Cada Manifest diz como realizá-la.
- Síntese de Workload no Kubernetes (preferida). A Recipe
helm/mysqldeclara umWorkloadagnóstico em relação às capacidades comform: stateful; o fornecedor 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 contentor contémMYSQL_DATABASE,MYSQL_USER,MYSQL_ROOT_PASSWORDeMYSQL_PASSWORD. O conjunto de carateres e a collation são respeitados como argumentos de linha de comandos do servidormysqld(--character-set-server,--collation-server), porque a imagem oficialmysqlos aceita 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 fornecedor compose sintetiza um serviço emdocker-compose.yamlcom a imagem do MySQL, o seu ambiente, um volume de dados com nome e uma verificação de estado. - Uma via de escape para o operador. A release do Compose define
infra.overrides.image, o pilar aberto para os factos específicos do fornecedor que o schema próprio do Component não nomeia, e o serviço renderizado executa exatamente essa referência de imagem. Ver Substituições específicas do Provider. - Modelo de credenciais com dois slots. As palavras-passe são anexos no pilar
features:do componente, cada um uma Feature etiquetadafeature.aggrega.ai/kind: secret, mantidos separados 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 anexada coloca o valor no canal de injeção do componente, e a Recipe lê-o como .context.inject.env.MYSQL_ROOT_PASSWORD, emitindo uma variável de ambiente simples do contentor. Não é gerado nenhum Secret do Kubernetes para ele.
user_password é um slot transparente (inject: [env, file]). A variante completa anexa uma credencial referenciável, que materializa um Secret do Kubernetes e publica a sua identidade; a Recipe referencia o slot através de containers.attachments, que o sintetizador renderiza como um secretKeyRef de env. O Secret gerado e a referência do contentor nomeiam o mesmo recurso porque ambos leem .features.user_password.provides.name. Deixar user_password por anexar (a variante base) também é válido: a Recipe recorre a um valor predefinido de desenvolvimento escrito inline (MYSQL_PASSWORD: apppass) e não é gerado nenhum Secret, pelo que uma implementação mínima continua a ser renderizada e executada.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example mysql-standaloneDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd mysql-standaloneCompilação
Este workspace não contém nenhum .aggrega-config.yaml, pelo que as entidades da biblioteca standard são resolvidas a partir do registo do hub, hub.aggrega.ai, e não é necessária nenhuma flag de catálogo; --auto-pull escreve durante a compilação o lockfile que falta a um clone acabado de criar:
# 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 artefactos renderizados ficam em dist/.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta da área de trabalho ainda não contiver uma pasta `mysql-standalone`, chame uma vez a ferramenta `scaffold` com `example` definido como `mysql-standalone` e sem `dir`: esta escreve o exemplo numa nova pasta `mysql-standalone`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-helm-synth.yaml`, `release-helm-synth-auth.yaml` e `release-compose.yaml` —, de cada vez com `workspace_root` definido como `mysql-standalone`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique quais os ficheiros que cada compilação escreveu; encontram-se em `mysql-standalone/dist/`.Dimensionamento pelo operador
As releases do Kubernetes satisfazem o pilar do dimensionamento pelo operador por ambiente: a tag da imagem do contentor vem de infra.engine_version (mysql:8.4), e o pedido e a classe de armazenamento do volumeClaimTemplate vêm de infra.storage. O Aggregate do programador nunca contém estes campos.
Substituições específicas do Provider
Os pilares de dimensionamento são campos com nome: o Component declara engine_version e storage, pelo que um operador que defina qualquer um deles está a preencher um campo que o Component previu. infra.overrides é o pilar para aquilo que um Component não pode prever — é declarado como um objeto que aceita qualquer estrutura aninhada, e cada Recipe documenta as chaves que lê.
release-compose.yaml usa-o. A Recipe do Compose lê uma chave, image, e quando esta está definida o contentor executa exatamente essa referência em vez daquela 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 contém a substituição tal e qual:
services: db: image: registry.internal.example/library/mysql:8.4 [… omitted: the service's environment, labels, volume, network and health check]Este é o caminho para uma compilação da mesma versão do servidor espelhada num registo ou fixada por digest — um dado de implementaçã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 devem procurar as chaves aplicáveis: a Recipe do Compose lê aqui image, e uma Recipe que não lê nenhuma di-lo.