VictoriaMetrics K8s Stack 설치 가이드

VictoriaMetrics K8s Stack 설치 가이드

개요

imprun.dev 플랫폼의 모니터링 인프라로 VictoriaMetrics를 선택했습니다.

선택 이유

1. 리소스 효율성: Prometheus 대비 메모리/CPU 사용량 50% 이하
2. 높은 성능: 쿼리 속도 7배 빠름, 압축률 높음 (장기 보존 비용 절감)
3. Prometheus 호환: PromQL, Grafana, ServiceMonitor 등 기존 생태계 활용
4. 단순한 운영: VMSingle(단일 노드)로 시작, 필요 시 VMCluster로 확장

설치된 구성 요소

monitoring 네임스페이스
├── VictoriaMetrics Operator       # CRD 관리
├── VMSingle                        # 메트릭 스토리지 (단일 노드)
├── VMAgent                         # 메트릭 수집 에이전트
├── Grafana                         # 시각화 대시보드
└── Prometheus Node Exporter       # 노드 메트릭 수집 (각 노드에 DaemonSet)

비활성화된 컴포넌트 (리소스 절약):

• VMAlert (알림 규칙 엔진)
• VMAlertmanager (알림 관리자)
• Kube-State-Metrics (쿠버네티스 리소스 메트릭)

설치 방법

1. Helm Repository 추가

helm repo add vm https://victoriametrics.github.io/helm-charts/
helm repo update

2. 설치

cd k8s

# 최소 사양 환경 (4코어, 24GB, 100GB)
helm install vm vm/victoria-metrics-k8s-stack \
  --namespace monitoring \
  --create-namespace \
  --values victoriametrics-values-minimal.yaml \
  --timeout 15m \
  --wait

3. 설치 확인

# Pod 상태 확인
kubectl get pods -n monitoring

# 기대 출력:
# NAME                                            READY   STATUS    RESTARTS   AGE
# vm-grafana-xxx                                  2/2     Running   0          1m
# vm-prometheus-node-exporter-xxx (각 노드별)      1/1     Running   0          1m
# vm-victoria-metrics-operator-xxx                1/1     Running   0          1m
# vmagent-vm-victoria-metrics-k8s-stack-xxx       2/2     Running   0          1m
# vmsingle-vm-victoria-metrics-k8s-stack-xxx      1/1     Running   0          1m

# 리소스 사용량 확인
kubectl top pods -n monitoring

리소스 사용량

예상 리소스 (최소 사양 기준)

컴포넌트	CPU (requests)	CPU (limits)	Memory (requests)	Memory (limits)
VM Operator	25m	100m	64Mi	128Mi
VMSingle	100m	500m	512Mi	1Gi
VMAgent	50m	200m	128Mi	256Mi
Grafana	50m	300m	192Mi	384Mi
Node Exporter	25m (per node)	50m	16Mi	32Mi
총합	250m	1150m	912Mi	1.8Gi

스토리지

• VMSingle: 10Gi (메트릭 데이터, 1개월 보존)
• Grafana: 2Gi (대시보드 설정)
• 총 12Gi

Grafana 접근

로컬 접근 (Port Forward)

kubectl port-forward -n monitoring svc/vm-grafana 3000:80

브라우저에서 http://localhost:3000 접속

• Username: admin
• Password: admin (⚠️ 반드시 변경 필요!)

프로덕션 접근 (Ingress)

victoriametrics-values-minimal.yaml에서 Ingress 활성화:

grafana:
  ingress:
    enabled: true
    ingressClassName: nginx
    hosts:
      - grafana.imprun.dev
    tls:
      - secretName: grafana-tls
        hosts:
          - grafana.imprun.dev

cert-manager를 사용한 TLS 인증서 자동 발급:

grafana:
  ingress:
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-cloudflare"

메트릭 수집 설정

imprun-server 메트릭 노출

imprun-server에서 Prometheus 메트릭을 노출하도록 설정:

1. NestJS 메트릭 라이브러리 설치

cd server
pnpm add @willsoto/nestjs-prometheus prom-client

2. Prometheus 모듈 추가

// server/src/app.module.ts
import { PrometheusModule } from '@willsoto/nestjs-prometheus';

@Module({
  imports: [
    PrometheusModule.register({
      defaultMetrics: {
        enabled: true,
      },
      path: '/metrics',  // /metrics 엔드포인트
    }),
    // ... 기타 모듈
  ],
})
export class AppModule {}

3. ServiceMonitor 생성

# deploy/helm/imprun-server/templates/servicemonitor.yaml
apiVersion: v1
kind: Service
metadata:
  name: {{ include "imprun-server.fullname" . }}-metrics
  labels:
    {{- include "imprun-server.labels" . | nindent 4 }}
spec:
  ports:
    - name: metrics
      port: 3000
      targetPort: 3000
  selector:
    {{- include "imprun-server.selectorLabels" . | nindent 4 }}
---
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMServiceScrape
metadata:
  name: {{ include "imprun-server.fullname" . }}
  labels:
    {{- include "imprun-server.labels" . | nindent 4 }}
spec:
  selector:
    matchLabels:
      {{- include "imprun-server.selectorLabels" . | nindent 6 }}
  endpoints:
    - port: metrics
      path: /metrics
      interval: 30s

자동 발견 확인

