본문으로 건너뛰기

GPU 서비스 그룹핑

노트

GPU 모니터링 전반에 대한 개요는 WhaTap GPU 모니터링 문서를 참고하세요.

WhaTap Operator의 GPU 모니터링 기능에서 애플리케이션(GPU 사용) 파드의 Kubernetes Label을 GPU 메트릭에 부착하여, WhaTap에서 서비스/프로젝트 단위로 GPU 사용량을 그룹핑·조회하는 방법을 설명합니다.

  • 적용 대상: WhatapAgent CR (monitoring.whatap.com/v2alpha1)

  • 관련 필드: spec.features.k8sAgent.gpuMonitoring.groupLabel, groupLabelAllowlistRegex

  • 핵심 결과 라벨: whatap_kube_label_gpu_group


팁

어떤 문제를 해결하나요?

기본 DCGM 메트릭(DCGM_FI_DEV_GPU_UTIL 등)에는 GPU/노드/파드 식별자는 있지만 사용자가 운영하는 "서비스" 단위의 정보(예: 프로젝트 ID, 팀, 워크로드 종류)는 들어있지 않습니다.

  • "프로젝트 A가 사용하는 전체 GPU 사용률 합계" 같은 질의가 어렵습니다.

  • 멀티테넌트(여러 팀이 한 클러스터 공유) 환경에서 비용/사용량 정산이 어렵습니다.

이 기능을 사용하면 파드에 붙인 라벨(prjId=projectA 등)이 DCGM 메트릭 라벨로 자동 전파되고, WhaTap의 공통 라벨 whatap_kube_label_gpu_group으로 정규화되어 대시보드/검색에서 그룹핑 키로 바로 사용할 수 있습니다.

빠른 시작​

GPU 모니터링 + 그룹 라벨 활성화​

apiVersion: monitoring.whatap.com/v2alpha1
kind: WhatapAgent
metadata:
  name: whatap
  namespace: whatap-monitoring
spec:
  features:
    k8sAgent:
      gpuMonitoring:
        enabled: true
        # 그룹핑 키로 사용할 파드 라벨 키
        groupLabel: "prjId"
        # (선택) 노출 허용 라벨 키 정규식. 미설정 시 ^(prjId)$ 자동 적용
        # groupLabelAllowlistRegex: "^(prjId|team)$"
        # (선택) 모든 GPU 메트릭에 cluster 라벨 부여
        clusterName: "prod-gpu-cluster"

GPU 사용 파드에 라벨 부여​

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ml-train
  namespace: ml
spec:
  replicas: 2
  selector:
    matchLabels:
      app: ml-train
  template:
    metadata:
      labels:
        app: ml-train
        prjId: "projectA"        # ◀ 그룹핑 키 (groupLabel 과 동일)
    spec:
      containers:
        - name: trainer
          image: my-registry/trainer:latest
          resources:
            limits:
              nvidia.com/gpu: 1
노트

라벨은 Pod 레벨(spec.template.metadata.labels)에 부여해야 합니다. Deployment 라벨이 아닙니다.

사용 예시 (활용 시나리오)​

프로젝트(prjId) 단위 사용량​

  • groupLabel: prjId
  • 파드 라벨: prjId: projectA, prjId: projectB
  • WhaTap 대시보드에서 whatap_kube_label_gpu_group으로 group by → 프로젝트별 GPU 사용률/메모리 사용량 비교

팀(team) 단위 정산​

gpuMonitoring:
  enabled: true
  groupLabel: "team"
  groupLabelAllowlistRegex: "^(team)$"
  • 파드 라벨: team: search, team: recsys, …

여러 라벨을 함께 노출하고 싶은 경우​

groupLabel로 정규화되는 라벨은 한 개(whatap_kube_label_gpu_group)지만, 다른 파드 라벨도 메트릭 라벨로 같이 노출하고 싶다면 groupLabelAllowlistRegex로 확장할 수 있습니다.

