[Data Platform] Prometheus + Grafana 구축 가이드 (feat. kube-prometheus-stack)

---

Intro

 

안녕하세요. 환이s입니다 👋

 

지난 글에서는 데이터 레이크하우스 플랫폼의

다섯 번째 스택으로 Airflow를 Kubernetes 위에 구축하고

Spark Job을 스케줄링하는 전체 파이프라인을 정리해 봤습니다.

 

이번 글에서는 여섯 번째 스택,

Prometheus + Grafana를 Kubernetes 환경에 구축하는 과정을 정리해보려고 합니다.

 

지금까지 구축한 Kafka, Spark, Ceph, Trino, Airflow가 실제로 잘 동작하고 있는지

한눈에 확인하려면 모니터링 환경이 필요합니다.

 

그 역할을 담당하는 것이 Prometheus와 Grafana입니다.

 

 

이번 글에서는

• kube-prometheus-stack으로 Prometheus + Grafana + Alertmanager + NodeExporter를 한 번에 설치하는 방법
• Prometheus와 Grafana 각각 Ingress로 외부 접근하는 방법
• Grafana 대시보드를 JSON 파일로 Import하는 방법

까지 순서대로 확인해 보겠습니다.

---

1. kube-prometheus-stack 아키텍처 개요

 

본격적인 설치에 앞서,

이번 구성의 전체 아키텍처를 먼저 이해하는 것이 중요합니다.

 

Kubernetes 클러스터
        │
        ▼
  NodeExporter (각 노드 메트릭 수집)
        │
        ▼
   Prometheus (메트릭 수집 및 저장)
        │
        ▼
    Grafana (메트릭 시각화 대시보드)
        │
  Alertmanager (알림 관리)

 

각 컴포넌트의 역할은 아래와 같습니다.

컴포넌트	역할
Prometheus	클러스터 및 애플리케이션 메트릭 수집 및 저장
Grafana	Prometheus 데이터를 시각화하는 대시보드
Alertmanager	알림 규칙 기반으로 알림 발송 관리
NodeExporter	각 노드의 CPU, 메모리, 디스크 등 시스템 메트릭 수집

 

즉, 여기서 확인할 수 있는 핵심은

kube-prometheus-stack 하나로 이 4가지 컴포넌트를 한 번에 설치하고

ServiceMonitor까지 자동으로 연결된다는 점입니다.

 

개별 설치 방식과 비교하면 아래와 같습니다.

방식	특징
개별 설치	버전 호환성 직접 관리, ServiceMonitor 별도 설정 필요
kube-prometheus-stack	버전 호환성 자동 관리, ServiceMonitor 자동 연결

---

2. 설치 순서

 

이번 구축에서 사용하는 디렉토리 구조는 아래와 같습니다.

prometheus/
├── helm/
│   ├── install.sh              # Helm 설치 스크립트
│   └── values.yaml             # Helm 커스텀 값
├── manifests/
│   ├── 10_ingress_prometheus.yaml
│   └── 20_ingress_grafana.yaml
└── grafana_dashboards/
    ├── clusterOverview.json    # 클러스터 전체 현황 대시보드
    └── nodeOverview.json       # 노드별 리소스 현황 대시보드

 

설치 순서는 아래와 같습니다.

Helm 설치 → Ingress 설정 → Grafana 대시보드 Import

 

---

3. Helm으로 kube-prometheus-stack 설치

 

Harbor 내부 레지스트리에서 OCI 방식으로 Helm Chart를 가져옵니다.

(Harbor가 없는 환경이라면 아래 공식 이미지를 확인해서 대체하시면 됩니다.)

prom/alertmanager - Docker Image

 

prom/node-exporter - Docker Image

 

grafana/grafana - Docker Image

 

prom/prometheus - Docker Image

 

# helm/install.sh
NAMESPACE=monitoring
RELEASE_NAME=prometheus
REGISTRY=harbor.local
CHART_VERSION=82.10.5

