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

Scripts de bootstrap e configuração personalizada do PostgreSQL — helm sintetizado

core/datastore/postgres expõe dois valores opcionais do desenvolvedor que determinam a primeira inicialização do banco de dados: init_scripts (SQL ou shell executado uma vez na inicialização) e custom_config (um fragmento de postgresql.conf). No destino helm sintetizado, a Recipe os leva para o contêiner como ConfigMaps montados. Este exemplo mostra que a funcionalidade é aditiva: um Aggregate que não define nenhum dos dois valores é renderizado exatamente como um banco de dados mínimo, e um Aggregate que os define ganha os ConfigMaps, os volumes e as montagens sem que nada mais seja alterado.

Duas Releases do mesmo Component, com o mesmo Manifest, que diferem apenas nos valores do desenvolvedor:

  • release-bare.yaml (aggregate-bare.yaml) — init_scripts e custom_config não definidos.
  • release-config.yaml (aggregate-config.yaml) — ambos definidos.

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 postgres-init-config

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

Terminal window
cd postgres-init-config

Build

Terminal window
aggrega build --release release-bare.yaml --auto-pull
aggrega build --release release-config.yaml --auto-pull

O catálogo se resolve a partir do registry do hub nomeado em .aggrega-config.yaml, então nenhum flag --catalog é necessário, e --auto-pull grava durante o build o arquivo de bloqueio que falta a um clone recém-criado. A release básica grava três arquivos em dist/helm/helm/; a release configurada grava esses três mais outros dois em dist/helm/helm/db/.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta Workspace ainda não contiver uma pasta `postgres-init-config`, chame uma vez a ferramenta `scaffold` com `example` definido como `postgres-init-config` e sem `dir`: ela grava o exemplo em uma nova pasta `postgres-init-config`. Em seguida, chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-bare.yaml` e `release-config.yaml` — cada vez com `workspace_root` definido como `postgres-init-config`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `postgres-init-config/dist/`.

Básica — a linha de base aditiva

aggregate-bare.yaml deixa os dois valores sem definir. A saída renderizada é um StatefulSet, um Service ClusterIP e um Service headless — nenhum ConfigMap, nenhum volume configmap, nenhuma montagem de volume no diretório de inicialização e nenhum argumento de arquivo de configuração no contêiner. Essa é a forma comum de um banco de dados PostgreSQL mínimo:

dist/helm/helm/db-statefulset.yaml
dist/helm/helm/db-default-service.yaml
dist/helm/helm/db-headless-service.yaml

Como os dois valores são protegidos por uma verificação de presença na Recipe, um valor não definido não emite nada — o corpo do ConfigMap é renderizado vazio e ignorado, e as linhas do volume, da montagem e do argumento do servidor são excluídas pela verificação. Um Aggregate que nunca toca nesses valores não é alterado pela existência deles.

Configurada — scripts e configuração montados

aggregate-config.yaml define os dois valores:

values:
init_scripts:
01-schema.sql: |
CREATE TABLE app_users ( ... );
02-seed.sql: |
INSERT INTO app_users (email) VALUES ('founder@example.com');
custom_config: |
max_connections = 200
shared_buffers = 256MB

Agora o build grava dois ConfigMaps adicionais e os conecta ao StatefulSet:

dist/helm/helm/db/initdb-configmap.yaml
dist/helm/helm/db/config-configmap.yaml

Ambos ficam em db/, o nome próprio do componente. A Recipe os nomeia no seu bloco artifacts:, e um arquivo nomeado ali traz a chave que o seu autor escreveu em vez de algo que identifique o componente — então o build o grava sob o componente que o declarou, e dois componentes que compartilham uma Recipe não podem cair no mesmo caminho. O StatefulSet e os dois Services recebem o nome do destino a partir do componente a que pertencem, então permanecem no diretório próprio da fronteira.

Os dois valores viajam em ConfigMaps separados porque cada um é montado inteiro em um caminho diferente do contêiner:

  • init_scripts → ConfigMap db-initdb, uma chave de dados por script (01-schema.sql, 02-seed.sql). Um volume configmap o monta em /docker-entrypoint-initdb.d, onde o PostgreSQL executa os arquivos uma vez na primeira inicialização, em ordem alfabética de chave.
  • custom_config → ConfigMap db-config, uma chave de dados postgresql.conf. Um segundo volume configmap o monta em /etc/postgresql, e os args: do contêiner apontam o servidor para ele: postgres -c config_file=/etc/postgresql/postgresql.conf. As configurações que o fragmento omite mantêm os seus valores padrão embutidos.
# db-statefulset.yaml (container)
containers:
- name: main
image: postgres:16
args:
- postgres
- -c
- config_file=/etc/postgresql/postgresql.conf
[… omitted: the container's port, environment and resources]
volumeMounts:
- name: data
mountPath: /var/lib/postgresql/data
- name: initdb
mountPath: /docker-entrypoint-initdb.d
- name: pgconf
mountPath: /etc/postgresql
[… omitted: the liveness and readiness probes]
volumes:
- name: initdb
configMap:
name: db-initdb
- name: pgconf
configMap:
name: db-config

Esses argumentos do servidor chegam como args: em vez de command:, e a diferença decide se o banco de dados sobe populado: args: fornece argumentos ao entrypoint da imagem, enquanto command: o substitui. Esse entrypoint é o script de inicialização que cria o banco de dados em um diretório de dados vazio, lê o ambiente POSTGRES_* e executa os arquivos em /docker-entrypoint-initdb.d. Substituí-lo iniciaria o servidor com o postgresql.conf montado e pularia tanto a inicialização quanto os scripts de bootstrap — os valores que o Aggregate definiu seriam renderizados no manifesto e nunca executados.

Definir apenas um dos dois valores é igualmente válido — o ConfigMap, o volume e a montagem do outro simplesmente não existem, e o argumento do arquivo de configuração só aparece quando custom_config está definido.

Compose

A Recipe do Compose para core/datastore/postgres lê o mesmo Component e realiza os dois valores por meio da primitiva própria do compose: ela renderiza entradas configs: de nível superior, e o serviço monta cada uma como arquivo.

  • init_scripts → uma config por chave, cada uma montada com o seu próprio nome de arquivo em /docker-entrypoint-initdb.d. A imagem executa uma vez os arquivos que encontra ali, em ordem de nome de arquivo, e apenas quando o diretório de dados está vazio — um banco de dados que já contém dados não é tocado.
  • custom_config → uma config, montada como o arquivo único /etc/postgresql/postgresql.conf, com os mesmos argumentos postgres -c config_file=… apontando o servidor para ele. As configurações que o fragmento omite mantêm os seus valores padrão embutidos.

Aqui também cada metade é protegida por uma verificação de presença, então um Aggregate que deixa um valor sem definir é renderizado como se essa chave não existisse.

Uma configuração merece ser citada ao escrever um bloco custom_config para uma Release no compose: listen_addresses aceita apenas conexões locais por padrão, então um bloco que a omite deixa o banco de dados inacessível a partir dos outros serviços da rede do compose.

O Manifest deste exemplo encaminha core/datastore/postgres para a Recipe helm. Fazer o build do mesmo Aggregate no compose significa usar, em vez disso, um Manifest que o encaminhe para compose/postgres; os valores do desenvolvedor não são tocados.