K8s 레이블 vs 어노테이션

1 개요[ | ]

레이블(label)과 어노테이션(annotation)은 쿠버네티스 오브젝트에 메타데이터를 부여하기 위한 두 가지 방식이다.
두 속성 모두 metadata 필드에 key:value 쌍 형태로 정의된다. 여기서 키(key)는 선택적 prefix와 필수 name으로 구성된 prefix/name 구조를 따르며, 전체 길이는 최대 253자이고 name 부분은 63자 이하여야 한다.

구분	레이블	어노테이션
주요 용도	리소스 식별·선택·분류 스케줄링, 서비스 연결, 버전·릴리즈 구분	리소스 부가 정보 저장 빌드·배포 정보, 외부 시스템 메타데이터, 컨트롤러 동작 힌트
셀렉터 지원	O	X
키 길이	최대 253자	최대 253자
값 길이	최대 63자	최대 262144자 (256KiB, JSON 등 보관 가능)
Well-known 예시	`app.kubernetes.io/name: mysql` `app.kubernetes.io/instance: wordpress-123`	`kubectl.kubernetes.io/default-container: web` `ingressclass.kubernetes.io/is-default-class: "true"`
커스텀 예시	`environment: production` `tier: frontend` `disktype: ssd`	`example.com/last-deployed: 2025-09-05` `example.com/owner: alice`
kubectl	`kubectl label` `kubectl get --show-labels`	`kubectl annotate`