VMAgent가 자동으로 ServiceMonitor를 발견하여 메트릭을 수집합니다:

# VMAgent 로그 확인
kubectl logs -n monitoring -l app.kubernetes.io/name=vmagent

# VMSingle에서 메트릭 확인
kubectl port-forward -n monitoring svc/vmsingle-vm-victoria-metrics-k8s-stack 8429:8429

# 브라우저: http://localhost:8429/vmui
# 쿼리 예시: up{job="imprun-server"}

주요 PromQL 쿼리

시스템 메트릭

# CPU 사용률 (노드별)
100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

# 메모리 사용률
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

# 디스크 사용률
(1 - (node_filesystem_avail_bytes{mountpoint="/"} / node_filesystem_size_bytes{mountpoint="/"})) * 100

애플리케이션 메트릭

# HTTP 요청 속도 (초당)
rate(http_requests_total[5m])

# HTTP 응답 시간 (p95)
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

# 에러율
rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

대시보드

기본 대시보드

설치 시 자동으로 포함되는 대시보드:

1. Node Exporter Full: 노드 하드웨어 메트릭 (CPU, 메모리, 디스크, 네트워크)
2. VictoriaMetrics: VMSingle, VMAgent 상태 모니터링
3. Kubernetes Cluster: Pod, Deployment, Service 메트릭

커스텀 대시보드 추가

Grafana UI에서:

1. + → Import
2. Grafana.com에서 대시보드 ID 입력 (예: 13770 - VictoriaMetrics Single)
3. Data Source: VictoriaMetrics 선택
4. Import

알림 설정 (선택적)

리소스가 충분하면 VMAlert 활성화:

# victoriametrics-values-minimal.yaml
vmalert:
  enabled: true
  spec:
    datasource:
      url: "http://vmsingle-vm-victoria-metrics-k8s-stack.monitoring.svc:8429"
    notifier:
      url: "http://vmalertmanager-vm-victoria-metrics-k8s-stack.monitoring.svc:9093"
    resources:
      limits:
        cpu: 200m
        memory: 256Mi
      requests:
        cpu: 50m
        memory: 128Mi

alertmanager:
  enabled: true
  config:
    global:
      slack_api_url: 'YOUR_SLACK_WEBHOOK_URL'
    route:
      receiver: 'slack'
    receivers:
      - name: 'slack'
        slack_configs:
          - channel: '#alerts'
            title: '[{{ .Status | toUpper }}] {{ .GroupLabels.alertname }}'
            text: '{{ range .Alerts }}{{ .Annotations.summary }}\n{{ end }}'

유지보수

업그레이드

# 차트 업데이트
helm repo update

# 새 버전 확인
helm search repo vm/victoria-metrics-k8s-stack --versions | head -5

# 업그레이드 (dry-run)
helm upgrade vm vm/victoria-metrics-k8s-stack \
  -n monitoring \
  -f victoriametrics-values-minimal.yaml \
  --dry-run --debug

# 실제 업그레이드
helm upgrade vm vm/victoria-metrics-k8s-stack \
  -n monitoring \
  -f victoriametrics-values-minimal.yaml \
  --wait

백업

# VMSingle 데이터 백업
kubectl exec -n monitoring vmsingle-vm-victoria-metrics-k8s-stack-xxx -- \
  /victoria-metrics-prod \
  -snapshotCreateURL=http://localhost:8428/snapshot/create

# Grafana 대시보드 백업
kubectl get configmap -n monitoring -l grafana_dashboard=1 -o yaml > grafana-dashboards-backup.yaml

삭제

# Helm release 삭제
helm uninstall vm -n monitoring

# PVC 수동 삭제 (데이터 삭제됨!)
kubectl delete pvc -n monitoring --all

# Namespace 삭제
kubectl delete namespace monitoring

트러블슈팅

VMAgent가 메트릭을 수집하지 못함

# VMAgent 로그 확인
kubectl logs -n monitoring -l app.kubernetes.io/name=vmagent

# ServiceMonitor 확인
kubectl get vmservicescrape -n monitoring
kubectl get vmservicescrape -n imprun-system  # imprun-server가 있는 네임스페이스

# VMAgent 설정 확인 (selectAllByDefault: true인지)
kubectl get vmagent -n monitoring vm-victoria-metrics-k8s-stack -o yaml | grep selectAllByDefault

Grafana 대시보드에 데이터가 없음

# VictoriaMetrics 데이터소스 확인
kubectl port-forward -n monitoring svc/vmsingle-vm-victoria-metrics-k8s-stack 8429:8429

# 브라우저: http://localhost:8429/vmui
# 쿼리: up (모든 타겟 확인)

# Grafana에서 데이터소스 테스트
# Configuration → Data Sources → VictoriaMetrics → Test

디스크 부족

# 메트릭 보존 기간 단축
kubectl edit vmsingle -n monitoring vm-victoria-metrics-k8s-stack
# spec.retentionPeriod: "1" → "0.5" (2주)

# 또는 PVC 확장
kubectl edit pvc -n monitoring vmsingle-vm-victoria-metrics-k8s-stack
# spec.resources.requests.storage: 10Gi → 20Gi

참고 자료

• VictoriaMetrics 공식 문서
• Helm Chart GitHub
• PromQL 치트시트
• Grafana 대시보드 갤러리