Kubernetes 시스템 컴포넌트 메트릭

Kubernetes 시스템 컴포넌트 메트릭 (Metrics For Kubernetes System Components)

시스템 컴포넌트 메트릭은 컴포넌트 내부에서 무슨 일이 일어나는지 더 잘 들여다보게 해줘요. 특히 대시보드와 알림을 만들 때 유용하죠. Kubernetes 컴포넌트는 Prometheus 형식으로 메트릭을 방출해요. 이 형식은 사람과 기계가 모두 읽을 수 있게 설계된 구조화된 평문이에요.

Kubernetes의 메트릭

대부분의 메트릭은 HTTP 서버의 /metrics 엔드포인트에서 확인할 수 있어요. 기본으로 엔드포인트를 노출하지 않는 컴포넌트는 --bind-address 플래그로 활성화할 수 있어요. 예:

  • kube-controller-manager
  • kube-proxy
  • kube-apiserver
  • kube-scheduler
  • kubelet

운영 환경에서는 Prometheus Server 같은 메트릭 수집기를 주기적으로 실행해 메트릭을 시계열 데이터베이스에 저장하도록 구성하세요. kubelet은 /metrics/cadvisor, /metrics/resource, /metrics/probes 엔드포인트에서도 메트릭을 노출해요.

클러스터가 RBAC를 쓴다면 메트릭을 읽으려면 /metrics에 접근을 허용하는 ClusterRole을 가진 사용자/그룹/ServiceAccount의 인가가 필요해요.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus
rules:
  - nonResourceURLs:
      - "/metrics"
    verbs:
      - get

메트릭 수명주기

Alpha 메트릭 → Beta 메트릭 → Stable 메트릭 → Deprecated 메트릭 → Hidden 메트릭 → Deleted 메트릭

  • Alpha: 안정성 보장이 없어 언제든 수정·삭제될 수 있어요.
  • Beta: 라벨을 제거할 수 없지만 추가는 가능해요.
  • Stable: 변경되지 않음을 보장해요. deprecated 시그니처가 없는 stable 메트릭은 삭제·이름 변경되지 않고, 타입도 수정되지 않아요.
  • Deprecated: 삭제 예정이지만 아직 사용 가능하며, deprecated된 버전 주석을 포함해요.
  • Hidden: 더 이상 스크랩용으로 게시되지 않지만, --show-hidden-metrics-for-version 플래그로 활성화하면 사용할 수 있어요. STABLE은 최소 3개 릴리스 또는 9개월(더 긴 쪽), BETA는 최소 1개 릴리스 또는 4개월(더 긴 쪽) 후 hidden이 돼요.
  • Deleted: 더 이상 게시되지도 않고 사용할 수도 없어요.

예를 들어 메트릭 A가 1.29에서 deprecated됐다면, ALPHA는 1.29에 hidden될 수 있고, BETA는 1.30부터(그때 --show-hidden-metrics-for-version=1.29 사용), STABLE은 1.32부터(그때 --show-hidden-metrics-for-version=1.31 사용) hidden됩니다.

컴포넌트 메트릭

kube-controller-manager 메트릭

컨트롤러 매니저의 성능과 상태를 보여줘요. Go 런타임 메트릭(goroutine 수 등)과 etcd 요청 지연, Cloudprovider(AWS, GCE, OpenStack) API 지연 같은 컨트롤러별 메트릭을 포함해요.

kube-scheduler 메트릭

FEATURE STATE: Kubernetes v1.21 [beta]

실행 중인 모든 Pod의 요청 리소스와 원하는 limit을 보고하는 옵셔널 메트릭을 노출해요. kube_pod_resource_request와 kube_pod_resource_limit 메트릭이 그것이며, /metrics/resources 엔드포인트에서 노출돼요. namespace, pod name, node, priority, 리소스 이름(cpu 등), 단위(cores 등)로 라벨링돼요.

kubelet Pressure Stall Information (PSI) 메트릭

FEATURE STATE: Kubernetes v1.36 [stable](기본 활성화)

커널이 PSI를 지원하면(4.20+) kubelet이 CPU/메모리/I-O 사용에 대한 PSI를 노드·Pod·컨테이너 수준에서 수집해요. /metrics/cadvisor에는 누적 카운터(container_pressure_cpu_stalled_seconds_total 등)로, /stats/summary에는 누적 total과 이동 평균(avg10, avg60, avg300)을 JSON으로 노출해요.

some avg10=0.00 avg60=0.00 avg300=0.00 total=0
full avg10=0.00 avg60=0.00 avg300=0.00 total=0

예를 들어 cpu.some avg10이 0.74라면 지난 10초 동안 그 컨테이너의 최소 한 작업이 CPU에서 0.74% 시간 동안 지연됐다는 뜻이에요. avg10이 avg300보다 훨씬 높으면 최근에 리소스 경합이 급증했음을 의미해요. full 값이 0이 아니면 모든 비idle 작업이 동시에 지연된 것이라 더 심각한 문제예요.

요구사항: PSI는 Linux 커널 4.20+와 cgroup v2가 필요해요.

메트릭 비활성화

--disabled-metrics 플래그로 명시적으로 메트릭을 끌 수 있어요 (예: --disabled-metrics=metric1,metric2).

메트릭 카디널리티 강제

무한 차원의 메트릭은 메모리 문제를 일으킬 수 있어요. --allow-metric-labels 옵션으로 메트릭에 허용할 라벨 값의 allow-list를 구성할 수 있어요.

--allow-metric-labels number_count_metric,odd_number='1,3,5', ...

더 알아보기 (Learn more)