Script di bootstrap e configurazione personalizzata di PostgreSQL — helm sintetizzato
core/datastore/postgres espone due valori facoltativi dello sviluppatore che determinano il primo avvio del database: init_scripts (SQL o shell eseguiti una sola volta all’inizializzazione) e custom_config (un frammento di postgresql.conf). Sul target helm sintetizzato, la Recipe li porta nel container come ConfigMap montate. Questo esempio mostra che la funzionalità è additiva: un Aggregate che non imposta nessuno dei due valori viene renderizzato esattamente come un database minimo, e un Aggregate che li imposta ottiene le ConfigMap, i volumi e i mount senza che nient’altro venga toccato.
Due Releases dello stesso Component, con lo stesso Manifest, che differiscono solo nei valori dello sviluppatore:
release-bare.yaml(aggregate-bare.yaml) —init_scriptsecustom_confignon impostati.release-config.yaml(aggregate-config.yaml) — entrambi impostati.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example postgres-init-configPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd postgres-init-configBuild
aggrega build --release release-bare.yaml --auto-pullaggrega build --release release-config.yaml --auto-pullIl catalogo si risolve dal registry dell’hub indicato in .aggrega-config.yaml, quindi non serve alcun flag --catalog, e --auto-pull scrive durante la build il lockfile che manca a un clone appena creato. La release essenziale scrive tre file in dist/helm/helm/; la release configurata scrive quei tre più altri due in dist/helm/helm/db/.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella Workspace non contiene ancora una cartella `postgres-init-config`, chiama una volta lo strumento `scaffold` con `example` impostato a `postgres-init-config` e senza `dir`: scrive l’esempio in una nuova cartella `postgres-init-config`. Poi chiama lo strumento `build` una volta per ogni Release, in quest’ordine — `release-bare.yaml` e `release-config.yaml` — ogni volta con `workspace_root` impostato a `postgres-init-config`, `release` impostato a quel file, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto ogni build; si trovano in `postgres-init-config/dist/`.Essenziale — la base additiva
aggregate-bare.yaml lascia entrambi i valori non impostati. L’output renderizzato è uno StatefulSet, un Service ClusterIP e un Service headless — nessuna ConfigMap, nessun volume configmap, nessun mount di volume nella directory di inizializzazione e nessun argomento di file di configurazione sul container. Questa è la forma ordinaria di un database PostgreSQL minimo:
dist/helm/helm/db-statefulset.yamldist/helm/helm/db-default-service.yamldist/helm/helm/db-headless-service.yamlPoiché nella Recipe entrambi i valori sono protetti da un controllo di presenza, un valore non impostato non emette nulla — il corpo della ConfigMap viene renderizzato vuoto e viene saltato, e le righe del volume, del mount e dell’argomento del server vengono escluse dal controllo. Un Aggregate che non tocca mai questi valori non viene modificato dalla loro esistenza.
Configurato — script e configurazione montati
aggregate-config.yaml imposta entrambi i valori:
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 = 256MBOra la build scrive due ConfigMap aggiuntive e le cabla nello StatefulSet:
dist/helm/helm/db/initdb-configmap.yamldist/helm/helm/db/config-configmap.yamlEntrambe si trovano sotto db/, il nome stesso del componente. La Recipe le nomina nel suo blocco artifacts:, e un file nominato lì porta la chiave che il suo autore ha scritto anziché qualcosa che identifichi il componente — quindi la build lo scrive sotto il componente che lo ha dichiarato, e due componenti che condividono una Recipe non possono finire sullo stesso percorso. Lo StatefulSet e i due Service ricevono il nome dal target a partire dal componente a cui appartengono, quindi restano nella directory propria del confine.
I due valori viaggiano in ConfigMap separate perché ciascuna viene montata per intero in un percorso diverso del container:
init_scripts→ ConfigMapdb-initdb, una chiave di dati per script (01-schema.sql,02-seed.sql). Un volumeconfigmapla monta in/docker-entrypoint-initdb.d, dove PostgreSQL esegue i file una sola volta alla prima inizializzazione, in ordine alfabetico di chiave.custom_config→ ConfigMapdb-config, una chiave di datipostgresql.conf. Un secondo volumeconfigmapla monta in/etc/postgresql, e gliargs:del container indirizzano il server verso di essa:postgres -c config_file=/etc/postgresql/postgresql.conf. Le impostazioni che il frammento omette mantengono i loro valori predefiniti integrati.
# 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-configQuegli argomenti del server arrivano come args: anziché come command:, e la differenza decide se il database si avvia popolato: args: fornisce argomenti destinati all’entrypoint dell’immagine, mentre command: lo sostituisce. Quell’entrypoint è lo script di avvio che crea il database su una directory dei dati vuota, legge l’ambiente POSTGRES_* ed esegue i file sotto /docker-entrypoint-initdb.d. Sostituirlo avvierebbe il server con il postgresql.conf montato e salterebbe sia l’inizializzazione sia gli script di bootstrap — i valori impostati dall’Aggregate verrebbero renderizzati nel manifest e non verrebbero mai eseguiti.
Impostare solo uno dei due valori è ugualmente valido — la ConfigMap, il volume e il mount dell’altro sono semplicemente assenti, e l’argomento del file di configurazione compare solo quando custom_config è impostato.
Compose
La Recipe Compose per core/datastore/postgres legge lo stesso Component e realizza entrambi i valori tramite la primitiva propria di compose: renderizza voci configs: di primo livello, e il servizio monta ciascuna come file.
init_scripts→ una config per chiave, ciascuna montata con il proprio nome di file sotto/docker-entrypoint-initdb.d. L’immagine esegue una sola volta i file che vi trova, in ordine di nome di file, e solo quando la directory dei dati è vuota — un database che contiene già dati non viene toccato.custom_config→ una config, montata come l’unico file/etc/postgresql/postgresql.conf, con gli stessi argomentipostgres -c config_file=…che indirizzano il server verso di esso. Le impostazioni che il frammento omette mantengono i loro valori predefiniti integrati.
Anche qui ciascuna metà è protetta da un controllo di presenza, quindi un Aggregate che lascia un valore non impostato viene renderizzato come se quella chiave non esistesse.
Un’impostazione merita di essere citata quando si scrive un blocco custom_config per una Release su compose: listen_addresses accetta per impostazione predefinita solo connessioni locali, quindi un blocco che la omette lascia il database irraggiungibile dagli altri servizi sulla rete compose.
Il Manifest di questo esempio instrada core/datastore/postgres verso la Recipe helm. Eseguire la build dello stesso Aggregate su compose significa usare invece un Manifest che lo instrada verso compose/postgres; i valori dello sviluppatore restano invariati.