Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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_scripts e custom_config non 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:

Terminal window
aggrega scaffold --example postgres-init-config

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

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

Il 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.yaml
dist/helm/helm/db-default-service.yaml
dist/helm/helm/db-headless-service.yaml

Poiché 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 = 256MB

Ora la build scrive due ConfigMap aggiuntive e le cabla nello StatefulSet:

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

Entrambe 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 → ConfigMap db-initdb, una chiave di dati per script (01-schema.sql, 02-seed.sql). Un volume configmap la monta in /docker-entrypoint-initdb.d, dove PostgreSQL esegue i file una sola volta alla prima inizializzazione, in ordine alfabetico di chiave.
  • custom_config → ConfigMap db-config, una chiave di dati postgresql.conf. Un secondo volume configmap la monta in /etc/postgresql, e gli args: 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-config

Quegli 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 argomenti postgres -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.