Prometheus로 kube-controllers 모니터링하기

원문 보기 위키 갱신 2026.10.11

kube-controllers는 Prometheus를 통해 여러 메트릭을 보고하도록 구성할 수 있어요. 이 문서는 reconcile 지연 시간과 큐 깊이 등 kube-controllers가 내보내는 메트릭의 참조 자료예요. IPAM 관련 메트릭과 레이블 의미, 그리고 Go 런타임·프로세스 기본 메트릭 목록을 확인할 수 있어요.

출처: 문서

본문

kube-controllers는 Prometheus를 통해 여러 메트릭을 보고하도록 구성할 수 있어요. 이 보고는 기본적으로 포트 9094에서 활성화돼요. 메트릭 보고 구성을 바꾸는 방법(또는 완전히 비활성화하는 방법)은 구성 참조를 참고하세요.

메트릭 참조

kube-controllers 전용

kube-controllers는 여러 Prometheus 메트릭을 내보내요. 현재 제공되는 메트릭은 다음과 같아요. 일부 메트릭은 kube-controllers 내부의 특정 구현 방식에 묶여 있기 때문에, 릴리스가 바뀌어도 메트릭이 반드시 유지된다는 강한 보장은 드릴 수 없어요. 다만 기존 메트릭을 불필요하게 변경하지 않도록 노력하고 있어요.

메트릭 이름	레이블	설명
`ipam_allocations_in_use`	ippool, node	워크로드나 인터페이스가 현재 사용 중인 Calico IP 할당 수예요.
`ipam_allocations_borrowed`	ippool, node	현재 사용 중인 Calico IP 할당 중, 다른 노드의 블록 어피니티에서 빌려온(borrowed) 할당 수예요.
`ipam_allocations_gc_candidates`	ippool, node	GC가 잠재적 누수로 표시해 둔 Calico IP 할당 수예요. 정상적인 GC 동작에서는 이 메트릭이 0으로 돌아가요.
`ipam_allocations_gc_reclamations`	ippool, node	GC가 회수한 Calico IP 할당 수예요. 정상 동작에서는 이 카운터의 증가가 candidates 게이지의 감소와 대응돼요.
`ipam_blocks`	ippool, node	IPAM 블록 수예요.
`ipam_ippool_size`	ippool	IP Pool CIDR에 포함된 IP 주소 수예요.
`ipam_blocks_per_node`	node	어피니티를 가진 노드별로 색인된 IPAM 블록 수예요. 새 통합에서는 `ipam_blocks`를 사용하는 것이 좋아요.
`ipam_allocations_per_node`	node	할당이 이루어진 노드별로 색인된 Calico IP 할당 수예요. 새 통합에서는 `ipam_allocations_in_use`를 사용하는 것이 좋아요.
`ipam_allocations_borrowed_per_node`	node	어피니티가 없는(non-affine) 블록에서 빌려온 Calico IP 할당 수로, 할당이 이루어진 노드별로 색인돼요. 새 통합에서는 `ipam_allocations_borrowed`를 사용하는 것이 좋아요.

레이블은 다음과 같이 해석할 수 있어요.

레이블 이름	설명
`node`	할당 메트릭의 경우 할당이 이루어진 노드예요. 블록 메트릭의 경우 블록이 어피니티를 가진 노드예요. 블록에 어피니티가 없으면 값은 `no_affinity`가 돼요.
`ippool`	IPAM 블록이 차지하는 IP Pool이에요. 블록과 일치하는 IP Pool이 없으면 값은 `no_ippool`이 돼요.

Prometheus 메트릭은 스스로 설명이 붙는(self-documenting) 형태예요. 메트릭을 켜 두면 curl을 사용해 메트릭 목록과 함께 도움말 텍스트, 타입 정보를 확인할 수 있어요.

curl -s http://localhost:9094/metrics | head

CPU / 메모리 메트릭

kube-controllers는 Prometheus가 기본으로 제공하는 메트릭 세트도 함께 내보내요. 현재 포함된 항목은 다음과 같아요.

이름	설명
`go_gc_duration_seconds`	GC 호출 소요 시간에 대한 요약이에요.
`go_goroutines`	현재 존재하는 고루틴 수예요.
`go_memstats_alloc_bytes`	할당되어 아직 사용 중인 바이트 수예요.
`go_memstats_alloc_bytes_total`	해제 여부와 관계없이 할당된 총 바이트 수예요.
`go_memstats_buck_hash_sys_bytes`	프로파일링 버킷 해시 테이블이 사용하는 바이트 수예요.
`go_memstats_frees_total`	총 해제(free) 횟수예요.
`go_memstats_gc_sys_bytes`	가비지 컬렉션 시스템 메타데이터에 사용된 바이트 수예요.
`go_memstats_heap_alloc_bytes`	할당되어 아직 사용 중인 힙 바이트 수예요.
`go_memstats_heap_idle_bytes`	사용 대기 중인 힙 바이트 수예요.
`go_memstats_heap_inuse_bytes`	현재 사용 중인 힙 바이트 수예요.
`go_memstats_heap_objects`	할당된 객체 수예요.
`go_memstats_heap_released_bytes_total`	OS로 반환된 힙 바이트의 총합이에요.
`go_memstats_heap_sys_bytes`	시스템에서 확보한 힙 바이트 수예요.
`go_memstats_last_gc_time_seconds`	마지막 가비지 컬렉션 시점부터 1970년 기준으로 지난 시간(초)이에요.
`go_memstats_lookups_total`	포인터 조회 총 횟수예요.
`go_memstats_mallocs_total`	총 malloc 횟수예요.
`go_memstats_mcache_inuse_bytes`	mcache 구조가 사용 중인 바이트 수예요.
`go_memstats_mcache_sys_bytes`	시스템에서 확보한 mcache 구조용 바이트 수예요.
`go_memstats_mspan_inuse_bytes`	mspan 구조가 사용 중인 바이트 수예요.
`go_memstats_mspan_sys_bytes`	시스템에서 확보한 mspan 구조용 바이트 수예요.
`go_memstats_next_gc_bytes`	다음 가비지 컬렉션이 수행될 시점의 힙 바이트 수예요.
`go_memstats_other_sys_bytes`	기타 시스템 할당에 사용된 바이트 수예요.
`go_memstats_stack_inuse_bytes`	스택 할당자가 사용 중인 바이트 수예요.
`go_memstats_stack_sys_bytes`	시스템에서 확보한 스택 할당자용 바이트 수예요.
`go_memstats_sys_bytes`	시스템에서 확보한 바이트 수예요. 모든 시스템 할당의 합계예요.
`process_cpu_seconds_total`	사용자 및 시스템 CPU 시간의 총합(초)이에요.
`process_max_fds`	열 수 있는 파일 디스크립터의 최대 개수예요.
`process_open_fds`	열려 있는 파일 디스크립터 수예요.
`process_resident_memory_bytes`	상주 메모리 크기(바이트)예요.
`process_start_time_seconds`	Unix epoch 기준 프로세스 시작 시간(초)이에요.
`process_virtual_memory_bytes`	가상 메모리 크기(바이트)예요.
`promhttp_metric_handler_requests_in_flight`	현재 처리 중인 스크랩 수예요.
`promhttp_metric_handler_requests_total`	HTTP 상태 코드별 스크랩 총 횟수예요.

더 알아보기 (Learn more)

메트릭 보고 설정은 kube-controllers 구성 참조에서 바꿀 수 있어요. IPAM 메트릭은 GC 후보 수가 계속 0으로 돌아오는지 확인하는 데 특히 유용해요.