클러스터 관제탑 'Prometheus & Grafana' 구축

Posted Jul 7, 2025 Updated Aug 20, 2025

By minnnning

19 min read

기존에 만든 vm3개를 이용해서 클러스터로 묶고 노드 하나를 control-plane으로 만들었고 2개의 워커노드가 존재했다 이것을 이용해서 클러스터 관제할 수 있는 프로그램을 추가적으로 설치한다

1. Helm 설치

Prometheus를 설치하기 위해서 helm을 설치 해야한다

Helm은 쿠버네티스의 패키지 매니저(Package Manager)로 스마트폰에 앱을 설치할 때 ‘앱 스토어’를 사용하는 것과 비슷하다 복잡한 앱도 ‘설치’ 버튼 한 번으로 간단히 설치할 수 있는 것처럼, Helm은 복잡한 쿠버네-티스 애플리케이션을 명령어 한 줄로 설치하고 관리할 수 있게 해준다

  
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

helm version # 버전확인

주요 개념:

Chart(차트): 애플리케이션을 구성하는 데 필요한 모든 쿠버네티스 리소스(Deployment, Service, ConfigMap등)의 설계도(YAML 파일)를 모아놓은 패키지, Prometheus 스택은 수십 개의 리소스가 필요하기 때문에 차트가 필수적
Repository(저장소): 이러한 차트들을 모아놓고 공유하는 온라인 공간 우리는 prometheus-community라는 공식 저장소를 사용
Values(설정값): 차트를 설치할 때 사용자가 원하는 대로 설정을 변경할 수 있는 변수 파일 values.yaml 파일을 수정하여 Grafana를 외부에서 접속할 수 있도록 만듦
Release(릴리즈): 특정 차트를 특정 설정(Values)으로 클러스터에 설치한 결과물(실행 중인 인스턴스)을 의미

모니터링 시스템

구성요소 (Component)	역할	쿠버네티스 오브젝트	실행 위치 (총 3대 노드 중)
Node Exporter	노드의 하드웨어/OS 정보 수집	`DaemonSet`	모든 워커 노드에 1개씩 (총 2개 실행)
Prometheus 서버	데이터 중앙 수집, 저장, 처리	`StatefulSet`	워커 노드 2대 중 1대에서 실행
Grafana	데이터 시각화 대시보드	`Deployment`	워커 노드 2대 중 1대에서 실행
Kube State Metrics	쿠버네티스 오브젝트 상태 수집	`Deployment`	워커 노드 2대 중 1대에서 실행
Operator 등 기타	시스템 관리 및 자동화	`Deployment`	워커 노드 2대 중 1대에서 실행

Node Exporter (DaemonSet): 노드의 건강 상태를 측정해야 하므로, 모든 워커 노드에 각각 하나씩 반드시 떠 있어야 한다 DaemonSet은 이 역할을 수행
Prometheus / Grafana (StatefulSet, Deployment): 중앙 처리 및 시각화 도구는 1개만 실행되면 된다 쿠버네티스의 스케줄러가 자원 여유가 있는 워커 노드 중 한 곳을 선택하여 Pod을 배치 만약 Prometheus가 실행 중인 워커 노드가 다운되면, 쿠버네티스는 자동으로 다른 워커 노드에 Prometheus Pod을 다시 생성하여 서비스를 유지 (단, 데이터는 PV/PVC를 통해 보존)

핵심: 데이터 수집은 모든 노드에서, 데이터 처리와 시각화는 중앙(특정 워커 노드)에서 이루어진다 컨트롤 플레인 노드는 클러스터 관리 역할에 집중하도록 기본적으로는 사용자 애플리케이션(모니터링 시스템 포함)이 배포되지 않는다

2. Helm 저장소 추가

# Prometheus 커뮤니티에서 운영하는 공식 저장소(Repository) 추가
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

# Helm 저장소 정보 최신화
helm repo update

3. 설정 파일(values.yaml) 준비

  
# values.yaml 파일

