어노테이션

어노테이션 (Annotations)

쿠버네티스 어노테이션을 사용해 객체에 임의의 비식별(non-identifying) 메타데이터를 붙일 수 있어요. 도구와 라이브러리 같은 클라이언트는 이 메타데이터를 검색할 수 있어요.

출처: 문서

본문

객체에 메타데이터 붙이기

쿠버네티스 객체에 메타데이터를 붙이려면 라벨(labels)이나 어노테이션(annotations)을 사용할 수 있어요. 라벨은 객체를 선택하고 특정 조건을 만족하는 객체 모음을 찾는 데 사용할 수 있어요. 반면 어노테이션은 객체를 식별하고 선택하는 데 사용되지 않아요. 어노테이션의 메타데이터는 작을 수도 클 수도 있고, 구조적일 수도 비구조적일 수도 있으며, 라벨이 허용하지 않는 문자를 포함할 수도 있어요. 같은 객체의 메타데이터에 라벨과 어노테이션을 모두 사용할 수 있어요.

어노테이션은 라벨처럼 키/값 맵이에요.

"metadata": {
  "annotations": {
    "key1" : "value1",
    "key2" : "value2"
  }
}

참고:

어노테이션에 기록될 수 있는 정보의 몇 가지 예는 다음과 같아요.

  • 선언적 구성 계층이 관리하는 필드: 이 필드를 어노테이션으로 붙이면 클라이언트나 서버가 설정한 기본값, 자동 생성된 필드, 자동 크기 조정 시스템이 설정한 필드와 구분할 수 있어요.
  • 빌드, 릴리스, 또는 이미지 정보: 타임스탬프, 릴리스 ID, git 브랜치, PR 번호, 이미지 해시, 레지스트리 주소 등.
  • 로깅, 모니터링, 분석, 또는 감사 저장소에 대한 포인터.
  • 디버깅 목적으로 사용할 수 있는 클라이언트 라이브러리 또는 도구 정보: 예를 들어 이름, 버전, 빌드 정보.
  • 사용자 또는 도구/시스템 출처(provenance) 정보: 다른 생태계 구성 요소에서 온 관련 객체의 URL 같은 것.
  • 가벼운 롤아웃 도구 메타데이터: 예를 들어 구성 또는 체크포인트.
  • 책임자 전화번호나 페이저 번호, 또는 팀 웹사이트처럼 그 정보를 찾을 수 있는 위치를 지정하는 디렉터리 항목.
  • 동작을 수정하거나 비표준 기능을 사용하도록 구현에 대한 최종 사용자 지시문.

어노테이션 대신 이런 정보를 외부 데이터베이스나 디렉터리에 저장할 수도 있지만, 그러면 배포, 관리, 내부 검사 등을 위한 공유 클라이언트 라이브러리와 도구를 만드는 것이 훨씬 어려워져요.

구문과 문자 집합 (Syntax and character set)

어노테이션은 키/값 쌍이에요. 유효한 어노테이션 키에는 두 부분이 있어요: 선택적 접두사와 이름으로, 슬래시(/)로 구분돼요. 이름 부분은 필수이며 63자 이하여야 하고, 영숫자 문자([a-z0-9A-Z])로 시작하고 끝나야 하며 그 사이에 대시(-), 밑줄(_), 점(.)과 영숫자가 올 수 있어요. 접두사는 선택 사항이에요. 지정하면 접두사는 DNS 하위 도메인이어야 해요: 점(.)으로 구분된 DNS 라벨의 연속으로, 총 253자 이하여야 하고 슬래시(/)가 뒤따라야 해요.

접두사가 생략되면 어노테이션 키는 사용자에게 사적인 것으로 간주돼요. 최종 사용자 객체에 어노테이션을 추가하는 자동화된 시스템 구성 요소(예: kube-scheduler, kube-controller-manager, kube-apiserver, kubectl, 또는 다른 서드파티 자동화)는 접두사를 지정해야 해요.

kubernetes.io/와 k8s.io/ 접두사는 쿠버네티스 핵심 구성 요소용으로 예약돼 있어요.

유효한 어노테이션 값에는 문자 집합 제한이 없어요. 라벨 값과 달리 어노테이션 값은 특수 문자, 공백, JSON이나 YAML 같은 구조적 데이터를 포함한 어떤 문자열이든 포함할 수 있어요. 이진 데이터(예: CBOR)를 저장할 계획이라면 쿠버네티스 프로젝트는 base64로 인코딩할 것을 권장해요. 하지만 단일 객체의 모든 어노테이션의 총 크기(키와 값을 합친)는 256 KiB를 초과할 수 없어요.

예를 들어 imageregistry: https://hub.docker.com/ 어노테이션이 있는 파드의 매니페스트는 다음과 같아요.

apiVersion: v1
kind: Pod
metadata:
  name: annotations-demo
  annotations:
    imageregistry: "https://hub.docker.com/"
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

더 알아보기 (Learn more)