10.3 Label과 Annotation

Kubernetes에서 label과 annotation은 리소스에 붙는 key-value 메타데이터다. 둘의 성격은 다르다. label은 셀렉터로 리소스를 골라내기 위한 것이라 값이 짧고 검색 대상이 되며, annotation은 셀렉터에 쓰지 않는 부가 정보라 값이 길거나 구조적일 수 있다. CloudNativePG는 자신이 만드는 Pod·PVC·Service·Job 같은 리소스에 정해진 label과 annotation을 붙여, 이 리소스가 어느 클러스터의 무슨 역할인지 스스로 드러낸다.

    flowchart TD
  CL["Cluster CRD"]
  OP["Operator"]
  POD["Pod<br/>cnpg.io/instanceRole"]
  PVC["PVC<br/>cnpg.io/pvcRole"]
  SVC["Service"]
  CL --> OP
  OP -->|label·annotation 부착| POD
  OP -->|label·annotation 부착| PVC
  OP -->|label·annotation 부착| SVC

  classDef node fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  class CL,OP,POD,PVC,SVC node

Operator가 붙이는 label

CloudNativePG가 관리하는 리소스에는 아래 label들이 붙는다. 이 값으로 kubectl 셀렉터를 걸면 원하는 리소스만 추려 낼 수 있다.

label	의미
`cnpg.io/cluster`	소속 Cluster 이름
`cnpg.io/instanceName`	인스턴스 이름
`cnpg.io/instanceRole`	인스턴스 역할 — `primary`·`replica`·`unhealthy`
`cnpg.io/podRole`	Pod 종류 — 인스턴스 Pod와 pooler Pod 구분
`cnpg.io/pvcRole`	PVC 용도 — `PG_DATA`·`PG_WAL`
`cnpg.io/jobRole`	Job 목적 — `import`·`initdb`·`join` 등
`cnpg.io/reload`	값이 바뀌면 자동 reload 대상으로 표시

Kubernetes 표준 label도 함께 붙는다.

label	값
`app.kubernetes.io/managed-by`	`cloudnative-pg`
`app.kubernetes.io/name`	`postgresql`
`app.kubernetes.io/instance`	소속 Cluster 이름

예를 들어 현재 primary Pod만 찾으려면 이렇게 건다.

kubectl get pods -l cnpg.io/cluster=cluster-example,cnpg.io/instanceRole=primary

Operator가 붙이는 annotation

annotation은 셀렉터가 아니라 운영 정보와 제어 스위치로 쓰인다. 자주 마주치는 것들만 추린다.

annotation	쓰임
`cnpg.io/hibernation`	`on`·`off` — 클러스터 휴면 여부
`cnpg.io/reconciliationLoop`	`disabled`이면 Operator 조정을 멈춤
`cnpg.io/reconcilePodSpec`	`disabled`이면 spec 변경 시 Pod 재시작을 막음
`cnpg.io/fencedInstances`	fencing 대상 인스턴스 목록(JSON)
`cnpg.io/skipWalArchiving`	`enabled`이면 WAL 아카이빙을 건너뜀
`cnpg.io/operatorVersion`	리소스를 만든 Operator 버전
`cnpg.io/nodeSerial`	클러스터 안 인스턴스 일련번호

cnpg.io/reconciliationLoop: disabled나 cnpg.io/fencedInstances 같은 annotation은 Operator의 자동 조정을 의도적으로 멈추는 강력한 스위치다. 트러블슈팅 중 잠깐 쓰고 반드시 원복하는 용도이지, 상시로 걸어 두는 값이 아니다. 켜 둔 채 방치하면 장애가 나도 self-healing이 동작하지 않는다.

내 label·annotation 물려주기

조직 공통 label(예: environment, team, 비용 태그)을 클러스터가 만드는 모든 리소스에 붙이고 싶을 때가 있다. 그런데 CloudNativePG는 기본적으로 Cluster의 메타데이터를 하위 리소스로 자동 전파하지 않는다. 어떤 key를 물려줄지 Operator 설정에서 명시해야 한다.

Operator 설정(ConfigMap 또는 Secret)에서 inheritedMetadata로 상속할 key를 지정한다.

inheritedMetadata:
  labels:
    - environment
    - workload
    - app
  annotations:
    - categories

mycompany/* 같은 와일드카드 패턴도 쓸 수 있다. 이렇게 설정한 뒤 Cluster에 해당 메타데이터를 달면, Operator가 하위 리소스로 값을 전파한다.

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
  labels:
    environment: production
    workload: database
    app: sso
  annotations:
    categories: database
spec:
  instances: 3

전파 결과는 Pod의 label을 직접 확인해 검증한다.

kubectl get pods --show-labels

CloudNativePG는 상속된 메타데이터의 삭제는 자동으로 전파하지 않는다. Cluster에서 label을 지워도 이미 만들어진 리소스에는 그대로 남는다. 값을 걷어내야 한다면 해당 리소스에서 직접 지우거나 리소스를 재생성한다.

정리

label은 셀렉터로 고르는 짧은 키, annotation은 부가 정보·제어 스위치
cnpg.io/cluster·cnpg.io/instanceRole 등으로 kubectl 셀렉터를 걸어 리소스를 추린다
hibernation·reconciliationLoop 같은 제어 annotation은 잠깐 쓰고 원복한다
내 메타데이터를 물려주려면 Operator의 inheritedMetadata에 key를 등록한다
상속된 메타데이터의 삭제는 자동 전파되지 않는다

이것으로 Part X를 마친다. 다음 Part XI에서는 cnpg 플러그인과 fencing·hibernation 같은 실제 운영 도구, 그리고 문제 해결을 다룬다.

10.2 로깅