Helm으로 Kubernetes에 Prometheus 설치하기
Prometheus 단독 차트와 kube-prometheus-stack을 구분해 설치하고 PVC, 보존 기간, ServiceMonitor의 대상 검색을 확인하는 방법을 설명합니다.
Helm 설치를 마치고 Prometheus 화면까지 열었는데 애플리케이션 시계열이 보이지 않는다면, 먼저 스크레이프 설정을 누가 만드는지 확인하세요. 단독 차트에서는 Prometheus 설정을 직접 관리합니다. kube-prometheus-stack에서는 Operator가 ServiceMonitor 같은 리소스를 읽어 스크레이프 설정을 생성합니다.
두 방식 모두 Kubernetes의 대상을 모니터링할 수 있습니다. 설정을 직접 관리하려면 단독 차트를, 팀별 수집 대상을 Kubernetes 리소스로 관리하고 기본 규칙과 대시보드도 활용하려면 스택을 선택할 수 있습니다.
Helm이 관리하는 범위
Helm은 워크로드, 서비스, 권한과 스토리지 구성을 하나의 릴리스로 관리합니다. 차트 버전과 values를 함께 보관하면 업그레이드 때 변경 사항을 검토하기 쉽습니다. 릴리스를 롤백해도 이미 잃어버린 볼륨의 시계열이나 변경된 CRD 스키마까지 복원되지는 않습니다.
Prometheus 단독 차트 설치하기
현재 Kubernetes 컨텍스트와 필요한 리소스 생성 권한을 확인하세요. 예제는 prometheus 차트 29.43.0과 Prometheus v3.16.0을 사용합니다. 매니페스트는 helm template로 확인했습니다. 스토리지와 정책은 설치할 클러스터의 구성을 따릅니다.
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update prometheus-community
helm upgrade --install prometheus prometheus-community/prometheus \
--version 29.43.0 --namespace monitoring --create-namespace
이 버전은 Alertmanager, kube-state-metrics, Node Exporter, Pushgateway를 기본으로 활성화합니다. kubectl get pods,pvc,svc -n monitoring에서 상태를 확인합니다. PVC가 Pending으로 남아 있다면 이벤트를 살펴보세요. StorageClass에 따라 프로비저너가 없거나 Pod가 아직 스케줄링되지 않았을 수 있습니다.
기본 Service는 prometheus-server입니다. Service의 80 포트는 서버의 9090으로 이어집니다. kubectl -n monitoring port-forward svc/prometheus-server 9090:80을 실행하고 http://localhost:9090/targets에서 등록된 작업과 최근 스크레이프 결과를 확인하세요.
볼륨 용량과 보존 기간 정하기
단독 차트는 서버 PVC를 기본으로 활성화하고 8Gi를 요청합니다. Alertmanager는 별도 키인 alertmanager.persistence를 쓰며 기본 요청량은 2Gi입니다. 서버 영속성을 끄면 emptyDir를 사용하므로 Pod가 교체될 때 로컬 데이터가 사라집니다.
아래 예제를 values.yaml로 저장합니다. 기본 8Gi PVC를 이미 쓰고 있다면 적용 전에 50Gi로 확장할 수 있는지 확인하세요. 확장할 수 없다면 먼저 스토리지 마이그레이션을 계획합니다.
server:
persistentVolume:
enabled: true
size: 50Gi
retention: 30d
retentionSize: 40GB
resources:
requests: { cpu: 500m, memory: 2Gi }
limits: { cpu: 2, memory: 8Gi }
alertmanager:
persistence:
enabled: true
helm upgrade prometheus prometheus-community/prometheus \
--version 29.43.0 --namespace monitoring --values values.yaml
50Gi는 PVC 요청 용량, 30d는 보존 기간, 40GB는 Prometheus의 크기 기준 예시입니다. 시간과 크기를 함께 설정하면 먼저 도달하는 조건이 적용됩니다. 컴팩션 등 스토리지 작업에 필요한 여유 공간을 두고, CPU와 메모리는 실제 워크로드에 맞춰 조정하세요. Prometheus 스토리지 문서(영어)
Operator를 사용하는 kube-prometheus-stack
스택에는 Operator와 Kubernetes용 규칙, Grafana 및 대시보드가 포함됩니다. 아래는 단독 차트 대신 선택할 수 있는 설치 방법입니다. 기본값으로 둘 다 시험한다면 클러스터를 분리하세요. 같은 대상을 모니터링하는 두 릴리스를 함께 실행하면 수집과 알림이 중복될 수 있습니다.
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update prometheus-community
helm upgrade --install monitoring prometheus-community/kube-prometheus-stack \
--version 92.21.2 --namespace monitoring --create-namespace
스택 차트 92.21.2에는 Kubernetes 1.25 이상이 필요합니다. 이 차트에서 Prometheus 스토리지는 prometheus.prometheusSpec.storageSpec으로 설정합니다. 버전을 변경하기 전에 스택 업그레이드 안내(영어)에서 CRD 처리 절차를 확인하세요.
ServiceMonitor가 수집 대상에 도달하는 과정
apps 네임스페이스에 app: my-app 레이블이 붙은 Service가 있고, metrics라는 포트가 애플리케이션의 /metrics로 연결된다고 가정합니다. 아래 예제를 servicemonitor.yaml에 저장하고 스택의 CRD가 등록된 뒤에 적용합니다.
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: my-app
namespace: monitoring
labels:
release: monitoring
spec:
namespaceSelector:
matchNames: [apps]
selector:
matchLabels:
app: my-app
endpoints:
- port: metrics
path: /metrics
interval: 15s
kubectl apply -f servicemonitor.yaml
먼저 스택의 Prometheus 리소스가 release: monitoring 레이블로 ServiceMonitor를 선택합니다. 다음으로 ServiceMonitor가 apps에서 app: my-app인 Service를 찾습니다. endpoints에 적는 값은 Service에 선언된 포트 이름입니다. Pod에만 레이블을 붙이면 Service가 선택되지 않습니다.
작업이 안 보이면 Prometheus 리소스의 serviceMonitorSelector와 serviceMonitorNamespaceSelector, Service의 레이블과 포트 이름, EndpointSlice를 확인하세요. Prometheus 서비스 계정에 apps의 리소스를 검색할 권한이 있는지도 살펴봅니다. 대상은 보이는데 Down이면 스크레이프 오류를 읽고 포트, 경로, 인증과 네트워크를 확인하세요. Operator 문제 해결 문서(영어)
이 검색 방식을 유지하면서 선택한 메트릭을 DataKit Prometheus Remote Write 수신기(영어)를 통해 Guance로 전송할 수 있습니다. 수신 측에서 클러스터, 네임스페이스, 인스턴스 레이블을 확인하세요. DataKit도 같은 엔드포인트를 직접 스크레이프한다면 두 경로를 동시에 켜기 전에 어느 쪽이 샘플을 보낼지 정합니다.
설치 후 자주 묻는 질문
단독 차트로도 Kubernetes 내부 대상을 스크레이프할 수 있나요? 가능합니다. 차이는 스크레이프 설정을 관리하는 방법에 있습니다. 팀별로 Kubernetes 리소스를 선언해 수집 대상을 관리할 때는 스택이 적합합니다.
values의 크기를 늘리면 기존 PVC도 확장되나요? StorageClass가 확장을 허용하고 스토리지 드라이버가 지원해야 합니다. 해당 차트와 드라이버의 절차에 따라 기존 PVC를 수정하고 values를 맞춥니다. StatefulSet의 볼륨 템플릿과 이미 생성된 PVC는 별도로 관리됩니다. Kubernetes PVC 확장 문서(영어)
여러 클러스터의 메트릭을 어떻게 모으나요? 각 클러스터에서 스크레이프하고, 필요한 시계열을 Remote Write로 Thanos Receive(영어)나 구성된 DataKit 수신기에 전송합니다. 외부 레이블로 클러스터를 구분하고 중앙 규칙 평가는 수신 측 기능에 맞춰 구성합니다.
함께 읽기. Helm으로 Kubernetes에 Grafana 설치하기 · Alertmanager 설정하기 · OpenTelemetry와 Prometheus 비교
