콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

PostgreSQL 부트스트랩 스크립트와 사용자 지정 구성 — 합성된 helm

core/datastore/postgres는 데이터베이스의 첫 시작을 결정하는 선택적 개발자 값 두 개를 노출합니다. init_scripts(초기화 시 한 번 실행되는 SQL 또는 셸)와 custom_config(postgresql.conf 조각)입니다. 합성된 helm 타깃에서는 Recipe가 이 값들을 마운트된 ConfigMap으로 컨테이너에 전달합니다. 이 예제는 이 기능이 추가적임을 보여 줍니다. 두 값을 모두 설정하지 않은 Aggregate는 최소 데이터베이스와 정확히 똑같이 렌더링되고, 값을 설정한 Aggregate는 다른 부분은 전혀 건드리지 않은 채 ConfigMap, 볼륨, 마운트를 얻습니다.

같은 Component, 같은 Manifest를 사용하며 개발자 값만 다른 두 Releases입니다.

  • release-bare.yaml (aggregate-bare.yaml) — init_scripts와 custom_config를 설정하지 않습니다.
  • release-config.yaml (aggregate-config.yaml) — 두 값을 모두 설정합니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

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

카탈로그는 .aggrega-config.yaml에 지정된 hub 레지스트리에서 해석되므로 --catalog 플래그가 필요하지 않으며, --auto-pull이 새로 클론한 사본에 없는 잠금 파일을 빌드 중에 기록합니다. 기본 릴리스는 dist/helm/helm/ 아래에 파일 세 개를 쓰고, 구성된 릴리스는 그 세 개에 더해 dist/helm/helm/db/ 아래에 두 개를 더 씁니다.

AI 어시스턴트 사용

Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. Workspace 폴더에 아직 `postgres-init-config` 폴더가 없으면 `example`을 `postgres-init-config`로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 새 `postgres-init-config` 폴더에 예제가 작성됩니다. 그런 다음 각 Release마다 `release-bare.yaml`, `release-config.yaml` 순서로 `build` 도구를 한 번씩 호출하되, 매번 `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 볼륨도, init 디렉터리로의 볼륨 마운트도, 컨테이너의 구성 파일 인수도 없습니다. 이는 최소 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

이 서버 인수는 command:가 아니라 args:로 전달되며, 이 차이가 데이터베이스가 채워진 상태로 올라오는지를 결정합니다. args:는 이미지의 엔트리포인트에 인수를 제공하는 반면, command:는 엔트리포인트를 대체합니다. 그 엔트리포인트는 빈 데이터 디렉터리에 데이터베이스를 생성하고, POSTGRES_* 환경을 읽고, /docker-entrypoint-initdb.d 아래의 파일을 실행하는 시작 스크립트입니다. 이를 대체하면 서버가 마운트된 postgresql.conf로 시작되어 초기화와 부트스트랩 스크립트를 모두 건너뜁니다. Aggregate가 설정한 값은 매니페스트에 렌더링되지만 실행되지는 않습니다.

두 값 중 하나만 설정해도 똑같이 유효합니다. 다른 값의 ConfigMap, 볼륨, 마운트가 없을 뿐이며, 구성 파일 인수는 custom_config가 설정된 경우에만 나타납니다.

Compose

core/datastore/postgres용 Compose Recipe는 같은 Component를 읽고 compose 자체의 기본 요소로 두 값을 구현합니다. 최상위 configs: 항목을 렌더링하고, 서비스가 각 항목을 파일로 마운트합니다.

  • init_scripts → 키마다 config 하나, 각각 /docker-entrypoint-initdb.d 아래에 자신의 파일 이름으로 마운트됩니다. 이미지는 거기서 찾은 파일을 파일 이름 순서로 한 번 실행하며, 데이터 디렉터리가 비어 있을 때만 실행합니다. 이미 데이터가 있는 데이터베이스는 건드리지 않습니다.
  • custom_config → config 하나, 단일 파일 /etc/postgresql/postgresql.conf로 마운트되며, 같은 postgres -c config_file=… 인수가 서버에 이 파일을 가리킵니다. 조각에서 생략한 설정은 기본 제공 기본값을 유지합니다.

여기서도 각 부분이 존재 여부로 보호되므로, 한 값을 설정하지 않은 Aggregate는 그 키가 존재하지 않는 것처럼 렌더링됩니다.

compose 배포용 custom_config 블록을 작성할 때 짚어 둘 만한 설정이 하나 있습니다. listen_addresses는 기본적으로 로컬 연결만 허용하므로, 이를 생략한 블록은 compose 네트워크의 다른 서비스에서 데이터베이스에 접근할 수 없게 만듭니다.

이 예제의 Manifest는 core/datastore/postgres를 helm Recipe로 라우팅합니다. 같은 Aggregate를 compose에서 빌드하려면 대신 이를 compose/postgres로 라우팅하는 Manifest가 필요하며, 개발자 값은 그대로입니다.