# kube-state-metrics 部署指南

> **版本**: v2.10.1
> **用途**: 提供 K8s 物件狀態指標給 Prometheus
> **建立日期**: 2026-03-29 (台北時間)

---

## 1. 部署 kube-state-metrics

```bash
# 從 Git repo 部署
kubectl apply -f k8s/kube-state-metrics/kube-state-metrics.yaml

# 驗證
kubectl get pods -n kube-state-metrics
kubectl get svc -n kube-state-metrics
```

## 2. 更新 Prometheus 配置

在 `192.168.0.188` 的 Prometheus 配置中新增抓取目標：

```yaml
# /home/ollama/momo-pro/monitoring/prometheus.yml

scrape_configs:
  # ... 現有配置 ...

  # kube-state-metrics
  - job_name: 'kube-state-metrics'
    static_configs:
      - targets: ['192.168.0.121:30888']  # NodePort
    metrics_path: /metrics
    scrape_interval: 30s
```

## 3. 更新告警規則

複製告警規則到 Prometheus：

```bash
# 在 188 主機執行
scp k8s/monitoring/k3s-alerts.yaml ollama@192.168.0.188:/home/ollama/momo-pro/monitoring/alerts.yml

# 重載 Prometheus
docker restart prometheus
```

## 4. 驗證

```bash
# 檢查 metrics 端點
curl http://192.168.0.121:30888/metrics | head -50

# 在 Prometheus 查詢
# kube_deployment_status_replicas_available
# kube_pod_container_status_restarts_total
# kube_node_status_condition
```

## 5. 相關告警規則

| 告警名稱 | 觸發條件 | 嚴重度 |
|---------|---------|--------|
| PodRestartingTooMuch | 1 小時內重啟 > 3 次 | warning |
| DeploymentReplicasMismatch | 副本數不符 > 5 分鐘 | warning |
| PodPendingTooLong | Pending > 10 分鐘 | warning |
| NodeMemoryPressure | NPD 記憶體壓力 | critical |
| NodeDiskPressure | NPD 磁碟壓力 | critical |
| NodePIDPressure | NPD PID 壓力 | warning |
| NodeNotReady | 節點未就緒 > 2 分鐘 | critical |

---

## 架構圖

```
┌─────────────────────────────────────────────────────────────┐
│                    K3s 叢集 (120/121)                        │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ kube-state-metrics namespace                         │    │
│  │  ┌───────────────────┐  ┌─────────────────────────┐ │    │
│  │  │ kube-state-metrics│  │ Service (NodePort:30888)│ │    │
│  │  │     Pod           │←─│                         │ │    │
│  │  └───────────────────┘  └─────────────────────────┘ │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼ :30888
┌─────────────────────────────────────────────────────────────┐
│                 192.168.0.188 (ollama)                       │
│  ┌────────────┐    ┌──────────────┐    ┌──────────────────┐ │
│  │ Prometheus │───►│ Alertmanager │───►│ AWOOOI Telegram  │ │
│  │   :9090    │    │    :9093     │    │                  │ │
│  └────────────┘    └──────────────┘    └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
