Stack FerretDB — um banco de dados de documentos composto como módulo
Este exemplo compila um stack pequeno e real — um banco de dados de documentos que expõe o protocolo de rede do MongoDB — para manifestos do Kubernetes sintetizados a partir de um único Aggregate escrito pelo desenvolvedor.
O banco de dados de documentos não é um único componente. É um módulo: um subagregado reutilizável que compõe dois componentes de carga de trabalho única —
- um proxy que fala o protocolo de rede do MongoDB e não mantém estado local, e
- um backend, PostgreSQL 17 com a extensão DocumentDB, que persiste os dados em um volume.
O módulo liga a sua própria aresta interna do proxy ao backend e exporta o proxy como o seu endpoint público mongo. O Aggregate de nível mais alto importa o módulo pelo nome e renderiza o stack composto; o operador dimensiona os componentes internos do módulo na Release.
Arquivos
| Arquivo | Papel |
|---|---|
aggregate.yaml | Intenção do desenvolvedor: importa o módulo de banco de dados de documentos (core/ferretdb). |
manifest-helm-synth.yaml | Mapeia os tipos proxy e backend para as suas Recipes helm synth. |
release-helm-synth.yaml | Documento do operador para o destino Kubernetes. Dimensiona os componentes internos do módulo pelos seus IDs com escopo de módulo; tudo o que fica com os valores padrão do esquema é renderizado de forma autônoma. |
O que ele demonstra
- Composição como módulo. Uma capacidade com várias cargas de trabalho — um banco de dados de documentos que na verdade é um proxy mais um backend de armazenamento — é empacotada como um subagregado que compõe dois componentes de carga de trabalho única, não como um único componente monolítico. O módulo é importado pelo nome e reutilizado onde quer que um banco de dados de documentos seja necessário.
- Uma aresta interna dentro do módulo. O proxy declara um uso do backend; o host, a porta, o usuário e o banco de dados dos
providesda Recipe do backend são canalizados para o proxy e compostos na sua conexão com o PostgreSQL. O compilador roteia as strings sem interpretá-las. - Um endpoint público. O módulo exporta o seu proxy como
mongo, o nome público estável ao qual um consumidor do banco de dados de documentos se conecta — desacoplado dos nomes dos componentes internos do módulo. - Dimensionamento dos componentes internos pelo operador. A Release endereça os componentes internos do módulo pelos seus IDs com escopo de módulo (
database.backend,database.proxy) para definir os recursos de computação, sem que o Aggregate do desenvolvedor repita o dimensionamento físico. - Uma credencial compartilhada. O proxy delega a autenticação ao seu backend PostgreSQL, então os dois compartilham uma única senha. Este exemplo usa um valor padrão de desenvolvimento compartilhado e escrito inline, então o stack é executado de forma autônoma, sem nenhum segredo externo.
- Uma string de conexão sem senha. A URL de conexão PostgreSQL do proxy é renderizada sem a senha embutida; a senha é fornecida separadamente na variável de ambiente padrão da libpq
PGPASSWORD, que o driver incorpora à conexão. Isso mantém a credencial fora da string de conexão no manifesto renderizado. - Imagens reproduzíveis. Tanto o proxy quanto o backend fixam tags de imagem explícitas, então os manifestos renderizados referenciam imagens estáveis.
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 ferretdb-stackEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd ferretdb-stackBuild
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:
aggrega build --release release-helm-synth.yaml --auto-pullOs artefatos renderizados ficam em dist/. O destino Kubernetes renderiza manifestos simples offline — nenhum pull de chart é necessário.
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 por conta própria. Se a pasta do espaço de trabalho ainda não contém uma pasta `ferretdb-stack`, chame uma vez a ferramenta `scaffold` com `example` definido como `ferretdb-stack` e sem `dir`: ela grava o exemplo em uma nova pasta `ferretdb-stack`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `ferretdb-stack`, `release` definido como `release-helm-synth.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `ferretdb-stack/dist/`.Como fica o stack composto
O proxy é renderizado como um Deployment sem estado mais um Service ClusterIP na porta do protocolo de rede. O ambiente do seu contêiner traz a conexão composta a partir da aresta para o backend — o nome do Service interno ao cluster do backend, o usuário e o banco de dados, sem senha na URL — e mantém o listener de depuração do FerretDB no endereço de loopback do pod, onde nenhum outro pod o alcança:
env: - name: FERRETDB_LISTEN_ADDR value: :27017 - name: FERRETDB_DEBUG_ADDR value: 127.0.0.1:8088 - name: FERRETDB_POSTGRESQL_URL value: postgres://postgres@database-zdbackend-default:5432/postgres - name: PGPASSWORD value: apppassNenhuma das duas probes precisa desse listener. A readiness probe executa ferretdb ping dentro do contêiner, que faz ping na porta do protocolo de rede e assim também comprova a conexão com o backend; a liveness probe verifica apenas se a porta do protocolo de rede aceita conexões, então uma indisponibilidade do backend tira o proxy do seu Service sem reiniciá-lo:
livenessProbe: tcpSocket: port: 27017readinessProbe: exec: command: - /ferretdb - pingO backend é renderizado como um StatefulSet com um volume persistente montado em /var/lib/postgresql/data, mais um Service ClusterIP e um Service headless.