gpuMonitoring:
  enabled: true
  groupLabel: "prjId"
  groupLabelAllowlistRegex: "^(prjId|team|env)$"
  • whatap_kube_label_gpu_group ← prjId 값
  • team, env 라벨도 DCGM 메트릭에 그대로 노출 (정규화는 되지 않음)

검증 방법​

dcgm-exporter 환경변수 확인​

kubectl -n whatap-monitoring get ds whatap-node-agent \
  -o jsonpath='{.spec.template.spec.containers[?(@.name=="dcgm-exporter")].env}' | jq

출력 결과에 다음 두 환경변수가 포함되어 있어야 파드 라벨 수집이 활성화된 상태입니다.

  • DCGM_EXPORTER_KUBERNETES_ENABLE_POD_LABELS=true
  • DCGM_EXPORTER_KUBERNETES_POD_LABEL_ALLOWLIST_REGEX=^(prjId)$

메트릭 직접 조회 (파드에 라벨 있어야 함)​

# dcgm-exporter Pod 하나에 접속
POD=$(kubectl -n whatap-monitoring get pod -l name=whatap-node-agent -o name | head -1)
kubectl -n whatap-monitoring exec "$POD" -c dcgm-exporter -- \
  wget -qO- localhost:9400/metrics | grep DCGM_FI_DEV_GPU_UTIL | head
DCGM_FI_DEV_GPU_UTIL{gpu="0", ..., pod="ml-train-xxxx", namespace="ml", prjId="projectA"} 87

OpenAgent scrape 설정 확인​

kubectl -n whatap-monitoring get configmap whatap-open-agent-config -o yaml | grep -A2 whatap_kube_label_gpu_group

출력에 다음 relabel 블록이 포함되어 있어야 합니다. source_labels의 값은 설정한 groupLabel 키와 일치해야 합니다.

- action: replace
  source_labels: [prjId]
  target_label: whatap_kube_label_gpu_group

트러블슈팅​

증상원인 / 확인 포인트
메트릭에 prjId 라벨이 안 보임(1) Pod 라벨에 prjId 부여되었는지 (spec.template.metadata.labels), (2) dcgm-exporter가 재시작되어 새 env 반영되었는지
prjId는 보이는데 whatap_kube_label_gpu_group이 안 보임OpenAgent ConfigMap 갱신 후 OpenAgent 파드 재기동 필요. kubectl rollout restart deploy/whatap-open-agent -n whatap-monitoring
groupLabel 값에 -, ., / 포함Prometheus 라벨 키 규칙상 _로 치환된 키로 source_labels가 구성됨. allowlist 정규식도 원본 키 기준이므로 그대로 설정 가능
멀티 라벨을 노출하고 싶음groupLabelAllowlistRegex를 ^(prjId|team|env)$처럼 명시
모든 GPU 메트릭에 클러스터 식별이 필요clusterName 필드를 함께 설정 (메트릭에 cluster=<값> 부착)

관련 필드 요약​

필드설명기본값
gpuMonitoring.enabledGPU 모니터링(dcgm-exporter) 활성화false
gpuMonitoring.groupLabel그룹핑에 사용할 Pod 라벨 키. 설정 시 whatap_kube_label_gpu_group으로 정규화-
gpuMonitoring.groupLabelAllowlistRegexdcgm-exporter가 노출할 Pod 라벨 키 정규식^(<groupLabel>)$
gpuMonitoring.clusterName모든 GPU 메트릭에 cluster 라벨 부착-

참고​

  • git repo: https://github.com/whatap/whatap-operator.git

  • 구현 코드: internal/controller/install_agents.go (addDcgmExporterToNodeAgent, GPU scrape config 생성부)

  • CRD 정의: api/v2alpha1/whatapagent_types.go (GpuMonitoringSpec)

  • 예제: examples/whatap-agent-all-options.yaml, examples/whatap-agent-gpu-custom-env.yaml

최종 수정: