Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Scripts de arranque y configuración personalizada de PostgreSQL — helm sintetizado

core/datastore/postgres expone dos valores opcionales del desarrollador que determinan el primer arranque de la base de datos: init_scripts (SQL o shell que se ejecuta una vez en la inicialización) y custom_config (un fragmento de postgresql.conf). En el destino helm sintetizado, la Recipe los lleva al contenedor como ConfigMaps montados. Este ejemplo muestra que la funcionalidad es aditiva: un Aggregate que no establece ninguno de los dos valores se renderiza exactamente como una base de datos mínima, y un Aggregate que los establece obtiene los ConfigMaps, los volúmenes y los montajes sin alterar nada más.

Dos Releases del mismo Component, con el mismo Manifest, que solo difieren en los valores del desarrollador:

  • release-bare.yaml (aggregate-bare.yaml) — init_scripts y custom_config sin establecer.
  • release-config.yaml (aggregate-config.yaml) — ambos establecidos.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

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

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd postgres-init-config

Compilación

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

El catálogo se resuelve desde el registro del hub nombrado en .aggrega-config.yaml, así que no hace falta ningún flag --catalog, y --auto-pull escribe durante la compilación el archivo de bloqueo que le falta a un clon nuevo. La release básica escribe tres archivos en dist/helm/helm/; la release configurada escribe esos tres más otros dos en dist/helm/helm/db/.

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta Workspace aún no contiene una carpeta `postgres-init-config`, llama una vez a la herramienta `scaffold` con `example` establecido en `postgres-init-config` y sin `dir`: escribe el ejemplo en una nueva carpeta `postgres-init-config`. Luego llama a la herramienta `build` una vez por cada Release, en este orden — `release-bare.yaml` y `release-config.yaml` — cada vez con `workspace_root` establecido en `postgres-init-config`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `postgres-init-config/dist/`.

Básica — la línea base aditiva

aggregate-bare.yaml deja ambos valores sin establecer. La salida renderizada es un StatefulSet, un Service ClusterIP y un Service headless — sin ConfigMap, sin volumen configmap, sin montaje de volumen en el directorio de inicialización y sin argumento de archivo de configuración en el contenedor. Esta es la forma habitual de una base de datos PostgreSQL mínima:

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

Como ambos valores están protegidos por una comprobación de presencia en la Recipe, un valor sin establecer no emite nada — el cuerpo del ConfigMap se renderiza vacío y se omite, y las líneas del volumen, del montaje y del argumento del servidor quedan excluidas por la comprobación. Un Aggregate que nunca toca estos valores no cambia por su existencia.

Configurada — scripts y configuración montados

aggregate-config.yaml establece ambos 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

Ahora la compilación escribe dos ConfigMaps adicionales y los conecta al StatefulSet:

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

Ambos quedan bajo db/, el nombre propio del componente. La Recipe los nombra en su bloque artifacts:, y un archivo nombrado allí lleva la clave que escribió su autor en lugar de algo que identifique al componente — así que la compilación lo escribe bajo el componente que lo declaró, y dos componentes que comparten una Recipe no pueden acabar en una misma ruta. El StatefulSet y los dos Services reciben su nombre del destino a partir del componente al que pertenecen, así que permanecen en el directorio propio del límite.

Los dos valores viajan en ConfigMaps separados porque cada uno se monta entero en una ruta distinta del contenedor:

  • init_scripts → ConfigMap db-initdb, una clave de datos por script (01-schema.sql, 02-seed.sql). Un volumen configmap lo monta en /docker-entrypoint-initdb.d, donde PostgreSQL ejecuta los archivos una vez en la primera inicialización, en orden alfabético de clave.
  • custom_config → ConfigMap db-config, una clave de datos postgresql.conf. Un segundo volumen configmap lo monta en /etc/postgresql, y los args: del contenedor dirigen el servidor hacia él: postgres -c config_file=/etc/postgresql/postgresql.conf. Los ajustes que el fragmento omite conservan sus valores predeterminados integrados.
# 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

Esos argumentos del servidor llegan como args: en lugar de como command:, y la diferencia decide si la base de datos arranca con datos: args: proporciona argumentos al punto de entrada de la imagen, mientras que command: lo reemplaza. Ese punto de entrada es el script de arranque que crea la base de datos en un directorio de datos vacío, lee el entorno POSTGRES_* y ejecuta los archivos bajo /docker-entrypoint-initdb.d. Reemplazarlo iniciaría el servidor con el postgresql.conf montado y omitiría tanto la inicialización como los scripts de arranque — los valores que estableció el Aggregate se renderizarían en el manifiesto y nunca se ejecutarían.

Establecer solo uno de los dos valores es igualmente válido — el ConfigMap, el volumen y el montaje del otro simplemente no están, y el argumento del archivo de configuración solo aparece cuando custom_config está establecido.

Compose

La Recipe de Compose para core/datastore/postgres lee el mismo Component y realiza ambos valores mediante la primitiva propia de compose: renderiza entradas configs: de nivel superior, y el servicio monta cada una como archivo.

  • init_scripts → una config por clave, cada una montada con su propio nombre de archivo bajo /docker-entrypoint-initdb.d. La imagen ejecuta una vez los archivos que encuentra allí, en orden de nombre de archivo, y solo cuando el directorio de datos está vacío — una base de datos que ya contiene datos no se toca.
  • custom_config → una config, montada como el único archivo /etc/postgresql/postgresql.conf, con los mismos argumentos postgres -c config_file=… que dirigen el servidor hacia él. Los ajustes que el fragmento omite conservan sus valores predeterminados integrados.

Aquí también cada mitad está protegida por una comprobación de presencia, así que un Aggregate que deja un valor sin establecer se renderiza como si esa clave no existiera.

Un ajuste merece mención al escribir un bloque custom_config para una Release en compose: listen_addresses solo acepta conexiones locales por defecto, así que un bloque que lo omite deja la base de datos inalcanzable desde los demás servicios de la red de compose.

El Manifest de este ejemplo encamina core/datastore/postgres a la Recipe helm. Compilar el mismo Aggregate en compose significa usar en su lugar un Manifest que lo encamine a compose/postgres; los valores del desarrollador no se tocan.