[Kubernetes] 어노테이션

Kubernetes 어노테이션은 리소스의 부가정보를 제공합니다. 레이블과 유사하지만 더 많은 메타데이터를 저장하고 비식별 메타데이터를 오브젝트에 첨부할 수 있습니다. 클라이언트는 이 메타데이터를 검색할 수 있습니다.

어노테이션에는 다음과 같은 정보가 포함될 수 있습니다.

• 리소스 구성에 대한 추가 정보
• 인증 정보
• 클러스터 또는 네임스페이스 수준의 설정 정보
• 빌드 또는 배포에 대한 버전 정보

어노테이션은 일반적으로 클러스터 관리자 또는 개발자가 사용합니다. 어노테이션을 사용하여 리소스를 더 잘 추적하고, 리소스 간의 관계를 더 잘 이해하며, 리소스를 더 효과적으로 관리할 수 있습니다.

오브젝트에 메타데이터 첨부

쿠버네티스 오브젝트에는 메타데이터를 첨부할 수 있습니다. 레이블을 사용하여 오브젝트를 선택하고, 특정 조건을 만족하는 오브젝트 컬렉션을 찾을 수 있습니다. 어노테이션은 오브젝트를 식별하고 선택하는데 사용되지 않으며, 메타데이터의 크기와 구조는 다양합니다. 어노테이션에는 레이블에서 허용되지 않는 문자를 포함할 수 있습니다.

어노테이션은 레이블과 같이 키/값 맵 구조입니다.

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

💡 맵의 키와 값은 문자열이어야 합니다. 이 말은 즉, 숫자, 불리언, 리스트 등 다른 형식을 키나 값으로 사용할 수 없다는 것입니다.

다음은 어노테이션에 기록할 수 있는 정보의 예시입니다:

• 필드는 선언적 구성 계층에 의해 관리됩니다. 어노테이션으로 첨부하는 필드는 클라이언트나 서버가 설정한 기본 값, 자동 생성된 필드, 오토사이징/오토스케일링 시스템에서 설정한 필드와 구분됩니다.
• 이미지 정보: 빌드, 릴리스, 타임 스탬프, 릴리스 ID, git 브랜치, PR 번호, 이미지 해시, 레지스트리 주소 등
• 로깅, 모니터링, 분석, 감사 리포지터리에 대한 포인터
• 디버깅 목적으로 사용될 수 있는 클라이언트 라이브러리나 도구 정보: 예를 들어 이름, 버전, 빌드 정보 등
• 다른 생태계 구성 요소의 관련 오브젝트 URL 등 사용자나 도구/시스템 출처 정보
• 경량 롤아웃 도구 메타데이터: 구성, 체크포인트 등
• 책임자의 전화번호나 호출기 번호, 팀 웹 사이트 등 해당 정보를 찾을 수 있는 디렉터리 진입점
• 최종 사용자의 지시 사항: 행동 수정 또는 비표준 기능 수행 등

이 유형의 정보를 어노테이션 대신 외부 데이터베이스나 디렉터리에 저장할 수 있지만, 이는 배포, 관리, 인트로스펙션 등을 위한 공유 클라이언트 라이브러리와 도구 생성을 훨씬 더 어렵게 만들 수 있습니다.

문법과 캐릭터 셋

어노테이션은 키/값 쌍으로, 유효한 어노테이션 키에는 두 개의 세그먼트가 있습니다. 이름 세그먼트는 필수이며, 영문 숫자([a-z0-9A-Z])로 시작하고 끝나는 63자 이하이어야 합니다. 접두사는 선택적이며, 지정된 경우 접두사는 DNS 서브도메인이어야 합니다. 어노테이션 키에는 대시(-), 밑줄(_), 점(.)이 들어갈 수 있습니다.

접두사가 생략될 경우 어노테이션 키는 사용자에게 비공개로 간주됩니다. 자동화된 시스템 구성 요소(예: kube-scheduler, kube-controller-manager, kube-apiserver, kubectl, 또는 다른 써드파티 자동화)는 어노테이션을 추가할 때 접두사를 지정해야 합니다.

kubernetes.io/와 k8s.io/ 접두사는 쿠버네티스 핵심 구성 요소를 위해 예약되어 있습니다.

어노테이션은 다음과 같은 방법으로 정의할 수 있습니다.

apiVersion: {API 버전}
kind: {리소스 종류}
metadata:
  annotations:
    {어노테이션 이름 1}: {값 1}
    {어노테이션 이름 2}: {값 2}

다음은 Pod에 어노테이션을 정의하는 예시입니다.

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    description: "This is my Pod."
    version: "1.0.0"

다음은 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

어노테이션은 다음과 같은 방법으로 조회할 수 있습니다.

kubectl describe {리소스 종류} {리소스 이름}

예를 들어, 다음과 같이 my-pod Pod의 어노테이션을 조회할 수 있습니다.

kubectl describe pod my-pod

어노테이션은 리소스의 메타데이터에 저장되기 때문에, 리소스를 삭제하면 어노테이션도 함께 삭제됩니다. 따라서, 어노테이션을 사용하기 전에 어노테이션을 저장할 리소스를 신중하게 선택해야 합니다.

레퍼런스

https://kubernetes.io/ko/docs/concepts/overview/working-with-objects/annotations/