Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler 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 programador que determinam o primeiro arranque da base 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 leva-os para o contentor como ConfigMaps montados. Este exemplo mostra que a funcionalidade é aditiva: um Aggregate que não define nenhum dos dois valores é renderizado exatamente como uma base de dados mínima, e um Aggregate que os define ganha os ConfigMaps, os volumes e as montagens sem que mais nada seja perturbado.

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

  • release-bare.yaml (aggregate-bare.yaml) — init_scripts e custom_config por definir.
  • release-config.yaml (aggregate-config.yaml) — ambos definidos.

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

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

Terminal window
cd postgres-init-config

Compilação

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

O catálogo resolve-se a partir do registo do hub nomeado em .aggrega-config.yaml, pelo que não é necessária nenhuma flag --catalog, e --auto-pull escreve durante a compilação o ficheiro de bloqueio que falta a um clone acabado de criar. A release básica escreve três ficheiros em dist/helm/helm/; a release configurada escreve esses três e mais 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-lhe este prompt.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa 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`: esta escreve o exemplo numa nova pasta `postgres-init-config`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-bare.yaml` e `release-config.yaml` — de cada vez com `workspace_root` definido como `postgres-init-config`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros cada compilação escreveu; encontram-se em `postgres-init-config/dist/`.

Básica — a linha de base aditiva

aggregate-bare.yaml deixa os dois valores por 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 ficheiro de configuração no contentor. Esta é a forma habitual de uma base de dados PostgreSQL mínima:

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

Como os dois valores estão protegidos por uma verificação de presença na Recipe, um valor por definir não emite nada — o corpo do ConfigMap é renderizado vazio e ignorado, e as linhas do volume, da montagem e do argumento do servidor ficam excluídas pela verificação. Um Aggregate que nunca toca nestes 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

A compilação escreve agora dois ConfigMaps adicionais e liga-os 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 nomeia-os no seu bloco artifacts:, e um ficheiro nomeado aí contém a chave que o seu autor escreveu em vez de algo que identifique o componente — pelo que a compilação o escreve sob o componente que o declarou, e dois componentes que partilham uma Recipe não podem ir parar ao mesmo caminho. O StatefulSet e os dois Services recebem o nome do destino a partir do componente a que pertencem, pelo que permanecem no diretório próprio da fronteira.

Os dois valores viajam em ConfigMaps separados porque cada um é montado inteiro num caminho diferente do contentor:

  • init_scripts → ConfigMap db-initdb, uma chave de dados por script (01-schema.sql, 02-seed.sql). Um volume configmap monta-o em /docker-entrypoint-initdb.d, onde o PostgreSQL executa os ficheiros uma vez na primeira inicialização, por ordem alfabética de chave.
  • custom_config → ConfigMap db-config, uma chave de dados postgresql.conf. Um segundo volume configmap monta-o em /etc/postgresql, e os args: do contentor apontam o servidor para ele: postgres -c config_file=/etc/postgresql/postgresql.conf. As definições que o fragmento omite mantêm os seus valores predefinidos incorporados.
# 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 a base de dados arranca com dados: args: fornece argumentos ao entrypoint da imagem, enquanto command: o substitui. Esse entrypoint é o script de arranque que cria a base de dados num diretório de dados vazio, lê o ambiente POSTGRES_* e executa os ficheiros em /docker-entrypoint-initdb.d. Substituí-lo arrancaria o servidor com o postgresql.conf montado e saltaria tanto a inicialização como 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 ficheiro 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 através da primitiva própria do compose: renderiza entradas configs: de nível superior, e o serviço monta cada uma como ficheiro.

  • init_scripts → uma config por chave, cada uma montada com o seu próprio nome de ficheiro em /docker-entrypoint-initdb.d. A imagem executa uma vez os ficheiros que aí encontra, por ordem de nome de ficheiro, e apenas quando o diretório de dados está vazio — uma base de dados que já contém dados não é tocada.
  • custom_config → uma config, montada como o ficheiro único /etc/postgresql/postgresql.conf, com os mesmos argumentos postgres -c config_file=… a apontar o servidor para ele. As definições que o fragmento omite mantêm os seus valores predefinidos incorporados.

Também aqui cada metade está protegida por uma verificação de presença, pelo que um Aggregate que deixa um valor por definir é renderizado como se essa chave não existisse.

Uma definição merece ser referida ao escrever um bloco custom_config para uma Release no compose: listen_addresses aceita apenas ligações locais por predefinição, pelo que um bloco que a omita deixa a base 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. Compilar o mesmo Aggregate no compose significa usar, em vez disso, um Manifest que o encaminhe para compose/postgres; os valores do programador não são tocados.