애노테이션

애노테이션 (Annotations)

쿠버네티스 객체에 "사람이 알아두면 좋은 메타데이터"를 붙이고 싶을 때가 있어요. 그럴 때 쓰는 게 애노테이션(Annotations) 입니다. 애노테이션을 이용하면 객체에 임의의 비식별(non-identifying) 메타데이터를 붙일 수 있고, 도구나 라이브러리 같은 클라이언트가 이 메타데이터를 가져올 수 있어요.

출처: 쿠버네티스 공식 문서 — Annotations

객체에 메타데이터 붙이기 (Attaching metadata to objects)

쿠버네티스 객체에 메타데이터를 붙이는 데는 라벨(labels) 이나 애노테이션(annotations) 을 쓸 수 있어요. 라벨은 객체를 선택하고 특정 조건을 만족하는 객체 컬렉션을 찾는 데 사용됩니다. 반면 애노테이션은 객체를 식별·선택하는 데 쓰지 않아요. 애노테이션의 메타데이터는 작을 수도 크고, 구조적이거나 비구조적일 수도 있으며, 라벨이 허용하지 않는 문자도 포함할 수 있습니다. 같은 객체의 메타데이터에 라벨과 애노테이션을 함께 쓸 수도 있어요.

애노테이션은 라벨처럼 키/값(key/value) 맵입니다:

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

참고: 맵의 키와 값은 반드시 문자열이어야 해요. 즉 숫자·불리언·리스트 같은 다른 타입은 키나 값으로 쓸 수 없습니다.

애노테이션에 기록할 수 있는 정보의 예시:

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

애노테이션 대신 이런 정보를 외부 데이터베이스나 디렉터리에 저장할 수도 있지만, 그러면 배포·관리·내부 관찰(introspection)용 공유 클라이언트 라이브러리와 도구를 만드는 게 훨씬 어려워집니다.

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

애노테이션은 키/값 쌍이에요. 유효한 애노테이션 키는 두 부분으로 나뉩니다: 선택적 접두사(prefix)와 이름(name) 으로, 슬래시(/)로 구분됩니다. 이름 부분은 필수이며 63자 이하여야 하고, 영숫자 문자([a-z0-9A-Z])로 시작·끝나야 하며, 그 사이에 대시(-), 밑줄(_), 점(.)과 영숫자가 올 수 있습니다. 접두사는 선택적입니다. 지정한다면 접두사는 DNS 서브도메인이어야 해요: 점(.)으로 구분된 일련의 DNS 라벨로, 총 253자를 넘지 않고, 슬래시(/)로 끝납니다.

접두사를 생략하면 애노테이션 키는 사용자에게 비공개(private)인 것으로 간주됩니다. 자동화된 시스템 컴포넌트가 이 키를 읽어야 한다면 접두사를 붙여야 해요 .

애노테이션