cnpg-cluster 1.1.0 — postInitApplicationSQLRefs 노출

앱별 부트스트랩 SQL 을 ConfigMap/Secret 참조로 실행할 수 있게 한다. CNPG CRD 에는
이미 있는 필드(operator 0.29.0/CRD 확인됨)인데 차트가 렌더하지 않아 values 로 쓸 수
없었다.

용도: 스키마 덤프처럼 큰 SQL 을 values 에 인라인하지 않고 ConfigMap 으로 넘기는 경우.
postInitApplicationSQL(인라인)과 시점·권한이 동일(클러스터 생성 직후 1회, 앱 DB 안에서
superuser) 하고 SQL 출처만 다르다. 1회성이라 비멱등 SQL(CREATE TABLE 등)을 그대로
넣어도 재실행되지 않는다.

- values.yaml: bootstrap.initdb.postInitApplicationSQLRefs 추가(configMapRefs/secretRefs,
  기본 빈 배열)
- templates/cluster.yaml: 값이 있을 때만 렌더(있으면 렌더, 없으면 필드 자체가 안 나옴 —
  기존 클러스터에 영향 없음을 렌더 테스트로 확인)
- CUSTOM-README.md: postInitApplicationSQL 과의 차이·참조 처리 순서(Secret 전체 →
  ConfigMap 전체) 문서화

카탈로그 관례 파일(BUILD-README·CUSTOM-README 본문 대부분·dip-*.yaml·custom-values.yaml)은
1.0.0 에서 그대로 승계했다(diff 로 확인).

검증: 빈 값일 때 필드 미노출, configMapRefs 지정 시 정상 렌더, 기존 1.0.0
custom-values.yaml 로 1.1.0 렌더해도 문제없음(하위 호환) 확인.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

manifests/helm/cnpg-cluster/1.1.0/templates/NOTES.txt

@@ -0,0 +1,55 @@
+PostgreSQL 클러스터 "{{ include "cnpg-cluster.fullname" . }}" 를 배포했습니다.
+인스턴스 {{ .Values.instances }}개 / 이미지 {{ include "cnpg-cluster.image" . }}
+
+1. 상태 확인 (반드시 FQN 을 사용하세요 — kubectl get cluster 는 Rancher/CAPI 리소스와 충돌합니다)
+
+   kubectl -n {{ include "cnpg-cluster.namespace" . }} get clusters.postgresql.cnpg.io {{ include "cnpg-cluster.fullname" . }}
+   kubectl -n {{ include "cnpg-cluster.namespace" . }} get pods -l cnpg.io/cluster={{ include "cnpg-cluster.fullname" . }} -L cnpg.io/instanceRole
+
+2. 접속 엔드포인트
+
+   {{ include "cnpg-cluster.fullname" . }}-rw   : primary (읽기/쓰기)
+   {{ include "cnpg-cluster.fullname" . }}-ro   : replica 만 (읽기 전용)
+   {{ include "cnpg-cluster.fullname" . }}-r    : 전체 인스턴스 (읽기 라운드로빈)
+{{- if .Values.pooler.enabled }}
+   {{ include "cnpg-cluster.fullname" . }}-pooler-{{ .Values.pooler.type }} : PgBouncer ({{ .Values.pooler.poolMode }} 모드)
+{{- end }}
+
+3. 자격증명
+
+   DB     : {{ .Values.bootstrap.initdb.database }}
+   User   : {{ .Values.bootstrap.initdb.owner }}
+{{- if .Values.bootstrap.initdb.secretName }}
+   Secret : {{ .Values.bootstrap.initdb.secretName }} (사용자 지정)
+{{- else }}
+   Secret : {{ include "cnpg-cluster.fullname" . }}-app (operator 자동 생성)
+
+   kubectl -n {{ include "cnpg-cluster.namespace" . }} get secret {{ include "cnpg-cluster.fullname" . }}-app \
+     -o jsonpath='{.data.password}' | base64 -d
+{{- end }}
+{{- if not .Values.enableSuperuserAccess }}
+
+   superuser(postgres) 직접 접속은 비활성화되어 있습니다 (enableSuperuserAccess: false).
+{{- end }}
+
+4. psql 접속 예시
+
+   kubectl -n {{ include "cnpg-cluster.namespace" . }} exec -it {{ include "cnpg-cluster.fullname" . }}-1 -c postgres -- \
+     psql -U postgres -d {{ .Values.bootstrap.initdb.database }}
+
+{{- if not .Values.backup.enabled }}
+
+경고: 백업이 비활성화되어 있습니다(backup.enabled: false). 운영 환경에서는
+      barmanObjectStore 를 설정하고 scheduledBackup 을 활성화하세요.
+      백업 없이는 PITR(Point-In-Time Recovery)이 불가능합니다.
+{{- end }}
+{{- if eq (int .Values.instances) 1 }}
+
+경고: instances=1 입니다. replica 가 없어 failover 가 불가능합니다.
+{{- end }}
+{{- if eq .Values.affinity.podAntiAffinityType "preferred" }}
+
+참고: podAntiAffinityType 이 "preferred" 입니다. 여러 인스턴스가 같은 노드에
+      배치될 수 있어 노드 장애 시 동시 손실 위험이 있습니다.
+      노드 수가 instances 이상인 운영 환경에서는 "required" 를 사용하세요.
+{{- end }}

