Kubernetes 레이블(Label)과 어노테이션(Annotation)

y001·2025년 3월 15일

annotations devops kubernetes labels 클라우드운영

MultiCloud(Docker, K8S, AWS)

목록 보기

24/51

Kubernetes에서 리소스를 효율적으로 관리하기 위해 레이블(Label)과 어노테이션(Annotation)을 활용할 수 있다. 이번 글에서는 레이블과 어노테이션의 개념, 차이점, 그리고 실제 활용 사례에 대해 정리해보겠다.

1. 레이블(Label)

레이블은 Kubernetes 리소스를 식별하고 그룹화하는 키-값 쌍으로, 클러스터 내부에서 특정 오브젝트를 빠르게 찾고 필터링하는 기능을 제공한다.

1.1 레이블의 특징

키-값(Key-Value) 형식으로 사용된다.
Pods, Nodes, Deployments, Services 등 모든 Kubernetes 리소스에 적용 가능하다.
색션(Scheduler) 및 셀렉터(Selector)에서 특정 리소스를 선택할 때 사용된다.
하나의 오브젝트에 여러 개의 레이블을 지정할 수 있지만, 같은 키를 중복으로 사용할 수 없다.

1.2 레이블 예제

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  labels:
    env: production
    version: v1
spec:
  containers:
  - name: my-container
    image: nginx

위 예제에서 env: production과 version: v1은 레이블이며, 이를 통해 특정 Pod을 쉽게 검색하고 관리할 수 있다.

1.3 레이블 셀렉터(Label Selector)

레이블 셀렉터를 사용하면 특정 레이블을 가진 리소스를 필터링할 수 있다.

MatchLabels

selector:
  matchLabels:
    env: production

MatchExpressions

selector:
  matchExpressions:
    - key: version
      operator: In
      values: ["v1", "v2"]
    - key: env
      operator: NotIn
      values: ["staging"]

위 예제에서는 version이 v1 또는 v2인 경우를 선택하며, env가 staging인 경우는 제외한다.

2. 어노테이션(Annotation)

어노테이션은 Kubernetes 리소스에 대한 추가적인 메타데이터를 저장하는 역할을 한다. 레이블과 달리 필터링이나 검색에는 사용되지 않으며, 오직 정보 저장 용도로만 활용된다.

2.1 어노테이션의 특징

레이블과 동일한 키-값 형식을 사용하지만 검색 기능이 없다.
관리 및 운영을 위한 추가적인 메타데이터를 제공한다.
로그, 디버깅 정보, 업데이트 기록 등을 저장하는 용도로 사용된다.

2.2 어노테이션 예제

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  annotations:
    kubernetes.io/description: "이 Pod는 프로덕션 환경에서 사용됩니다."
    monitoring: "enabled"
spec:
  containers:
  - name: my-container
    image: nginx

위 예제에서 kubernetes.io/description과 monitoring 어노테이션은 Pod에 대한 추가적인 설명과 모니터링 설정 정보를 담고 있다.

3. 레이블과 어노테이션의 차이점

	레이블(Label)	어노테이션(Annotation)
주요 목적	리소스를 필터링 및 선택하는 기준 제공	부가적인 정보를 제공하는 메타데이터
형식	키-값(Key-Value) 쌍	키-값(Key-Value) 쌍
검색 가능 여부	`kubectl get ... --selector`로 검색 가능	검색 및 필터링 불가능
사용 예시	특정 환경(`env=prod`), 특정 버전(`version=v1`)을 가진 리소스를 찾을 때 사용	업데이트 이력, 로그 기록, 디버깅 정보 저장

4. 결론

레이블(Label)은 Kubernetes 리소스를 검색하고 필터링하는 데 사용되며, 운영 및 배포 전략을 설정하는 중요한 역할을 한다.
어노테이션(Annotation)은 검색 기능 없이 메타데이터를 추가하는 용도로 활용되며, 주로 로깅, 모니터링, 업데이트 기록 등에 사용된다.
적절한 레이블과 어노테이션을 활용하면 Kubernetes 클러스터를 보다 효율적으로 운영할 수 있다.