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

MariaDB + Adminer — um exemplo executável com dois destinos

Este exemplo compila uma stack pequena e real — uma base de dados MariaDB com uma UI web Adminer à frente — a partir de um único Aggregate escrito pelo programador para duas plataformas:

  • Docker Compose para o desenvolvimento local, e
  • Kubernetes para um cluster local (kind / minikube / k3d), renderizado de três formas.

O mesmo Aggregate conduz ambas. Só mudam a Release, o seu Manifest e a camada de Recipe carregada em tempo de compilação. Todos os ficheiros aqui compilam com a CLI aggrega publicada, e o resultado renderizado funciona: é possível arrancar a stack, abrir o Adminer num navegador e iniciar sessão na base de dados em execução.

aggregate.yaml

escrito uma vez

Num portátil

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

Num cluster Kubernetes

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

Manifestos Kubernetes

Cada plataforma é compilada a partir da sua própria Release e do seu próprio Manifest. O Aggregate, que descreve a sua aplicação, mantém-se igual.

O que demonstra

  • Uma única superfície de autoria, muitos destinos. Um único aggregate.yaml é a fonte de verdade sobre o que a stack é. Cada destino é uma camada fina de catálogo que diz como realizá-la.
  • O String Pipe. O Adminer declara um uso databases do MariaDB; o provides.host da Recipe da base de dados é encaminhado para a variável de ambiente ADMINER_DEFAULT_SERVER do Adminer. O compilador encaminha a string sem a interpretar — assim, a compilação para compose liga um nome de serviço do compose e a compilação para Kubernetes liga um nome DNS de Service, a partir da mesma aresta.
  • Síntese de Workload. As Recipes para compose e para Kubernetes autónomo declaram um Workload agnóstico em relação às capacidades; o fornecedor 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 a base de dados form: stateful, um StatefulSet cujo modelo de claim de volume por réplica contém o diretório de dados, ao lado do Service headless que o governa e do Service ClusterIP que os consumidores contactam.
  • O subsistema de credenciais. As palavras-passe da base de dados são anexadas no pilar features: do componente — cada uma uma Feature com a etiqueta feature.aggrega.ai/kind: secret, mantida à parte dos values da aplicação. O featuresSchema do Component declara dois tipos de slot, e o exemplo exercita ambos: um slot de caixa negra cuja FeatureRecipe entrega o valor internamente, e um slot transparente cujo valor o programador entrega explicitamente com um bloco inject: no anexo.
  • Origens de chart remotas. O destino Kubernetes gerido obtém o chart upstream do MariaDB da Bitnami por referência OCI. aggrega pull fixa o chart num ficheiro de bloqueio e transfere-o para uma cache endereçada por conteúdo; aggrega build renderiza a partir dessa cache, pelo que o momento do bloqueio e o da compilação resolvem o mesmo chart. A versão do chart provém do infra.source_version do operador quando a Release fixa uma, e caso contrário de um valor escrito pelo programador (um valor que flui para a resolução da origem). Os ficheiros de bloqueio por release fixam as identidades e os digests das entidades: depois de entidades do catálogo serem renomeadas ou de o seu conteúdo mudar, é necessário atualizar um ficheiro 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, pelo que não é necessário nenhum --catalog num terminal, num editor ou através de um assistente.
  • Proveniência como anotações. Cada objeto do Kubernetes renderizado contém uma anotação aggrega.ai/recipe-uri que regista a Recipe que o produziu — uma anotação, e não uma etiqueta, porque o valor URI contém caracteres que o valor de uma etiqueta 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 fornecedor 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 encaminha os valores mapeados de cada componente — incluindo o host da base de dados encaminhado — 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, retirada de qualquer camada de catálogo que a compilação carregue.

Autoria e consumo — um espaço de trabalho misto