helm registry login $REGISTRY

helm upgrade --install $RELEASE_NAME \
  oci://$REGISTRY/helm-chart/kube-prometheus-stack \
  --version $CHART_VERSION \
  --namespace $NAMESPACE \
  --create-namespace \
  -f values.yaml

 

values.yaml의 핵심 설정은 아래와 같습니다.

---

NodeExporter 설정

nodeExporter:
  enabled: true
  image:
    registry: harbor.local
    repository: library/monitoring/node-exporter
    tag: v1.8.1

 

각 노드에 DaemonSet으로 배포되어 CPU, 메모리, 디스크 등 시스템 메트릭을 수집합니다.

---

Prometheus 설정

prometheus:
  service:
    type: NodePort
    port: 80
    targetPort: 9090
    nodePort: 31010
  prometheusSpec:
    storageSpec:
      volumeClaimTemplate:
        spec:
          storageClassName: rook-ceph-block
          accessModes: ["ReadWriteOnce"]
          resources:
            requests:
              storage: 20Gi
    image:
      registry: harbor.local
      repository: library/monitoring/prometheus
      tag: v2.50.0

 

수집된 메트릭을 Ceph 블록 스토리지에 영구 저장합니다.

rook-ceph-block StorageClass를 사용해서 RWO 방식의 PVC를 생성합니다.

---

Grafana 설정

grafana:
  adminPassword: "secure123!"
  service:
    type: NodePort
    port: 80
    targetPort: 3000
    nodePort: 31020
  image:
    registry: harbor.local
    repository: library/monitoring/grafana
    tag: 12.4.0

⚠️ adminPassword를 values.yaml에 고정값으로 설정한 이유는 ArgoCD GitOps 배포 환경에서 OutOfSync 방지를 위해서입니다.

운영 환경에서는 Kubernetes Secret으로 분리해서 관리하는 것을 권장합니다.

 

---

Alertmanager 설정

alertmanager:
  alertmanagerSpec:
    storage:
      volumeClaimTemplate:
        spec:
          storageClassName: rook-ceph-block
          accessModes: ["ReadWriteOnce"]
          resources:
            requests:
              storage: 5Gi

Alertmanager는 이번 구성에서 설치만 되어 있는 상태입니다.

실제 알림 receiver 설정(Slack, Email 등)은 추후 별도 가이드에서 다루겠습니다.

---

Pod가 Running 상태인지 확인합니다.

kubectl get pods -n monitoring

 

정상적인 경우 아래처럼 보입니다.

NAME                                                      READY   STATUS    RESTARTS   AGE
prometheus-helm-kube-prome-prometheus-0                   2/2     Running   0          ...
prometheus-helm-grafana-xxxxxxxxxx-xxxxx                  3/3     Running   0          ...
prometheus-helm-kube-prome-alertmanager-0                 2/2     Running   0          ...
prometheus-helm-prometheus-node-exporter-xxxxx            1/1     Running   0          ...

 

Pod가 Running 상태가 되지 않는 경우 아래 명령어로 원인을 확인합니다.

# Pod 상태 상세 확인
kubectl describe pod <pod-name> -n monitoring

# Pod 로그 확인
kubectl logs <pod-name> -n monitoring

 

자주 발생하는 원인은 아래와 같습니다.

증상	원인	조치
Pending 상태 지속	PVC 바인딩 실패	kubectl get pvc -n monitoring으로 PVC 상태 확인
CrashLoopBackOff	Grafana 설정 오류	kubectl logs로 Grafana 컨테이너 로그 확인
ImagePullBackOff	이미지 pull 실패	Harbor 로그인 상태 또는 공식 이미지 URL 확인

---

4. Ingress 설정

 

Prometheus와 Grafana 각각 Ingress를 설정합니다.

---

Prometheus Ingress