# Grafana 관련 설정
grafana:
  # Grafana 웹 UI에 처음 로그인할 때 사용할 관리자 계정의 비밀번호
  # ID는 'admin'으로 고정되어 있습니다.
  adminPassword: "prom-operator"
  
  # Grafana 서비스를 클러스터 외부와 통신하게 하는 방법 설정
  service:
    # NodePort: 워커 노드의 특정 포트를 통해 외부에서 접속할 수 있도록 열어주는 방식
    # 이 설정을 통해 http://<워커노드IP>:<포트> 형태로 접속이 가능해집니다.
    type: NodePort

# Prometheus 서버 관련 설정
prometheus:
  # Prometheus 웹 UI 서비스 설정
  service:
    # Prometheus의 관리자 페이지도 필요시 외부에서 접속할 수 있도록 NodePort로 설정
    type: NodePort

  # Prometheus가 수집한 데이터를 저장할 영구 저장소(PersistentVolumeClaim) 설정
  prometheusSpec:
    storageSpec:
      volumeClaimTemplate:
        spec:
          # 대부분의 쿠버네티스 환경에 기본적으로 설정된 스토리지 클래스 이름
          storageClassName: default
          # ReadWriteOnce: 하나의 Pod만 이 볼륨에 데이터를 쓸 수 있도록 설정
          accessModes: ["ReadWriteOnce"]
          # 저장소의 크기 요청
          resources:
            requests:
              storage: 10Gi # 테스트용으로 10GB 공간 요청

storage class “default” does not exist 에러

GKE, AKS, EKS 같은 클라우드 플랫폼에서는 이 default 주문서가 자동으로 제공되지만, 직접 VM으로 구축한 클러스터에는 관리자가 직접 이 주문서를 만들어주기 전까지는 존재하지 않는다 바로 이것이 에러의 근본적인 원인

방법1

이 방법을 사용하면 Prometheus Pod이 재시작될 때마다 그동안 수집했던 모든 모니터링 데이터가 사라짐

  
  prometheusSpec:
    storageSpec:
      volumeClaimTemplate:
        spec:
          storageClassName: default
          accessModes: ["ReadWriteOnce"]
          resources:
            requests:
              storage: 10Gi
              
 # 위 부분을 아래로 대체
  prometheusSpec:
    # storageSpec을 빈 객체로 만들어 PVC 요청을 비활성화합니다.
    storageSpec: {}

수정한 정보로 재실행

  
helm upgrade kube-prom-stack prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --values values.yaml

방법2 (스토리지 시스템 구축 및 StorageClass 생성하기)

실제 운영 환경과 동일하게, 클러스터에 영구 스토리지를 제공하는 시스템을 설치하고 StorageClass를 직접 만들어주는 방법

Longhorn은 쿠버네티스를 위해 만들어진 가볍고 안정적인 분산 스토리지 시스템

(사전 준비) 모든 노드에 open-iscsi 설치: Longhorn이 노드의 디스크를 사용하기 위해 필요한 패키지로 컨트롤 플레인과 워커 노드 모두에 접속하여 아래 명령어를 실행
1 2 # Ubuntu / Debian sudo apt update && sudo apt install -y open-iscsi

Longhorn 설치: 아래 명령어 한 줄이면 Longhorn 시스템이 클러스터에 설치된다

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.6.2/deploy/longhorn.yaml

Longhorn 설치 확인: 몇 분 정도 기다린 후, longhorn-system 네임스페이스에 Pod들이 모두 Running 상태가 될 때까지 기다림
1 kubectl get pods -n longhorn-system
새로 생긴 StorageClass 확인: Longhorn 설치가 완료되면, longhorn이라는 이름의 StorageClass가 자동으로 생성
1 2 kubectl get sc # 또는 kubectl get storageclass
결과에 longhorn
Prometheus가 Longhorn을 사용하도록 설정: 이제 Prometheus에게 default가 아닌 longhorn 스토리지 주문서를 사용하라고 알려주면 된다 values.yaml 파일을 다음과 같이 수정
수정 전 values.yaml:
1 2 3 ... storageClassName: default ...
수정 후 values.yaml:
1 2 3 4 ... # 생성된 longhorn 스토리지 클래스를 사용하도록 명시합니다. storageClassName: longhorn ...

