10.3 Label과 Annotation
Kubernetes에서 label과 annotation은 리소스에 붙는 key-value 메타데이터입니다. 둘의 성격은 다릅니다. label은 셀렉터로 리소스를 골라내기 위한 것이라 값이 짧고 검색 대상이 되며, annotation은 셀렉터에 쓰지 않는 부가 정보라 값이 길거나 구조적일 수 있습니다. CloudNativePG는 자신이 만드는 Pod·PVC·Service·Job 같은 리소스에 정해진 label과 annotation을 붙여, 이 리소스가 어느 클러스터의 무슨 역할인지 스스로 드러냅니다.
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)의 INHERITED_LABELS와 INHERITED_ANNOTATIONS로 상속할 key를 지정합니다.
data:
INHERITED_LABELS: environment, workload, app
INHERITED_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
.spec.inheritedMetadata는 이와 별개로, key와 값을 직접 지정해 하위 리소스에 붙이는 Cluster 필드입니다.
전파 결과는 Pod의 label을 직접 확인해 검증합니다.
kubectl get pods --show-labels
CloudNativePG는 상속된 메타데이터의 삭제는 자동으로 전파하지 않습니다. Cluster에서 label을 지워도 이미 만들어진 리소스에는 그대로 남습니다. 값을 걷어내야 한다면 해당 리소스에서 직접 지우거나 리소스를 재생성합니다.
정리
cnpg.io/cluster·cnpg.io/instanceRole등으로 kubectl 셀렉터를 걸어 리소스를 추립니다hibernation·reconciliationLoop같은 제어 annotation은 잠깐 쓰고 원복합니다- 내 메타데이터를 물려주려면 Operator 설정의
INHERITED_LABELS·INHERITED_ANNOTATIONS에 key를 등록합니다 - 상속된 메타데이터의 삭제는 자동 전파되지 않습니다
이것으로 Part X를 마칩니다.