manifests/helm/cnpg-cluster/1.1.0/templates/_helpers.tpl

@@ -0,0 +1,70 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "cnpg-cluster.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "cnpg-cluster.fullname" -}}
+{{- if .Values.nameOverride }}
+{{- .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- .Release.Name | default "cnpg-cluster" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "cnpg-cluster.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "cnpg-cluster.labels" -}}
+helm.sh/chart: {{ include "cnpg-cluster.chart" . }}
+{{ include "cnpg-cluster.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "cnpg-cluster.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "cnpg-cluster.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the namespace to use
+*/}}
+{{- define "cnpg-cluster.namespace" -}}
+{{- if .Values.namespaceOverride }}
+{{- .Values.namespaceOverride }}
+{{- else }}
+{{- .Release.Namespace }}
+{{- end }}
+{{- end }}
+
+{{/*
+PostgreSQL 이미지. imageName 이 지정되면 그것을 그대로 쓰고, 아니면 repository:tag 조합.
+
+주의: 맨 major 태그(`:18`)를 쓰면 안 된다. 그 태그는 Debian 11(bullseye) 기반으로
+      2026-08-31 에 지원이 종료된다. 반드시 베이스 OS 를 포함한 태그를 지정한다
+      (예: 18.4-system-trixie → Debian 13, 2030-06-30 까지 지원).
+*/}}
+{{- define "cnpg-cluster.image" -}}
+{{- if .Values.postgresql.imageName }}
+{{- .Values.postgresql.imageName }}
+{{- else }}
+{{- printf "%s:%s" .Values.postgresql.image.repository (.Values.postgresql.image.tag | toString) }}
+{{- end }}
+{{- end }}

manifests/helm/cnpg-cluster/1.1.0/templates/cluster.yaml

@@ -0,0 +1,135 @@
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: {{ include "cnpg-cluster.fullname" . }}
+  namespace: {{ include "cnpg-cluster.namespace" . }}
+  labels:
+    {{- include "cnpg-cluster.labels" . | nindent 4 }}
+    {{- with .Values.extraLabels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+  {{- with .Values.extraAnnotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  instances: {{ .Values.instances }}
+  imageName: {{ include "cnpg-cluster.image" . }}
+
+  primaryUpdateStrategy: {{ .Values.primaryUpdateStrategy }}
+  primaryUpdateMethod: {{ .Values.primaryUpdateMethod }}
+
+  enableSuperuserAccess: {{ .Values.enableSuperuserAccess }}
+
+  postgresql:
+    {{- with .Values.postgresql.parameters }}
+    parameters:
+      {{- range $k, $v := . }}
+      {{ $k }}: {{ $v | quote }}
+      {{- end }}
+    {{- end }}
+    {{- with .Values.postgresql.sharedPreloadLibraries }}
+    shared_preload_libraries:
+      {{- toYaml . | nindent 6 }}
+    {{- end }}
+    {{- with .Values.postgresql.pg_hba }}
+    pg_hba:
+      {{- toYaml . | nindent 6 }}
+    {{- end }}
+    {{- with .Values.postgresql.synchronous }}
+    synchronous:
+      {{- toYaml . | nindent 6 }}
+    {{- end }}
+
+  bootstrap:
+    initdb:
+      database: {{ .Values.bootstrap.initdb.database }}
+      owner: {{ .Values.bootstrap.initdb.owner }}
+      {{- with .Values.bootstrap.initdb.secretName }}
+      secret:
+        name: {{ . }}
+      {{- end }}
+      {{- with .Values.bootstrap.initdb.encoding }}
+      encoding: {{ . }}
+      {{- end }}
+      {{- with .Values.bootstrap.initdb.localeCollate }}
+      localeCollate: {{ . }}
+      {{- end }}
+      {{- with .Values.bootstrap.initdb.localeCType }}
+      localeCType: {{ . }}
+      {{- end }}
+      {{- with .Values.bootstrap.initdb.postInitApplicationSQL }}
+      postInitApplicationSQL:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.bootstrap.initdb.postInitApplicationSQLRefs }}
+      {{- if or .configMapRefs .secretRefs }}
+      postInitApplicationSQLRefs:
+        {{- with .secretRefs }}
+        secretRefs:
+          {{- toYaml . | nindent 10 }}
+        {{- end }}
+        {{- with .configMapRefs }}
+        configMapRefs:
+          {{- toYaml . | nindent 10 }}
+        {{- end }}
+      {{- end }}
+      {{- end }}
+
+  storage:
+    size: {{ .Values.storage.size }}
+    {{- with .Values.storage.storageClass }}
+    storageClass: {{ . }}
+    {{- end }}
+
+  {{- if .Values.walStorage.enabled }}
+  walStorage:
+    size: {{ .Values.walStorage.size }}
+    {{- with .Values.walStorage.storageClass }}
+    storageClass: {{ . }}
+    {{- end }}
+  {{- end }}
+
+  resources:
+    {{- toYaml .Values.resources | nindent 4 }}
+
+  affinity:
+    enablePodAntiAffinity: {{ .Values.affinity.enablePodAntiAffinity }}
+    podAntiAffinityType: {{ .Values.affinity.podAntiAffinityType }}
+    topologyKey: {{ .Values.affinity.topologyKey }}
+    {{- with .Values.affinity.nodeSelector }}
+    nodeSelector:
+      {{- toYaml . | nindent 6 }}
+    {{- end }}
+    {{- with .Values.affinity.tolerations }}
+    tolerations:
+      {{- toYaml . | nindent 6 }}
+    {{- end }}
+
+  monitoring:
+    enablePodMonitor: {{ .Values.monitoring.enablePodMonitor }}
+    {{- with .Values.monitoring.customQueriesConfigMap }}
+    customQueriesConfigMap:
+      {{- toYaml . | nindent 6 }}
+    {{- end }}
+
+  {{- if .Values.backup.enabled }}
+  backup:
+    retentionPolicy: {{ .Values.backup.retentionPolicy }}
+    barmanObjectStore:
+      destinationPath: {{ required "backup.enabled=true 이면 backup.barmanObjectStore.destinationPath 가 필요하다" .Values.backup.barmanObjectStore.destinationPath }}
+      {{- with .Values.backup.barmanObjectStore.endpointURL }}
+      endpointURL: {{ . }}
+      {{- end }}
+      s3Credentials:
+        accessKeyId:
+          name: {{ required "backup.enabled=true 이면 s3Credentials.accessKeyId.name 이 필요하다" .Values.backup.barmanObjectStore.s3Credentials.accessKeyId.name }}
+          key: {{ .Values.backup.barmanObjectStore.s3Credentials.accessKeyId.key }}
+        secretAccessKey:
+          name: {{ required "backup.enabled=true 이면 s3Credentials.secretAccessKey.name 이 필요하다" .Values.backup.barmanObjectStore.s3Credentials.secretAccessKey.name }}
+          key: {{ .Values.backup.barmanObjectStore.s3Credentials.secretAccessKey.key }}
+      wal:
+        {{- toYaml .Values.backup.barmanObjectStore.wal | nindent 8 }}
+      data:
+        {{- toYaml .Values.backup.barmanObjectStore.data | nindent 8 }}
+  {{- end }}

manifests/helm/cnpg-cluster/1.1.0/templates/database.yaml

@@ -0,0 +1,48 @@
+{{- /*
+선언적 데이터베이스/확장 관리 (CNPG 1.26+ Database CRD).
+
+중요: bootstrap.initdb.postInitApplicationSQL 안의 CREATE EXTENSION 은 CNPG 1.30.0 에서
+반영되지 않는다(오류도 나지 않고 조용히 무시됨 — doc/deploy-test-cnpg.md 검증 기록 참고).
+확장은 반드시 이 Database CRD 로 선언해야 한다.
+*/}}
+{{- range .Values.databases }}
+---
+apiVersion: postgresql.cnpg.io/v1
+kind: Database
+metadata:
+  name: {{ include "cnpg-cluster.fullname" $ }}-{{ .name }}
+  namespace: {{ include "cnpg-cluster.namespace" $ }}
+  labels:
+    {{- include "cnpg-cluster.labels" $ | nindent 4 }}
+spec:
+  cluster:
+    name: {{ include "cnpg-cluster.fullname" $ }}
+  name: {{ .name }}
+  owner: {{ .owner | default $.Values.bootstrap.initdb.owner }}
+  ensure: {{ .ensure | default "present" }}
+  # retain = Database 리소스를 지워도 실제 DB 는 남는다 (운영 기본값)
+  databaseReclaimPolicy: {{ .reclaimPolicy | default "retain" }}
+  {{- with .extensions }}
+  extensions:
+    {{- range . }}
+    - name: {{ .name }}
+      ensure: {{ .ensure | default "present" }}
+      {{- with .version }}
+      version: {{ . | quote }}
+      {{- end }}
+      {{- with .schema }}
+      schema: {{ . }}
+      {{- end }}
+    {{- end }}
+  {{- end }}
+  {{- with .schemas }}
+  schemas:
+    {{- range . }}
+    - name: {{ .name }}
+      ensure: {{ .ensure | default "present" }}
+      {{- with .owner }}
+      owner: {{ . }}
+      {{- end }}
+    {{- end }}
+  {{- end }}
+{{- end }}

manifests/helm/cnpg-cluster/1.1.0/templates/pooler.yaml

@@ -0,0 +1,28 @@
+{{- if .Values.pooler.enabled }}
+apiVersion: postgresql.cnpg.io/v1
+kind: Pooler
+metadata:
+  name: {{ include "cnpg-cluster.fullname" . }}-pooler-{{ .Values.pooler.type }}
+  namespace: {{ include "cnpg-cluster.namespace" . }}
+  labels:
+    {{- include "cnpg-cluster.labels" . | nindent 4 }}
+spec:
+  cluster:
+    name: {{ include "cnpg-cluster.fullname" . }}
+  instances: {{ .Values.pooler.instances }}
+  type: {{ .Values.pooler.type }}
+  pgbouncer:
+    poolMode: {{ .Values.pooler.poolMode }}
+    {{- with .Values.pooler.parameters }}
+    parameters:
+      {{- range $k, $v := . }}
+      {{ $k }}: {{ $v | quote }}
+      {{- end }}
+    {{- end }}
+  template:
+    spec:
+      containers:
+        - name: pgbouncer
+          resources:
+            {{- toYaml .Values.pooler.resources | nindent 12 }}
+{{- end }}

manifests/helm/cnpg-cluster/1.1.0/templates/scheduled-backup.yaml

@@ -0,0 +1,16 @@
+{{- if and .Values.backup.enabled .Values.scheduledBackup.enabled }}
+apiVersion: postgresql.cnpg.io/v1
+kind: ScheduledBackup
+metadata:
+  name: {{ include "cnpg-cluster.fullname" . }}
+  namespace: {{ include "cnpg-cluster.namespace" . }}
+  labels:
+    {{- include "cnpg-cluster.labels" . | nindent 4 }}
+spec:
+  # CNPG 의 schedule 은 6필드다 (초 분 시 일 월 요일) — 표준 5필드 cron 이 아니다.
+  schedule: {{ .Values.scheduledBackup.schedule | quote }}
+  backupOwnerReference: {{ .Values.scheduledBackup.backupOwnerReference }}
+  immediate: {{ .Values.scheduledBackup.immediate }}
+  cluster:
+    name: {{ include "cnpg-cluster.fullname" . }}
+{{- end }}