Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Скрипти початкового налаштування PostgreSQL і власна конфігурація — синтезований helm

core/datastore/postgres надає два необов’язкові значення розробника, які визначають перший запуск бази даних: init_scripts (SQL або shell, що виконуються один раз під час ініціалізації) і custom_config (фрагмент postgresql.conf). На цілі синтезованого helm Recipe передає їх у контейнер як змонтовані ConfigMap. Цей приклад показує, що ця можливість адитивна: сутність Aggregate, яка не задає жодного з цих значень, рендериться точно так само, як мінімальна база даних, а сутність Aggregate, яка їх задає, отримує ConfigMap, томи й точки монтування, і більше нічого не змінюється.

Дві сутності Releases того самого Component з тим самим Manifest, що відрізняються лише значеннями розробника:

  • release-bare.yaml (aggregate-bare.yaml) — init_scripts і custom_config не задано.
  • release-config.yaml (aggregate-config.yaml) — задано обидва.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

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

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd postgres-init-config

Збирання

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

Каталог визначається з реєстру hub, вказаного в .aggrega-config.yaml, тому прапорець --catalog не потрібен, а --auto-pull під час збирання записує lock-файл, якого бракує у свіжому клоні. Базовий реліз записує три файли в dist/helm/helm/; налаштований реліз записує ці три файли і ще два в dist/helm/helm/db/.

З ШІ-асистентом

ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.

Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека Workspace ще не містить теки `postgres-init-config`, викличте один раз інструмент `scaffold`, задавши для `example` значення `postgres-init-config` і не задаючи `dir`: він запише приклад у нову теку `postgres-init-config`. Потім викличте інструмент `build` один раз для кожної сутності Release у такому порядку — `release-bare.yaml` і `release-config.yaml` — щоразу задаючи для `workspace_root` значення `postgres-init-config`, для `release` — цей файл, для `auto_pull` — true і для `write` — true. Скажіть мені, які файли записала кожна збірка; вони розташовані в `postgres-init-config/dist/`.

Базовий варіант — адитивна відправна точка

aggregate-bare.yaml не задає жодного з двох значень. Результат рендерингу — це StatefulSet, ClusterIP Service і Headless Service — без ConfigMap, без тому configmap, без монтування тому в каталог ініціалізації та без аргументу конфігураційного файлу в контейнері. Це звичайна форма мінімальної бази даних PostgreSQL:

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

Оскільки обидва значення в Recipe захищено перевіркою наявності, незадане значення не породжує нічого — тіло ConfigMap рендериться порожнім і пропускається, а рядки тому, монтування й аргументу сервера відкидаються перевіркою. Сутність Aggregate, яка ніколи не торкається цих значень, їхнє існування ніяк не змінює.

Налаштований варіант — змонтовані скрипти й конфігурація

aggregate-config.yaml задає обидва значення:

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

Тепер збирання записує дві додаткові ConfigMap і підключає їх до StatefulSet:

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

Обидві розміщено в db/, власній назві компонента. Recipe називає їх у своєму блоці artifacts:, а файл, названий там, має ключ, який написав його автор, а не щось, що ідентифікує компонент, — тому збирання записує його під компонентом, що його оголосив, і два компоненти зі спільним Recipe не можуть потрапити в один шлях. StatefulSet і дві Service ціль називає за компонентом, якому вони належать, тому вони залишаються у власному каталозі межі.

Два значення передаються в окремих ConfigMap, бо кожна монтується цілком в інший шлях контейнера:

  • init_scripts → ConfigMap db-initdb, один ключ даних на скрипт (01-schema.sql, 02-seed.sql). Том configmap монтує її в /docker-entrypoint-initdb.d, де PostgreSQL виконує файли один раз під час першої ініціалізації в алфавітному порядку ключів.
  • custom_config → ConfigMap db-config, один ключ даних postgresql.conf. Другий том configmap монтує її в /etc/postgresql, а args: контейнера вказують на неї серверу: postgres -c config_file=/etc/postgresql/postgresql.conf. Параметри, яких фрагмент не містить, зберігають свої вбудовані значення за замовчуванням.
# 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

Ці аргументи сервера передаються як args:, а не як command:, і від цієї різниці залежить, чи запуститься база даних заповненою: args: передає аргументи до точки входу образу, тоді як command: її замінює. Ця точка входу — стартовий скрипт, який створює базу даних у порожньому каталозі даних, читає середовище POSTGRES_* і виконує файли в /docker-entrypoint-initdb.d. Її заміна запустила б сервер зі змонтованим postgresql.conf і пропустила б і ініціалізацію, і скрипти початкового налаштування — значення, задані в сутності Aggregate, потрапили б у маніфест, але ніколи не виконалися б.

Задати лише одне з двох значень так само допустимо — ConfigMap, том і монтування іншого просто відсутні, а аргумент конфігураційного файлу з’являється лише тоді, коли задано custom_config.

Compose

Compose Recipe для core/datastore/postgres читає той самий Component і реалізує обидва значення через власний примітив compose: він рендерить записи верхнього рівня configs:, а сервіс монтує кожен із них як файл.

  • init_scripts → одна конфігурація на ключ, кожна змонтована під власним іменем файлу в /docker-entrypoint-initdb.d. Образ виконує знайдені там файли один раз у порядку імен файлів і лише тоді, коли каталог даних порожній, — база даних, яка вже містить дані, залишається незмінною.
  • custom_config → одна конфігурація, змонтована як єдиний файл /etc/postgresql/postgresql.conf, з тими самими аргументами postgres -c config_file=…, що вказують на неї серверу. Параметри, яких фрагмент не містить, зберігають свої вбудовані значення за замовчуванням.

Кожну половину тут теж захищено перевіркою наявності, тому сутність Aggregate, яка не задає одного зі значень, рендериться так, ніби цього ключа не існувало.

Під час написання блоку custom_config для розгортання compose варто згадати один параметр: listen_addresses за замовчуванням приймає лише локальні з’єднання, тому блок, який його не містить, залишає базу даних недоступною для інших сервісів у мережі compose.

Manifest у цьому прикладі спрямовує core/datastore/postgres до helm Recipe. Збирання того самого Aggregate на compose означає Manifest, який натомість спрямовує його до compose/postgres; значення розробника лишаються незмінними.