wooo/awoooi
1
1
Fork 0
Code Issues 2 Pull Requests 1 Actions 2 Packages Projects Releases Wiki Activity

docs: 新增 ADR-025 告警鏈路 E2E 驗證 + 更新 Skills

Browse Source 
新增:
- ADR-025: 告警鏈路 E2E 驗證架構 (2026-03-26 事故教訓)

更新:
- ADR-011: 新增 DNS 規則最佳實踐 (附錄 B)
- Skill 04: 新增 NetworkPolicy DNS 規則 + CoreDNS 設定
- Skill 05: 新增告警鏈路 Smoke Test 要求
- CLAUDE.md: 新增告警鏈路驗證到任務前必讀

事故根因:
1. URL 路徑錯誤 (webhook vs webhooks)
2. NetworkPolicy DNS 規則標籤不匹配
3. CoreDNS 上游 DNS 依賴 systemd-resolved

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OG T
2026-03-26 15:34:12 +08:00
parent 579da38b8b
commit 14c81f728f
5 changed files with 473 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/adr/ADR-011-networkpolicy-governance.md
View File

@@ -265,7 +265,7 @@ k8s/awoooi-prod/
---
## 附錄: 今日事故根因分析
## 附錄 A: 2026-03-23 事故根因分析
```
2026-03-23 Y 按鈕執行超時
@@ -286,3 +286,54 @@ k8s/awoooi-prod/
2. NetworkPolicy 需要允許完整路由路徑
3. 變更前應該用 dry-run 驗證
```
---
## 附錄 B: 2026-03-26 DNS 規則事故根因分析
```
2026-03-26 兩天無 Telegram 告警
根因 1: Alertmanager URL 路徑錯誤
設定: /api/v1/webhook/alertmanager (單數)
實際: /api/v1/webhooks/alertmanager (複數)
結果: 404 Not Found
根因 2: NetworkPolicy DNS 規則標籤錯誤
設定: podSelector 要求 environment=prod, system=awoooi
實際: CoreDNS 只有 k8s-app=kube-dns
結果: Pod 無法連接 CoreDNS
根因 3: CoreDNS 上游 DNS 設定錯誤
設定: forward . /etc/resolv.conf → 127.0.0.53 (systemd-resolved)
實際: 容器內無法使用 127.0.0.53
結果: 外部 DNS 解析失敗
修復:
1. Alertmanager ConfigMap 修正 URL 路徑
2. NetworkPolicy 使用正確的 namespaceSelector
3. CoreDNS 改用 8.8.8.8 1.1.1.1
教訓:
1. URL 路徑必須經過 E2E 測試驗證 (ADR-025)
2. NetworkPolicy DNS 規則必須使用 namespace selector
3. CoreDNS 不能依賴宿主機的 systemd-resolved
```
### DNS 規則最佳實踐
```yaml
# ✅ 正確的 DNS 規則寫法
- ports:
- port: 53
protocol: UDP
- port: 53
protocol: TCP
to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: kube-system
podSelector:
matchLabels:
k8s-app: kube-dns
```

196
docs/adr/ADR-025-alert-chain-e2e-validation.md Normal file
View File

