Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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

escrito uma vez

Em um laptop

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

Em um cluster Kubernetes

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

Manifestos 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 databases do MariaDB; o provides.host da Recipe do banco de dados é canalizado para a variável de ambiente ADMINER_DEFAULT_SERVER do 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 Workload agnóstico em relação às capacidades; o provedor sintetiza um serviço do docker-compose.yaml, ou os objetos do Kubernetes que o form do Workload pede — um Deployment e um Service para a UI web sem estado e, para o banco de dados form: stateful, um StatefulSet cujo template de claim de volume por réplica traz o diretório de dados, ao lado do Service headless que o governa e do Service ClusterIP que os consumidores chamam.
  • O subsistema de credenciais. As senhas do banco de dados são vinculadas no pilar features: do componente — cada uma uma Feature rotulada feature.aggrega.ai/kind: secret, mantida separada dos values da aplicação. O featuresSchema do 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 bloco inject: 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 pull fixa o chart em um arquivo de bloqueio e o baixa para um cache endereçado por conteúdo; aggrega build renderiza a partir desse cache, então o momento do bloqueio e o do build resolvem o mesmo chart. A versão do chart vem do infra.source_version do 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 com aggrega 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.yaml nomeia para ela em workspace.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-uri que 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-chart compõe um chart guarda-chuva: o subchart local de cada componente é copiado literalmente (com os seus {{ }} do Helm preservados intactos), e o values.yaml do 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:

Terminal window
aggrega scaffold --example mariadb-adminer

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd mariadb-adminer

Build

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:

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

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

web 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 bloco inject: 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ê:

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

Saí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:

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

Abra http://localhost:8080 e faça login:

CampoValor
SistemaMySQL / MariaDB
Servidordb (já preenchido)
Nome de usuárioappuser
Senhadev-app-pw-change-me
Banco de dadosappdb

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

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

Saída em 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

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

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

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

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

Saída em 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]

Instalá-lo (os subcharts estão incluídos em charts/, então nenhum helm dependency build é necessário antes):

Terminal window
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/mariadb e ./charts/adminer sã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 do helm install. A única tarefa do compositor ali é a montagem, não o templating. O único campo que ele define é o name de cada Chart.yaml colocado, 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; veja providers/helm-chart.md.
  • Artefatos $import: usam dois delimitadores. Uma Recipe pode injetar arquivos de template extras via artifacts: { 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 artefato netpol.yaml — com a chave netpol.yaml e 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.