Prometheus + Grafana로 쿠버네티스 모니터링 구축하기 - 직접 붙여본 후기

집에서 돌리는 k3s 클러스터에 앱을 몇 개 올려두고 쓰다 보니, "지금 노드 메모리가 얼마나 남았지", "어제 새벽에 파드가 왜 재시작됐지" 같은 질문에 답을 못 하는 상황이 반복됐습니다. 매번 kubectl top이나 kubectl describe로 확인하는 것도 한계가 있더라고요. 결국 제대로 된 모니터링 스택을 올리기로 하고 Prometheus와 Grafana를 붙여봤는데, 생각보다 손이 많이 갔지만 붙여놓고 나니 왜 다들 이 조합을 쓰는지 알겠더군요. 오늘은 이 둘이 뭔지와, 실제로 k3s에 설치한 과정을 정리합니다.

Prometheus가 뭔가요?

Prometheus는 SoundCloud에서 시작돼 지금은 CNCF(클라우드 네이티브 재단)의 대표 프로젝트가 된 시계열(time-series) 모니터링 시스템입니다. 핵심 특징은 pull 방식이라는 건데요, 모니터링 대상이 알아서 데이터를 쏴주는 게 아니라 Prometheus 서버가 주기적으로 각 대상의 /metrics 엔드포인트를 긁어가는 구조입니다. 이 엔드포인트를 노출해주는 작은 에이전트를 "Exporter"라고 부르는데, 노드 자체의 CPU/메모리/디스크는 node-exporter가, 쿠버네티스 오브젝트 상태는 kube-state-metrics가 담당하는 식으로 역할이 나뉘어 있습니다.

Grafana는 뭔가요?

Prometheus가 데이터를 모으고 저장하는 쪽이라면, Grafana는 그 데이터를 그래프와 대시보드로 보여주는 시각화 도구입니다. Prometheus 자체에도 간단한 그래프 화면이 있긴 한데 실무에서 그대로 쓰는 경우는 거의 없고, 대부분 Grafana를 앞단에 붙여서 씁니다. 이미 커뮤니티에서 만들어둔 대시보드(노드 상태, 파드 리소스, Ingress 트래픽 등)를 ID 하나로 가져다 쓸 수 있다는 게 가장 큰 장점입니다.

왜 이 둘을 같이 쓰나

Prometheus 단독으로는 "저장 + 쿼리 + 알림 조건 평가"까지만 하고, 사람이 보기 좋은 화면은 Grafana가 맡는 식으로 역할이 명확히 나뉘어 있어서 그렇습니다. 여기에 Alertmanager를 추가하면 "메모리 90% 초과 5분 지속" 같은 규칙을 걸어서 Slack이나 이메일로 알림까지 받을 수 있습니다. 이 셋을 묶어서 흔히 "PLG 스택"이 아니라 그냥 "Prometheus 스택"이라고 부르고, 쿠버네티스 모니터링에서는 사실상 기본값 취급을 받습니다.

아키텍처 한눈에 보기

Exporter - node-exporter(노드 자원), kube-state-metrics(쿠버네티스 오브젝트 상태), 각 앱이 자체 노출하는 metrics 등 실제 데이터를 만들어내는 쪽입니다.

Prometheus Server - 주기적으로 Exporter들을 긁어와 시계열 DB에 저장하고, PromQL로 쿼리와 알림 규칙 평가를 담당합니다.

Alertmanager - Prometheus가 평가한 알림 규칙을 받아서 중복 제거, 그룹핑을 거쳐 실제 채널(Slack, 이메일 등)로 보냅니다.

grafana Grafana - Prometheus를 데이터소스로 붙여서 대시보드로 시각화합니다.

직접 구축해보기 - k3s에 kube-prometheus-stack 설치

직접 하나하나 설치할 수도 있지만, 커뮤니티에서 관리하는 kube-prometheus-stack Helm 차트를 쓰면 Prometheus, Alertmanager, Grafana, node-exporter, kube-state-metrics를 한 번에 올려줍니다. 실무에서도 이 방식이 가장 널리 쓰입니다.

1. Helm 설치

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
helm version

2. 저장소 추가 및 설치

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

kubectl create namespace monitoring

