본문으로 건너뛰기

3.3 Operator 설정

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

경고

설정 변경은 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_DELAYCluster 업그레이드 사이 대기(초)0
INSTANCES_ROLLOUT_DELAY같은 Cluster 내 인스턴스 사이 대기(초)0
ENABLE_INSTANCE_MANAGER_INPLACE_UPDATESinstance 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_DOMAINservice FQDN 도메인 접미사cluster.local
CREATE_ANY_SERVICECluster에 -any service 생성false
노트

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

설정 예제​

두 예제는 동일한 값을 각각 ConfigMap과 Secret으로 표현한 것입니다. Secret은 stringData에 평문으로 적으면 Kubernetes API 서버가 data(base64)로 변환해 저장합니다.

ConfigMap​

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'

Secret​

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는 하나.