Helm 릴리즈 업그레이드: 수정한 values.yaml 파일을 다시 적용

  
helm upgrade kube-prom-stack prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --values values.yaml

이제 Prometheus Operator는 longhorn이라는 유효한 주문서를 발견하고, Longhorn 시스템을 통해 디스크 공간(PV)을 성공적으로 생성하여 Prometheus Pod을 정상적으로 실행

4. Helm으로 모니터링 스택 설치하기

이제 helm install 명령어로 prometheus-community 저장소에 있는 kube-prometheus-stack 차트를 설치 이 때 우리가 만든 values.yaml 설정이 적용된다

  
# 'monitoring' 이라는 격리된 공간(Namespace)을 먼저 생성합니다.
kubectl create namespace monitoring

# Helm을 이용해 'kube-prom-stack'이라는 이름의 릴리즈(Release)를 설치합니다.
helm install kube-prom-stack prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --values values.yaml

5. 설치 확인 (어느 노드에서 실행되는지 직접 보기)

kubectl get pods -n monitoring -o wide

6. Grafana 대시보드 접속하기

kubectl get service -n monitoring

출력된 결과에서 kube-prom-stack-grafana 서비스의 PORT(S) 정보를 찾는다 80:3xxxx/TCP와 같이 표시된 부분에서 3xxxx가 바로 외부 접속 포트(NodePort)

결과

현재 실행되는 pod를 모두보면 아래 사진 처럼 엄청 많은것을 확인할 수 있다

쿠버네티스 클러스터도 이제 ①핵심 인프라, ②스토리지 시스템, ③모니터링 시스템이라는 3개의 큰 시스템이 유기적으로 동작한다

kube-system 네임스페이스: “클러스터의 시청과 사회 기반 시설”

사용자가 직접 설치한 것이 아니라 쿠버네티스 클러스터를 처음 구축할 때 자동으로 생성

Pod(s) 그룹	역할 (하는 일)	실행 방식 및 이유
`etcd-master`	클러스터의 모든 정보(DB)	클러스터의 모든 설정, 상태 정보(어떤 Pod이 어디에 떠있는지 등)를 저장하는 핵심 데이터베이스 `master` 노드에서만 실행
`kube-apiserver-master`	클러스터의 민원 창구(API)	`kubectl` 명령어 등 외부의 모든 요청을 가장 먼저 받아 처리하는 관문 `master` 노드에서만 실행
`kube-controller-manager-master`	상태 관리 감독관	“Deployment에 Pod 3개를 띄워라”는 명령을 받으면, 현재 3개가 떠있는지 계속 감시하고 부족하면 새로 만드는 등 클러스터 상태를 관리
`kube-scheduler-master`	Pod 입주 심사관	새로운 Pod이 생성될 때, 어느 노드(worker1 or worker2)에 배치하는 것이 가장 효율적일지 결정
`coredns-xxxxx` (2개)	클러스터의 DNS 서버	Pod들이 서로를 IP가 아닌 서비스 이름(예: `prometheus-service`)으로 찾을 수 있게 해주는 이름 풀이 서비스 2개를 띄워 안정성을 높임
`calico-node-xxxxx` (3개)	노드별 교통 경찰 (`DaemonSet`)	모든 노드(master, worker1, worker2)에 하나씩 실행되며, 해당 노드 내에서 Pod 간의 네트워크 통신을 실제로 처리하고 보안 규칙을 적용
`kube-proxy-xxxxx` (3개)	서비스 길 안내원 (`DaemonSet`)	모든 노드에 하나씩 실행되며, 특정 서비스로 향하는 네트워크 요청을 실제 Pod의 IP로 연결해주는 길 안내 역할

