이제 나도 클라우드 네이티브 전문가: 쿠버네티스 구축부터 운영 완전 정복

앞서 레이블(Labels)을 사용하여 쿠버네티스 오브젝트를 식별하고 그룹화하는 방법을 배웠습니다. 레이블은 마치 오브젝트의 ‘이름표’나 ‘분류 태그’와 같아서, 셀렉터(Selectors)를 통해 원하는 오브젝트를 찾아내고 연결하는 데 핵심적인 역할을 합니다. 하지만 때로는 오브젝트를 식별하거나 선택하는 목적이 아닌, 부가적인 정보나 설명을 오브젝트에 첨부하고 싶을 때가 있습니다. 예를 들어, 이 오브젝트를 빌드한 도구의 버전 정보, 마지막으로 수정한 사람의 연락처, 또는 특정 운영 정책에 대한 설명 등을 기록해두고 싶을 수 있습니다. 바로 이러한 목적을 위해 사용되는 것이 어노테이션(Annotations)입니다. 이번 섹션에서는 어노테이션이 무엇이며, 레이블과는 어떻게 다르고, 주로 어떤 용도로 활용되는지 자세히 알아보겠습니다. 어노테이션은 쿠버네티스 오브젝트에 마치 ‘주석’이나 ‘메모’를 달아두는 것과 같아서, 사람이나 다른 도구들이 오브젝트를 이해하고 관리하는 데 유용한 추가 정보를 제공할 수 있습니다.

• 어노테이션(Annotations)은 레이블과 마찬가지로 쿠버네티스 오브젝트의 metadata 필드 아래에 키-값 쌍(key-value pairs) 형태로 저장되는 메타데이터입니다. 하지만 레이블과는 결정적인 차이점이 있습니다. 레이블은 오브젝트를 식별하고 선택(selecting)하는 데 사용되는 반면, 어노테이션은 그러한 식별 목적이 아닌, 임의의 비식별(non-identifying) 메타데이터를 저장하기 위해 사용됩니다. 즉, 쿠버네티스 시스템 자체는 어노테이션의 내용을 직접 해석하거나 사용하여 오브젝트를 그룹화하거나 필터링하지 않습니다. 어노테이션은 주로 사람 운영자나 외부 도구, 라이브러리, 또는 컨트롤러들이 참조하거나 특정 동작을 트리거하기 위한 정보를 담는 데 활용됩니다.
• 어노테이션의 특징 및 구문:
  • 레이블과 마찬가지로 키와 값으로 구성되며, 하나의 오브젝트에 여러 개의 어노테이션을 가질 수 있습니다.
  • 어노테이션 키도 레이블 키와 유사하게 도메인 접두사(선택 사항)와 이름 부분으로 구성될 수 있습니다. 다른 도구나 시스템과의 충돌을 피하기 위해, 특정 도구나 시스템에서 사용하는 어노테이션은 고유한 접두사(예: example.com/my-annotation)를 사용하는 것이 권장됩니다.
  • 레이블 값과는 달리, 어노테이션 값은 훨씬 더 크고 복잡한 데이터(예: 긴 설명 문자열, JSON 블록, 심지어 Base64로 인코딩된 바이너리 데이터 등)를 포함할 수 있습니다. (물론 전체 어노테이션의 크기에는 제한이 있습니다. 보통 수백 KB에서 1MB 내외로, etcd의 요청 크기 제한에 영향을 받습니다.)
  • 어노테이션은 오브젝트의 metadata 필드 아래 annotations 맵(map)에 정의됩니다. 예를 들어, 디플로이먼트 매니페스트 파일에서 다음과 같이 어노테이션을 정의할 수 있습니다.
    클립보드에 복사

    Syntax HighlighterapiVersion: apps/v1 kind: Deployment metadata: name: my-app-deployment annotations: build-timestamp: "2023-10-27T10:30:00Z" contact-person: "Alice <alice@example.com>" description: "This deployment manages the frontend web servers for the new e-commerce platform." monitoring.example.com/scrape-port: "9102" # 특정 모니터링 도구를 위한 정보 kubernetes.io/change-cause: "Updated image to version 1.5.2 for bug fixes." # kubectl set image 시 자동 추가 가능 spec: # ... 디플로이먼트 명세 ...
