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

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

ArquivoPapel
aggregate.yamlIntenção do desenvolvedor: importa o módulo de banco de dados de documentos (core/ferretdb).
manifest-helm-synth.yamlMapeia os tipos proxy e backend para as suas Recipes helm synth.
release-helm-synth.yamlDocumento 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 provides da 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:

Terminal window
aggrega scaffold --example ferretdb-stack

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

Terminal window
cd ferretdb-stack

Build

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:

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

Os 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: apppass

Nenhuma 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: 27017
readinessProbe:
exec:
command:
- /ferretdb
- ping

O backend é renderizado como um StatefulSet com um volume persistente montado em /var/lib/postgresql/data, mais um Service ClusterIP e um Service headless.