3.3 Operator 설정

CloudNativePG는 “설정보다 관례(convention over configuration)“를 따르므로 대부분의 기본값을 그대로 써도 된다. 그래도 상속할 label·annotation, 감시 namespace, 기본 이미지, rollout 지연 같은 전역 동작은 Operator 설정으로 바꿀 수 있다. 설정은 Operator namespace(기본 cnpg-system)에 있는 cnpg-controller-manager-config 라는 이름의 ConfigMap 또는 Secret으로 전달한다.

    flowchart TD
  CM["ConfigMap<br/>cnpg-controller-manager-config"]
  SC["Secret<br/>동일 이름"]
  OP["controller-manager"]
  RS["rollout restart"]
  NEW["이후 생성 리소스에<br/>설정 반영"]

  CM --> OP
  SC --> OP
  OP --> RS --> NEW

  classDef step fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  class CM,SC,OP,RS,NEW step

설정 변경은 Operator Pod를 재시작해야 반영되고, 재시작 이후 새로 생성되는 리소스에만 적용된다. 이미 떠 있는 Cluster에 소급 적용되지 않으므로, 기존 리소스에 반영하려면 해당 리소스를 다시 조정하거나 재생성해야 한다.

ConfigMap과 Secret

ConfigMap과 Secret 둘 다 같은 이름(cnpg-controller-manager-config)으로 쓸 수 있다. 민감하지 않은 값은 ConfigMap, 자격증명처럼 노출을 피해야 하는 값은 Secret에 둔다. Operator는 ConfigMap을 먼저 읽고 Secret을 나중에 읽으므로, 같은 파라미터가 양쪽에 있으면 Secret 값이 우선한다.

주요 설정 항목

파라미터	용도	기본값
`INHERITED_ANNOTATIONS`	생성 리소스에 상속할 annotation 이름	—
`INHERITED_LABELS`	생성 리소스에 상속할 label 이름	—
`WATCH_NAMESPACE`	감시할 namespace 목록(쉼표 구분)	전역
`CLUSTERS_ROLLOUT_DELAY`	Cluster 업그레이드 사이 대기(초)	0
`INSTANCES_ROLLOUT_DELAY`	같은 Cluster 내 인스턴스 사이 대기(초)	0
`ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES`	instance manager in-place 갱신	false
`MONITORING_QUERIES_CONFIGMAP`	기본 모니터링 쿼리 ConfigMap	—
`MONITORING_QUERIES_SECRET`	기본 모니터링 쿼리 Secret	—
`POSTGRES_IMAGE_NAME`	기본 PostgreSQL 이미지	Operator 버전 기본값
`PGBOUNCER_IMAGE_NAME`	기본 PgBouncer 이미지	Operator 버전 기본값
`PULL_SECRET_NAME`	추가 image pull secret 이름	—
`CERTIFICATE_DURATION`	생성 인증서 수명(일)	90
`EXPIRING_CHECK_THRESHOLD`	인증서 만료 경고 임계값(일)	7
`DRAIN_TAINTS`	노드 drain으로 판단할 taint 키	표준 k8s·Autoscaler·Karpenter taint
`KUBERNETES_CLUSTER_DOMAIN`	service FQDN 도메인 접미사	cluster.local
`CREATE_ANY_SERVICE`	Cluster에 `-any` service 생성	false

INHERITED_ANNOTATIONS·INHERITED_LABELS 는 example.com/* 같은 경로형 wildcard를 지원한다. 조직 공통 label(팀·과금·환경 태그 등)을 Operator가 만드는 모든 하위 리소스에 자동으로 붙이고 싶을 때 유용하다.

설정 예제

두 예제는 동일한 값을 각각 ConfigMap과 Secret으로 표현한 것이다. Secret은 stringData 로 평문 입력하면 Operator가 base64 인코딩을 처리한다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: cnpg-controller-manager-config
  namespace: cnpg-system
data:
  CLUSTERS_ROLLOUT_DELAY: '60'
  ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES: 'true'
  INHERITED_ANNOTATIONS: categories
  INHERITED_LABELS: environment, workload, app
  INSTANCES_ROLLOUT_DELAY: '10'

apiVersion: v1
kind: Secret
metadata:
  name: cnpg-controller-manager-config
  namespace: cnpg-system
type: Opaque
stringData:
  CLUSTERS_ROLLOUT_DELAY: '60'
  ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES: 'true'
  INHERITED_ANNOTATIONS: categories
  INHERITED_LABELS: environment, workload, app
  INSTANCES_ROLLOUT_DELAY: '10'

설정 적용

ConfigMap·Secret을 적용한 뒤 Operator Deployment를 재시작해 다시 읽게 한다.

kubectl rollout restart deployment \
  -n cnpg-system \
  cnpg-controller-manager

Pod를 직접 삭제해 재기동해도 된다.

kubectl delete pods -n cnpg-system \
  -l app.kubernetes.io/name=cloudnative-pg

namespace를 나누고 WATCH_NAMESPACE·ENABLE_WEBHOOK_NAMESPACE_SUFFIX 를 조합하더라도, 하나의 Kubernetes 클러스터에서 CloudNativePG Operator를 여러 개 동시에 돌리는 구성은 지원하지 않는다. 클러스터당 Operator는 하나로 유지한다.

정리

Operator 설정은 cnpg-system의 cnpg-controller-manager-config ConfigMap 또는 Secret으로 전달
같은 파라미터가 양쪽에 있으면 Secret이 우선
변경은 Operator 재시작 후, 이후 생성 리소스에만 반영
INHERITED_LABELS·WATCH_NAMESPACE·rollout delay가 자주 쓰는 항목
클러스터당 Operator는 하나

다음 절(3.4)에서는 Kubernetes 노드를 점검·업그레이드할 때 PostgreSQL을 지키는 유지보수 절차를 본다.

3.2 Image Catalog 3.4 Kubernetes 업그레이드와 유지보수