longhorn-system 네임스페이스: “클러스터의 중앙 물류창고 시스템”

분산 스토리지 시스템 Longhorn의 구성요소 데이터를 영구적으로 저장하고 관리하는 역할

Pod(s) 그룹	역할 (하는 일)	실행 방식 및 이유
`longhorn-manager-xxxxx` (2개)	각 노드의 창고 관리자 (`DaemonSet`)	워커 노드 각각에 하나씩 실행되며, 해당 노드의 디스크를 관리하고 데이터 복제본을 생성/유지하는 핵심 컨트롤러
`longhorn-csi-plugin-xxxxx` (2개)	쿠버네티스-Longhorn 통역사 (`DaemonSet`)	워커 노드 각각에 하나씩 실행되며, 쿠버네티스가 “디스크 만들어줘”라고 했을 때 그 명령을 Longhorn이 알아들을 수 있게 통역
`instance-manager-xxxxx` (2개)	데이터 운반 트럭 (`DaemonSet`)	워커 노드 각각에 하나씩 실행되며, 실제 데이터 볼륨을 담당하는 프로세스를 관리
`engine-image-xxxxx` (2개)	미리 준비된 포장재 (`DaemonSet`)	워커 노드 각각에 하나씩 실행되며, 볼륨을 더 빨리 만들기 위해 필요한 엔진 이미지를 미리 다운로드해 놓는다
`csi-attacher`, `csi-provisioner`, `csi-resizer`, `csi-snapshotter` (여러 개)	CSI 표준 도우미들	디스크를 노드에 붙이고(attach), 새로 만들고(provision), 크기를 조절하고(resize), 스냅샷을 찍는 등 CSI 표준 기능을 수행하는 도우미들 안정성을 위해 여러 개가 실행
`longhorn-ui-xxxxx` (2개)	물류창고 관리 대시보드	Longhorn의 상태를 시각적으로 보여주는 웹 UI입니다. 2개를 띄워 안정성을 높임

monitoring 네임스페이스: “클러스터의 중앙 관제탑”

Pod(s) 그룹	역할 (하는 일)	실행 방식 및 이유
`prometheus-...-prometheus-0` (1개)	데이터 수집/저장소 (Prometheus)	관제탑의 심장부. 모든 데이터를 수집하고 Longhorn이 만들어준 디스크에 저장하며, Grafana의 요청에 따라 데이터를 제공
`kube-prom-stack-grafana-xxxxx` (1개)	데이터 시각화 대시보드 (Grafana)	Prometheus가 수집한 데이터를 인간이 보기 쉬운 그래프와 차트로 보여주는 시각화 도구
`kube-prom-stack-prometheus-node-exporter-xxxxx` (3개)	각 노드의 건강검진 센서 (`DaemonSet`)	모든 노드(master, worker1, worker2)에 하나씩 실행되며, 각 노드의 CPU, 메모리, 디스크 사용량 등 물리적인 건강 상태를 측정하여 Prometheus에 보고
`kube-prom-stack-kube-state-metrics-xxxxx` (1개)	쿠버네티스 상태 보고관	Deployment 개수, Pod 상태 등 쿠버네티스 내부의 논리적인 상태 정보를 수집하여 Prometheus에 보고
`alertmanager-xxxxx` (1개)	비상 경보 시스템	Prometheus가 “CPU 90% 초과!”와 같은 이상 신호를 발견했을 때, 관리자에게 이메일이나 슬랙 등으로 경보를 보내는 역할
`kube-prom-stack-kube-prome-operator-xxxxx` (1개)	관제탑 자동 설정 로봇	모니터링 관련 설정을 사람이 직접 하지 않고, 코드 기반으로 자동화해주는 똑똑한 오퍼레이터

cloud

kubernetses

This post is licensed under CC BY 4.0 by the author.