Este exemplo trabalha as duas pontas do catálogo ao mesmo tempo: escreve algumas entidades localmente e consome outras da biblioteca standard do Aggrega. O Component de base de dados MariaDB, as suas Features de credencial e as Recipes por destino são construídos de raiz nos diretórios locais catalog-*/ — um único Aggregate renderiza essa base de dados escrita localmente em quatro destinos. A UI web Adminer, pelo contrário, é 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 da base de dados ao lado do consumo do catálogo no lado da UI. As entidades que aqui se constroem são do mesmo tipo que as publicadas na biblioteca standard: um Component de base de dados, Features de credencial, Recipes de fornecedor.

O exemplo catalog-only situa-se na ponta do consumo puro do mesmo percurso: monta esta mesma stack — uma base de dados MariaDB com uma UI Adminer — referenciando entidades da biblioteca standard, sem escrever nenhuma própria. Para aprender como as entidades do catálogo são construídas, leia o lado da base de dados deste exemplo; para aprender como uma stack inteira é usada a partir do catálogo publicado, leia os exemplos de consumo.

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:

Terminal window
aggrega scaffold --example mariadb-adminer

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd mariadb-adminer

Compilação

Cada destino é uma Release, compilada uma por execução; o pull escreve o lockfile que o build lê. Primeiro o Docker Compose — a secção de cada destino, mais abaixo, indica 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-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 `mariadb-adminer`, chame uma vez a ferramenta `scaffold` com `example` definido como `mariadb-adminer` e sem `dir`: esta escreve o exemplo numa nova pasta `mariadb-adminer`. Em seguida, 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. Indique quais os ficheiros que a compilação escreveu; encontram-se 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-* contém 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 — é resolvido a partir da biblioteca standard. Uma compilação carrega uma camada catalog-* sobre essa biblioteca standard, 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 é indicado para ela em .aggrega-config.yaml.

O Aggregate partilhado

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 da base de dados à variável de ambiente ADMINER_DEFAULT_SERVER no contentor do Adminer. Nada no Aggregate nomeia um fornecedor; essa escolha reside inteiramente na camada de catálogo que a compilação carrega.

Uma nota sobre as credenciais

A imagem do MariaDB precisa de uma palavra-passe de root para arrancar, e o utilizador da aplicação precisa da sua própria. Ambas são anexadas no pilar features: do componente de base de dados — mantidas à parte dos values da aplicação — como Features com a etiqueta 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 negra (inject: []): a FeatureRecipe entrega o valor no canal do componente. O programador não dita — nem pode ditar — como.
  • user_password é um slot transparente (inject: [env, file]): a credencial expõe o seu valor, e o programador mapeia-o para uma variável de ambiente com o bloco inject: no anexo.

Os valores aqui são literais inline para que a stack seja executada com um único comando — adequado para desenvolvimento local e demonstrações. Para ambientes partilhados ou de produção, os mesmos anexos 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 a compilação — o pull escreve release-compose.lock, que a compilação lê:

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

Resultado: dist/app/compose/docker-compose.yaml — dois serviços numa única rede. db executa mariadb:11.4 com a base de dados, o utilizador, o charset e as palavras-passe injetadas; web executa adminer:4, publica a porta 8080, depende de db e contém ADMINER_DEFAULT_SERVER: db (o nome de serviço do compose que a Recipe da base de dados emitiu).

Executá-lo:

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

Abra http://localhost:8080 e inicie sessão:

CampoValor
SistemaMySQL / MariaDB
Servidordb (já preenchido)
Nome de utilizadorappuser
Palavra-passedev-app-pw-change-me
Base de dadosappdb

(ou root / dev-root-pw-change-me). Para desmontar, execute 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 — uma única compilação offline.

O Workload da base de dados declara form: stateful, pelo que sintetiza um StatefulSet cujo diretório de dados é um template de volume claim por réplica em vez de um Deployment que partilha 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, pelo que o seu Workload deixa form no valor predefinido e continua a ser 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

Resultado 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