# manifests/10_ingress_prometheus.yaml
spec:
  ingressClassName: nginx
  rules:
  - host: prometheus.<your-ip>.sslip.io
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: prometheus-helm-kube-prome-prometheus
            port:
              number: 80

---

Grafana Ingress

# manifests/20_ingress_grafana.yaml
spec:
  ingressClassName: nginx
  rules:
  - host: grafana.<your-ip>.sslip.io
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: prometheus-helm-grafana
            port:
              number: 80

kubectl apply -f manifests/

 

접근 주소는 아래와 같습니다.

Prometheus : http://prometheus.<your-ip>.sslip.io
Grafana    : http://grafana.<your-ip>.sslip.io
             ID: admin
             PW: (values.yaml에서 설정한 adminPassword)

 

즉, 여기서 확인할 수 있는 핵심은

Prometheus 서비스명이 prometheus-helm-kube-prome-prometheus처럼

길게 자동 생성되기 때문에 kubectl get svc -n monitoring으로

실제 서비스명을 먼저 확인하고 Ingress에 적용해야 한다는 점입니다.

kubectl get svc -n monitoring

 

---

5. Grafana Dashboard Import

 

Grafana에 대시보드를 등록하는 방법은 두 가지가 있습니다.

방법	특징
UI Import	JSON 파일을 Grafana에서 직접 업로드, 즉시 반영
ConfigMap 프로비저닝	values.yaml에 설정해서 배포 시 자동 등록

 

이번 구성에서는 UI Import 방식을 사용합니다.

 

💡 이번 구성에서 사용하는 JSON 파일은 Grafana 공식 대시보드를 기반으로 직접 커스텀한 파일입니다.
공식 대시보드는 Grafana Dashboard에서 찾을 수 있으며, 다운로드한 JSON을 환경에 맞게 수정한 뒤 아래 방법으로 Import 하면 됩니다.

Grafana dashboards | Grafana Labs

 

Import 순서

1. Grafana 접속 → 좌측 메뉴 Dashboards 클릭
2. 우측 상단 New → Import 클릭
3. JSON 파일 업로드
4. Import 버튼 클릭

 

등록하면 아래 두 개의 대시보드를 확인할 수 있습니다.

대시보드	내용
00_Cluster Overview	클러스터 전체 CPU, 메모리, 네트워크 현황
00_Node Overview	노드별 리소스 사용량 상세 현황

 

즉, 여기서 확인할 수 있는 핵심은

JSON 파일을 그대로 Import하면 Prometheus에서 수집한 메트릭이 Grafana 대시보드에 즉시 연동된다는 점입니다.

---

📝 마무리

이번 글에서는

Kubernetes 위에서 kube-prometheus-stack으로 Prometheus + Grafana + Alertmanager + NodeExporter를 한 번에 구축하는 과정을 정리해 봤습니다.

 

정리하면,

• kube-prometheus-stack → 4가지 컴포넌트를 한 번에 설치, 버전 호환성 자동 관리
• Ceph 블록 스토리지 → Prometheus / Alertmanager 메트릭 영구 저장
• Ingress → Prometheus / Grafana 각각 외부 접근
• JSON Import → 대시보드를 파일로 관리하고 UI에서 바로 등록

라고 볼 수 있습니다.

 

특히 이번 구축에서 주의해야 할 포인트는

• Ingress 서비스명은 반드시 kubectl get svc -n monitoring으로 확인 후 적용
• adminPassword 고정값 설정은 ArgoCD OutOfSync 방지 목적 — 운영 환경에서는 Secret으로 분리 권장
• Alertmanager는 설치만 된 상태 — 실제 알림 receiver 설정은 추후 별도 가이드에서 다룰 예정

이 3가지였습니다.

 

다음 편에서는 데이터를 비즈니스 관점으로 시각화하는 Superset 구축 과정을 다뤄보겠습니다. 🙌

 

궁금한 점이나 추가로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요! 😊