@@ -0,0 +1,196 @@
# ADR-025: 告警鏈路 E2E 驗證架構
**狀態**: 批准
**日期**: 2026-03-26
**決策者**: 統帥
**觸發**: URL 路徑錯誤 + NetworkPolicy DNS 規則錯誤導致 2 天無告警
## 問題陳述
```
事故時間線 (2026-03-26):
├── Alertmanager 設定 /api/v1/webhook/alertmanager (單數)
├── API 實際路徑 /api/v1/webhooks/alertmanager (複數)
├── 結果: 404 Not Found，所有告警丟失
├── 同時: NetworkPolicy DNS 規則使用錯誤標籤
├── CoreDNS 無法解析外部 DNS (使用 127.0.0.53)
└── 後果: 2 天完全無 Telegram 告警
```
**根本原因**:
1. 沒有 E2E 測試驗證 Alertmanager → API → Telegram 鏈路
2. 部署後沒有 Smoke Test 確認端點可達
3. NetworkPolicy DNS 規則標籤與 CoreDNS 不匹配
4. CoreDNS 上游 DNS 設定依賴 systemd-resolved (容器內無效)
---
## 決策：四層驗證架構
```
┌──────────────────────────────────────────────────────────────────────┐
│ 告警鏈路 E2E 驗證架構 │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: 部署後 Smoke Test (強制) │
│ ═══════════════════════════════════ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 每次部署後自動執行: │ │
│ │ 1. curl POST /api/v1/webhooks/alertmanager (測試告警) │ │
│ │ 2. 驗證回應 success=true │ │
│ │ 3. 驗證 Telegram message_id 存在 │ │
│ │ 4. 失敗 → 部署回滾 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Layer 2: DNS 連通性檢查 │
│ ══════════════════════════ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Health Probe 必須包含: │ │
│ │ - 內部 DNS: kubernetes.default.svc.cluster.local │ │
│ │ - 外部 DNS: api.telegram.org │ │
│ │ 任一失敗 → Pod 標記 Not Ready │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Layer 3: 鏈路心跳監控 │
│ ════════════════════════ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Prometheus 規則: │ │
│ │ - awoooi_alerts_received_total │ │
│ │ - awoooi_telegram_sent_total │ │
│ │ 連續 1 小時為 0 → 觸發 CRITICAL 告警 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Layer 4: ConfigMap 驗證 Hook │
│ ════════════════════════════ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Alertmanager ConfigMap 修改前: │ │
│ │ 1. 提取 webhook URL │ │
│ │ 2. curl 測試 URL 可達性 │ │
│ │ 3. 必須收到 200 或 422 (格式錯但端點存在) │ │
│ │ 4. 驗證失敗 → 阻止 apply │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
```
---
## 實施細節
### 1. 部署後 Smoke Test
```yaml
# CI/CD 強制步驟
- name: Alert Chain Smoke Test
run: |
# 發送測試告警
RESPONSE=$(curl -s -X POST "$API_URL/api/v1/webhooks/alertmanager" \
-H 'Content-Type: application/json' \
-d '{"receiver":"smoke-test","status":"firing","alerts":[{"status":"firing","labels":{"alertname":"SmokeTest","severity":"info"},"annotations":{"summary":"CI Smoke Test"}}]}')
# 驗證成功
echo "$RESPONSE" | jq -e '.success == true' || exit 1
echo "Alert chain smoke test passed"
```
### 2. NetworkPolicy DNS 規則 (正確寫法)
```yaml
# ❌ 錯誤: 使用不存在的標籤
- ports:
- port: 53
to:
- podSelector:
matchLabels:
environment: prod # CoreDNS 沒有這個標籤！
k8s-app: kube-dns
system: awoooi # CoreDNS 沒有這個標籤！
# ✅ 正確: 使用 namespace selector
- ports:
- port: 53
protocol: UDP
- port: 53
protocol: TCP
to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: kube-system
podSelector:
matchLabels:
k8s-app: kube-dns
```
### 3. CoreDNS 上游 DNS 設定
```yaml
# ❌ 錯誤: 使用 /etc/resolv.conf (指向 127.0.0.53)
forward . /etc/resolv.conf
# ✅ 正確: 使用真實 DNS 伺服器
forward . 8.8.8.8 1.1.1.1
```
### 4. Prometheus 鏈路監控規則
```yaml
groups:
- name: alert-chain-health
rules:
- alert: AlertChainBroken
expr: increase(awoooi_alerts_received_total[1h]) == 0
for: 1h
labels:
severity: critical
annotations:
summary: "告警鏈路斷裂！1 小時內沒有收到任何告警"
- alert: TelegramNotificationFailed
expr: increase(awoooi_telegram_sent_total[1h]) == 0 and increase(awoooi_alerts_received_total[1h]) > 0
for: 30m
labels:
severity: critical
annotations:
summary: "Telegram 通知失敗！有告警但沒有發送成功"
```
---
## URL 路徑規範
| 正確 | 錯誤 |
|-----|------|
| `/api/v1/webhooks/alertmanager` | `/api/v1/webhook/alertmanager` |
| 複數形式 `webhooks` | 單數形式 `webhook` |
| `/api/v1/approvals` | `/api/v1/approval` |
| `/api/v1/incidents` | `/api/v1/incident` |
**原則**: API Router 統一使用複數命名
---
## 驗收標準
| 項目 | 狀態 |
|------|------|
| CI/CD 包含 Alert Chain Smoke Test | ⬜ |
| NetworkPolicy DNS 規則使用正確標籤 | ✅ |
| CoreDNS 使用真實上游 DNS | ✅ |
| Prometheus 鏈路監控規則已部署 | ⬜ |
| ConfigMap 修改前驗證 Hook | ⬜ |
---
## 教訓
> "路徑差一個 s，所以 404" — 這種低級錯誤絕對不能再犯。
> 必須靠自動化驗證，不能靠人眼審查。
---
## 關聯文件
- Memory: `feedback_alertchain_e2e_validation.md`
- ADR-011: NetworkPolicy 變更治理架構
- Skill 04: DevOps Commander
- Skill 05: SRE QA