Repare em ADMINER_DEFAULT_SERVER: db-default — para Kubernetes, a Recipe da base de dados emite o nome DNS do Service interno ao cluster, pelo que a mesma aresta do Aggregate se resolve num endereço encaminhá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 inicie sessão com Server db-default, nome de utilizador appuser, palavra-passe dev-app-pw-change-me e base de dados appdb. Para o remover, execute kubectl delete -f dist/app/helm/.


Destino 3 — Kubernetes (chart Bitnami gerido)

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 programador. Fixar a versão do chart é uma questão de infraestrutura, pelo que a fixação do operador prevalece sempre que uma Release define uma; esta Release deliberadamente não define nenhuma, pelo que a chave .values é a versão que efetivamente se resolve — o que é precisamente o objetivo deste destino, porque um valor do programador que chega à resolução da origem só é observável na saída renderizada enquanto a fixação operacional estiver ausente. Fixe source_version no componente db em release-helm-bitnami.yaml e a etiqueta helm.sh/chart renderizada 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 programador em vez de se resolver numa versão vazia — consulte optional para a semântica da verificação de presença.

Compilar este destino é um fluxo em dois passos: aggrega pull resolve o chart, fixa-o em release-helm-bitnami.lock e obtém-no para a cache de compilação endereçada por conteúdo (o único passo online); aggrega build renderiza depois a partir da cache, pelo que o momento do bloqueio e o da compilação resolvem o mesmo chart. As credenciais injetadas fluem para os valores auth do chart, e o chart gera o Secret do Kubernetes que a base de dados lê. O Adminer é renderizado pela mesma Recipe sintetizada do Destino 2 e liga-se ao Service primário do chart (db-mariadb). Os dois destinos autónomos acima são a forma sem dependências de executar a stack de ponta a ponta.


Destino 4 — Kubernetes (chart Helm composto)

A quarta camada implementa os mesmos componentes sobre o fornecedor 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" }

Compilá-lo:

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

Resultado 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/, pelo que não é necessário um helm dependency build antes):

Terminal window
helm install mariadb-adminer dist/app/helm-chart/

O values.yaml do chart guarda-chuva já contém os valores resolvidos de cada componente, pelo que a base de dados arranca com as suas credenciais e o Adminer fica ligado ao Service do MariaDB — a mesma ligação que os outros destinos exprimem, agora entregue como um chart que é possível instalar ou incluir no próprio projeto.

Aplicam-se dois regimes de delimitadores distintos, e não se sobrepõem:

  • Os subcharts com origem são copiados, exceto o seu próprio nome. Os ficheiros 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 resolvem-se no momento do helm install. A única tarefa do compositor aí é a montagem, não o templating. O único campo que define é o name de cada Chart.yaml colocado, que se torna a identidade da instância do componente (db, web), para que dois componentes que incluem charts que declaram um mesmo nome continuem distinguíveis; consulte providers/helm-chart.md.
  • Os artefactos $import: usam dois delimitadores. Uma Recipe pode injetar ficheiros de template adicionais através de artifacts: { name: { $import: ... } }. Esses ficheiros — e apenas esses — são pré-renderizados pelo compilador com os delimitadores [[ ]] antes de serem colocados, enquanto o seu {{ }} é preservado para o Helm. O artefacto netpol.yaml — com a chave netpol.yaml e importado de ./extras/mariadb-netpol.yaml, uma vez que a chave nomeia o ficheiro emitido e a importação seleciona o seu conteúdo — mostra a mistura: [[ .context.instance_id ]] (preenchido na compilação) e {{ .Release.Namespace }} (deixado para a instalação).

O String Pipe exprime-se em termos de chart: o uso databases do MariaDB pelo Adminer resolve o provides.host da Recipe da base 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, pelo que 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 é selecionado um destino

A seleção da Recipe faz-se 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, pelo que 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 a compilação, nomeando as Recipes que o implementam, mesmo quando a camada carregada contém apenas uma. O fornecedor que renderiza um nó é o spec.capability da Recipe que tiver sido associada. Mudar de destino é mudar a Release, com o seu Manifest e o diretório de catálogo que .aggrega-config.yaml nomeia para ela — o Aggregate nunca muda.