• 레이블과의 주요 차이점 요약:

  특징	레이블 (Labels)	어노테이션 (Annotations)
  주요 목적	오브젝트 식별 및 선택 (Grouping & Selecting)	비식별 메타데이터 저장 (Describing & Informing)
  값의 크기	작고 간결한 값 (식별자 역할)	크고 복잡한 데이터 가능 (설명, 설정 정보 등)
  시스템 사용	셀렉터에 의해 쿠버네티스 시스템이 적극적으로 사용	쿠버네티스 시스템은 직접 사용하지 않음 (도구나 사용자 참조용)
  구문 제약	값에 대한 문자 규칙이 상대적으로 엄격함	값에 대한 문자 규칙이 상대적으로 유연함

  이처럼 레이블과 어노테이션은 서로 다른 목적을 가지고 있으며, 각각의 용도에 맞게 사용하는 것이 중요합니다. 오브젝트를 그룹화하거나 선택해야 한다면 레이블을, 그렇지 않은 부가 정보를 저장하고 싶다면 어노테이션을 사용해야 합니다.

어노테이션은 그 유연성 덕분에 매우 다양한 방식으로 활용될 수 있습니다. 쿠버네티스 시스템 자체가 직접 사용하지는 않지만, 어노테이션에 담긴 정보는 다음과 같이 다양한 도구나 시스템, 또는 운영상의 편의를 위해 중요한 역할을 합니다.

1. 빌드, 릴리스, 배포 정보 기록:
   • 애플리케이션이나 오브젝트의 빌드 타임스탬프, 커밋 해시, 릴리스 버전, CI/CD 파이프라인 ID 등 빌드 및 배포와 관련된 정보를 어노테이션으로 기록해 둘 수 있습니다. 이는 추후 문제 발생 시 특정 빌드나 릴리스와 연관 짓거나, 변경 이력을 추적하는 데 도움이 됩니다.
   • 예: build-id: “pipeline-run-12345”, git-commit-sha: “abcdef1234567890”
2. 헬름(Helm), 커스터마이즈(Kustomize) 등 배포 도구의 메타데이터:
   • 헬름 차트나 커스터마이즈와 같은 쿠버네티스 패키지 매니저 및 설정 관리 도구들은 자신들이 관리하는 리소스에 대한 정보를 어노테이션으로 저장하곤 합니다. 예를 들어, 헬름은 릴리스 이름, 차트 버전 등의 정보를 어노테이션에 기록하여 해당 리소스가 어떤 헬름 릴리스에 의해 관리되는지 식별합니다.
   • 예: meta.helm.sh/release-name: “my-wordpress-release”, meta.helm.sh/release-namespace: “default”
3. 운영 및 관리 편의를 위한 정보:
   • 오브젝트 담당자의 연락처 정보, 운영 가이드 문서 링크, 장애 발생 시 참고할 만한 정보, 또는 해당 리소스의 사용 목적이나 특이사항에 대한 설명을 어노테이션으로 남겨둘 수 있습니다. 이는 팀 내 협업이나 인수인계 시 매우 유용합니다.
   • 예: owner: “DevOps Team devops@example.com“, documentation: “https://internal-wiki.example.com/my-app-guide“