helm install kube-prom-stack prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --set grafana.adminPassword='원하는비밀번호' \
  --set prometheus.prometheusSpec.retention=7d \
  --set prometheus.prometheusSpec.resources.requests.memory=256Mi \
  --set prometheus.prometheusSpec.resources.limits.memory=512Mi

여기서 retention과 resources 값을 신경 써서 잡았는데, 홈랩처럼 메모리가 넉넉하지 않은 단일 노드 환경에서는 기본값 그대로 설치하면 Prometheus 하나가 생각보다 많은 메모리를 가져가서 다른 파드가 밀려나는 경험을 했습니다. 보관 기간을 7일 정도로 줄이고 리소스 request/limit을 명시적으로 낮게 잡는 걸 추천합니다.

3. 설치 확인 및 Grafana 접속

kubectl get pods -n monitoring

모든 파드가 Running이 되면, 우선 port-forward로 빠르게 접속해봅니다.

kubectl port-forward -n monitoring svc/kube-prom-stack-grafana 3000:80

브라우저에서 http://localhost:3000으로 접속하면 로그인 화면이 뜹니다. 기본 계정은 admin이고, 비밀번호는 설치할 때 --set으로 넣지 않았다면 아래 명령으로 시크릿에서 꺼낼 수 있습니다.

kubectl get secret -n monitoring kube-prom-stack-grafana \
  -o jsonpath="{.data.admin-password}" | base64 -d

외부에서 접속하고 싶다면 매번 port-forward를 띄우는 대신 Ingress(저는 Traefik을 쓰기 때문에 IngressRoute)로 노출하는 게 편합니다. 다만 Grafana처럼 관리자 화면을 외부에 여는 경우에는 인증서 발급 여부와 접근 제한(IP 화이트리스트나 별도 인증 미들웨어)을 꼭 같이 걸어두는 걸 추천합니다.

4. 대시보드 확인하기

kube-prometheus-stack을 설치하면 Node, Pod, Kubernetes 클러스터 전반을 보여주는 대시보드가 기본으로 몇 개 딸려 옵니다. 왼쪽 메뉴 Dashboards에서 바로 확인할 수 있고, 부족하면 Grafana 공식 대시보드 갤러리에서 ID를 가져와 Import 메뉴에 입력만 하면 바로 적용됩니다. node-exporter 대시보드는 1860번, 쿠버네티스 클러스터 전체 현황은 315번이 널리 쓰입니다.

실무에 적용할 때 팁

스토리지가 넉넉하지 않다면 Prometheus의 retention을 꼭 짧게 잡으세요. 기본값(보통 10일 이상)으로 두면 디스크를 순식간에 채웁니다.
단일 노드 홈랩 환경이라면 Prometheus, Grafana 각각에 resources.requests/limits를 명시적으로 낮게 걸어야 다른 워크로드가 밀리지 않습니다.
Alertmanager까지 설정해서 "디스크 사용률 90% 초과" 같은 규칙에 Slack Webhook을 걸어두면, 문제가 커지기 전에 알림을 받을 수 있어 체감 효과가 큽니다.
Grafana 관리자 페이지를 외부에 노출할 경우 기본 admin 비밀번호를 반드시 바꾸고, 가능하면 접근을 VPN이나 IP 제한으로 한 번 더 감싸는 걸 권장합니다.

마무리

처음엔 "굳이 홈랩에 이런 것까지 필요할까" 싶었는데, 막상 붙여놓고 나니 문제가 생겼을 때 "감"으로 추측하던 걸 그래프로 바로 확인할 수 있다는 게 체감이 컸습니다. 특히 단일 노드처럼 자원이 빠듯한 환경에서는 리소스 사용량을 눈으로 보면서 튜닝하는 것 자체가 큰 도움이 되더라고요. 차트 구성이나 알림 규칙은 운영하는 서비스 특성에 따라 계속 손봐야 하는 부분이니, 이번 글은 시작점 정도로 참고하시면 좋을 것 같습니다. 더 자세한 설정 옵션은 공식 문서(prometheus.io, grafana.com)를 참고하시는 걸 추천합니다.

로그인 후 댓글을 작성할 수 있습니다.