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_scriptsecustom_confignã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:
aggrega scaffold --example postgres-init-configEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd postgres-init-configBuild
aggrega build --release release-bare.yaml --auto-pullaggrega build --release release-config.yaml --auto-pullO 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.yamldist/helm/helm/db-default-service.yamldist/helm/helm/db-headless-service.yamlComo 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 = 256MBAgora o build grava dois ConfigMaps adicionais e os conecta ao StatefulSet:
dist/helm/helm/db/initdb-configmap.yamldist/helm/helm/db/config-configmap.yamlAmbos 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→ ConfigMapdb-initdb, uma chave de dados por script (01-schema.sql,02-seed.sql). Um volumeconfigmapo 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→ ConfigMapdb-config, uma chave de dadospostgresql.conf. Um segundo volumeconfigmapo monta em/etc/postgresql, e osargs: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-configEsses 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 argumentospostgres -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.