HPA 커스텀 메트릭 + Grafana 대시보드로 MCP 서버 안정화하기: Kubernetes에서 AI 에이전트 서버 운영 실전

원하는 Pod 수 = ceil(현재 Pod 수 × (현재 메트릭 값 / 목표 메트릭 값))

MCP 서버 Pod
  └── /metrics 엔드포인트 (Prometheus 형식)
        ↓
Prometheus
  └── 15초 간격 스크래핑
        ↓
Prometheus Adapter
  └── custom.metrics.k8s.io API로 변환
        ↓
HPA 컨트롤러
  └── 15초마다 메트릭 조회 → Pod 수 결정
        ↓
Grafana
  └── 시각화 및 알림

// Node.js (TypeScript) 예시
import { Registry, Histogram, Counter, Gauge } from 'prom-client';
 
const registry = new Registry();
 
// histogram 타입 필수: _bucket, _sum, _count가 자동 생성됨
export const requestDuration = new Histogram({
  name: 'mcp_request_duration_seconds',
  help: 'MCP 요청 처리 지연 시간',
  labelNames: ['method', 'status'],
  buckets: [0.05, 0.1, 0.2, 0.5, 1, 2, 5], // 초 단위
  registers: [registry],
});
 
export const errorsTotal = new Counter({
  name: 'mcp_errors_total',
  help: 'MCP 에러 총 횟수',
  labelNames: ['error_type'],
  registers: [registry],
});
 
export const queueDepth = new Gauge({
  name: 'mcp_queue_depth',
  help: '처리 대기 중인 요청 수',
  labelNames: ['service'],
  registers: [registry],
});
 
// /metrics 엔드포인트
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', registry.contentType);
  res.end(await registry.metrics());
});

# mcp-server-deployment.yaml (핵심 부분)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mcp-server
  template:
    metadata:
      labels:
        app: mcp-server
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "8080"
        prometheus.io/path: "/metrics"
    spec:
      containers:
      - name: mcp-server
        image: your-registry/mcp-server:latest
        ports:
        - containerPort: 8080
        resources:
          requests:
            cpu: "250m"       # HPA 작동을 위해 필수
            memory: "512Mi"
          limits:
            cpu: "2"
            memory: "2Gi"

# Prometheus 서비스 이름 확인 (환경마다 다름)
kubectl get svc -n monitoring
 
# 확인된 서비스명으로 Adapter 설치
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install prometheus-adapter prometheus-community/prometheus-adapter \
  --namespace monitoring \
  --set prometheus.url=http://prometheus-operated.monitoring.svc.cluster.local \
  --set prometheus.port=9090

# prometheus-adapter-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus-adapter
  namespace: monitoring
data:
  config.yaml: |
    rules:
    - seriesQuery: 'mcp_request_duration_seconds_sum{service="mcp-server"}'
      resources:
        overrides:
          namespace: { resource: namespace }
          pod: { resource: pod }
      name:
        matches: "^mcp_request_(.*)_seconds_sum"
        as: "mcp_request_${1}_latency"
      # 올바른 평균 지연 계산: sum을 count로 나눠야 실제 지연값이 됨
      metricsQuery: |
        avg(
          rate(mcp_request_duration_seconds_sum{service="mcp-server"}[2m])
          / rate(mcp_request_duration_seconds_count{service="mcp-server"}[2m])
        )
 
    - seriesQuery: 'mcp_errors_total{service="mcp-server"}'
      resources:
        overrides:
          namespace: { resource: namespace }
          pod: { resource: pod }
      name:
        matches: "^mcp_(.*)_total"
        as: "mcp_${1}_rate"
      metricsQuery: 'sum(rate(mcp_errors_total{service="mcp-server"}[2m]))'

kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/" | jq '.resources[].name'

# mcp-server-hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: mcp-server-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: mcp-server
  minReplicas: 2
  maxReplicas: 20  # 노드 5개 × 4 CPU / 0.25(requests) × 0.25(안전마진)
  metrics:
  - type: Pods
    pods:
      metric:
        name: mcp_request_duration_latency
      target:
        type: AverageValue
        averageValue: "200m"   # Pod당 평균 지연 200ms 초과 시 스케일 아웃
  - type: Pods
    pods:
      metric:
        name: mcp_errors_rate
      target:
        type: AverageValue
        averageValue: "0.01"   # Pod당 에러율 1% 초과 시 스케일 아웃
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 0      # 스파이크에 즉각 반응
      policies:
      - type: Percent
        value: 100
        periodSeconds: 15                # 15초마다 최대 2배 확장
    scaleDown:
      stabilizationWindowSeconds: 300    # 5분간 안정화 후 축소
      policies:
      - type: Percent
        value: 50
        periodSeconds: 60

# mcp-server-scaledobject.yaml
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: mcp-server-keda
spec:
  scaleTargetRef:
    name: mcp-server
  minReplicaCount: 1
  maxReplicaCount: 20
  triggers:
  - type: prometheus
    metadata:
      serverAddress: http://prometheus-operated.monitoring.svc.cluster.local:9090
      metricName: mcp_request_queue_depth
      query: 'sum(mcp_queue_depth{service="mcp-server"})'
      threshold: '30'           # 큐에 30개 이상이면 스케일 아웃
      activationThreshold: '5'  # 큐 5개 미만이면 KEDA 비활성 (불필요한 기동 방지)

# 패널 1: p99 호출 지연 — histogram 타입 메트릭 필수
histogram_quantile(0.99,
  rate(mcp_request_duration_seconds_bucket[5m])
)
 
# 패널 2: 에러율 (%)
sum(rate(http_requests_total{status=~"5.."}[5m]))
/ sum(rate(http_requests_total[5m])) * 100
 
# 패널 3: 현재 활성 Pod 수
count(up{job="mcp-servers"})
 
# 패널 4: 큐 깊이 (실시간)
mcp_queue_depth{service="mcp-server"}

# otel-collector-configmap.yaml
receivers:
  otlp:                        # traces 파이프라인이 참조하는 수신기 — 반드시 정의 필요
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  prometheus:
    config:
      scrape_configs:
      - job_name: 'mcp-servers'
        static_configs:
        - targets: ['localhost:8080']
 
processors:
  batch:
    timeout: 10s
    send_batch_size: 1024
 
exporters:
  prometheus:
    endpoint: "0.0.0.0:8888"
  jaeger:
    endpoint: jaeger-collector:14250
 
service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch]
      exporters: [prometheus]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [jaeger]