4. 특정 컨트롤러나 오퍼레이터의 동작 트리거 또는 설정:
   • 일부 커스텀 컨트롤러나 오퍼레이터(Operator)는 특정 어노테이션의 존재 유무나 그 값을 기준으로 특별한 동작을 수행하거나 설정을 변경하기도 합니다. 예를 들어, 특정 어노테이션이 설정된 파드에 대해서만 사이드카 컨테이너를 자동으로 주입(inject)하는 오퍼레이터가 있을 수 있습니다. 또는, 인그레스 컨트롤러가 특정 어노테이션을 참조하여 리다이렉션 규칙이나 인증 설정을 적용할 수도 있습니다.
   • 예: nginx.ingress.kubernetes.io/rewrite-target: “/” (Nginx 인그레스 컨트롤러 설정), sidecar.istio.io/inject: “true” (Istio 서비스 메쉬 사이드카 주입 설정)
5. kubectl 명령어의 변경 원인 기록:
   • kubectl apply –record (현재는 deprecated 되었지만 유사한 기능은 kubectl annotate 등으로 구현 가능) 또는 kubectl set image –record 와 같이 변경 이력을 기록하는 옵션을 사용하면, 해당 변경을 유발한 kubectl 명령어가 어노테이션(kubernetes.io/change-cause)으로 기록됩니다. 이를 통해 kubectl rollout history 명령으로 디플로이먼트의 변경 이력을 확인할 때 각 리비전(revision)이 어떤 이유로 변경되었는지 파악하는 데 도움이 됩니다.
6. 리소스 할당량 및 제한 관련 정보 (예: 클러스터 오토스케일러):
   • 클러스터 오토스케일러와 같은 도구는 특정 파드나 노드에 대한 스케일링 정책이나 제외 규칙 등을 어노테이션을 통해 설정받기도 합니다.
   • 예: cluster-autoscaler.kubernetes.io/safe-to-evict: “false” (이 파드는 자동으로 축출되지 않도록 설정)
7. 디버깅 및 로깅 수준 제어:
   • 특정 컴포넌트의 디버깅을 활성화하거나 로깅 수준을 동적으로 변경하기 위한 플래그를 어노테이션으로 전달하는 경우도 있습니다.

어노테이션 관리:

레이블과 마찬가지로 어노테이션도 kubectl 명령어를 통해 추가, 수정, 삭제할 수 있습니다.

• 어노테이션 추가/수정: kubectl annotate <resource-type> <resource-name> <key>=<value> [–overwrite]
  • 예: kubectl annotate pod my-pod description=”This is a test pod”
  • -overwrite 옵션을 사용하면 이미 존재하는 어노테이션 키의 값을 덮어쓸 수 있습니다.
• 어노테이션 삭제: kubectl annotate <resource-type> <resource-name> <key>- (키 이름 뒤에 -를 붙임)
  • 예: kubectl annotate pod my-pod description-
• 매니페스트 파일의 metadata.annotations 필드를 직접 수정하고 kubectl apply -f <filename.yaml> 명령을 실행하여 어노테이션을 관리하는 것이 일반적입니다.

결론적으로, 어노테이션은 쿠버네티스 오브젝트에 ‘맥락’과 ‘이야기’를 더해주는 강력한 도구입니다. 레이블이 오브젝트의 ‘신분증’이라면, 어노테이션은 그 신분증 뒷면에 적힌 ‘부가 설명’과 같습니다. 비록 쿠버네티스 시스템이 직접적으로 어노테이션의 의미를 해석하지는 않지만, 어노테이션은 사람 운영자, 자동화 도구, 그리고 확장된 쿠버네티스 생태계의 다양한 컴포넌트들이 오브젝트를 더욱 풍부하게 이해하고 지능적으로 상호작용할 수 있도록 하는 중요한 역할을 수행합니다. 효과적인 어노테이션 활용은 클러스터 운영의 투명성을 높이고, 문제 해결을 용이하게 하며, 다양한 자동화 시나리오를 가능하게 만드는 데 기여할 것입니다. 따라서 어노테이션의 존재와 그 잠재적인 활용 가치를 이해하는 것은 쿠버네티스를 좀 더 깊이 있게 사용하는 데 중요한 부분입니다.