📝 Kubernetes Annotation 완전 정리

Kubernetes에는 리소스에 메타데이터를 붙이는 두 가지 방식이 있다.

• Label
• Annotation

라벨이 “선택과 그룹핑” 용도라면
어노테이션은 “부가 정보 저장” 용도다.

---

📌 Annotation이란?

Annotation은 Kubernetes 리소스에 붙일 수 있는 임의의 Key-Value 메타데이터다.

예시:

metadata:
  annotations:
    description: "nginx web server"
    owner: "platform-team"

특징

• selector로 사용 불가
• 필터링 대상 아님
• 비교적 큰 데이터 저장 가능
• 설명, 설정값, 도구 연동 정보 등에 사용

---

🔎 Label vs Annotation 차이

구분	Label	Annotation
목적	선택 / 그룹핑	설명 / 부가정보
selector 사용	가능	불가능
데이터 크기	짧은 값 권장	상대적으로 큰 값 가능
사용 예	app=v1	배포 히스토리, 설정값

---

📦 Annotation 추가하기

kubectl annotate po nginx description="nginx web pod"

---

📦 기존 Annotation 수정하기

이미 존재하면 에러가 발생한다.

kubectl annotate po nginx description="new value" --overwrite

---

🗑 Annotation 삭제하기

🔹 단일 Annotation 삭제

kubectl annotate po nginx description-

키 뒤에 -를 붙이면 삭제된다.

---

🔹 여러 개 Annotation 동시에 삭제

kubectl annotate po nginx description- owner-

공백으로 여러 키를 나열하면 된다.

---

🔹 조건에 맞는 리소스에서 여러 개 삭제

예:

kubectl annotate po -l app=web description- owner-

→ app=web 라벨을 가진 모든 Pod에서
→ description, owner annotation 제거

---

📌 삭제 문법 정리

작업	명령
단일 삭제	kubectl annotate po name key-
여러 개 삭제	kubectl annotate po name key1- key2-
조건부 일괄 삭제	kubectl annotate po -l selector key1- key2-

---

🔥 실제 활용 예

Ingress 설정:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /

배포 기록:

kubectl.kubernetes.io/last-applied-configuration

Helm, ArgoCD, Prometheus 등
많은 도구가 Annotation을 설정 전달용으로 사용한다.

---

🎯 언제 Annotation을 써야 할까?

✔ 필터링이 필요 없다
✔ 설명이나 설정값 저장 목적
✔ 긴 문자열 또는 JSON 저장
✔ 외부 컨트롤러가 참고하는 값

트래픽 선택이나 정책 적용 대상이면 Label을 사용해야 한다.

---

🏁 한 줄 정리

• Label은 선택과 그룹핑
• Annotation은 설명과 설정 전달
• 여러 개 삭제는 key1- key2- 형태로 가능

역할을 구분하면 Kubernetes 리소스 관리가 훨씬 명확해진다.