6f7a4be2c7
- ADR-062: Data Safety Guardrails (服務分級/Pre-flight/MultiSig) - ADR-063: Service Registry IaC 設計規範 - Sprint 5.1 方案文件: 規範驗證通過，P1-P5 問題修正 - P1: Playbook 存 Redis（非 SQL），M-001 改為 Pydantic model 修改 - P2: velero_client.py 命名維持（與 signoz_client 慣例一致） - P3: docker-health-monitor 狀態釐清 - P4/P5: DI setter + Deployment Verification 補充 - LOGBOOK: 當前焦點更新為 Sprint 5.1 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
93 lines
2.7 KiB
Markdown
93 lines
2.7 KiB
Markdown
# ADR-063 — Service Registry IaC 設計規範
|
||
|
||
> **狀態**: 已批准 (首席架構師裁示 2026-04-08)
|
||
> **撰寫**: Claude Sonnet 4.6 / 2026-04-08 Asia/Taipei
|
||
> **相關**: ADR-062 (Data Safety Guardrails)
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
ADR-062 決定使用靜態 YAML 儲存服務的 Stateful 分級（Q6 決策：IaC）。需要規範此 YAML 的設計原則、修改流程、以及與程式碼的整合方式。
|
||
|
||
---
|
||
|
||
## 設計原則
|
||
|
||
**Infrastructure as Code**：服務的 Stateful 屬性是架構本質，不允許在 Web UI 上隨意修改。所有變更必須透過 Git PR + 統帥審核。
|
||
|
||
---
|
||
|
||
## 檔案位置
|
||
|
||
```
|
||
ops/config/service-registry.yaml
|
||
```
|
||
|
||
此路徑在 `service_registry.py` 中以相對於 repo root 的方式計算：
|
||
```python
|
||
Path(__file__).parents[5] / "ops" / "config" / "service-registry.yaml"
|
||
```
|
||
|
||
---
|
||
|
||
## YAML 結構規範
|
||
|
||
```yaml
|
||
services:
|
||
- name: <service_name> # 唯一識別，對應 container name / k8s service name
|
||
display_name: <顯示名稱>
|
||
host: <IP 或 "k3s">
|
||
stateful_level: BLOCK | CRITICAL_HITL | STANDARD_HITL | AUTO
|
||
reason: <說明為何此分級> # 必填，記錄決策依據
|
||
alert_only: true # 僅 BLOCK 使用
|
||
requires_pre_backup: false # CRITICAL_HITL 使用
|
||
restart_command: "docker start" # 特殊重啟命令（如 Prometheus/Grafana）
|
||
containers: ["container-name"] # docker container 名稱（可多個）
|
||
|
||
backup_policies:
|
||
velero_max_age_hours: 4
|
||
emergency_backup_timeout: 600
|
||
block_backup_on_high_io: true
|
||
io_threshold_percent: 80
|
||
|
||
multisig:
|
||
critical_required_votes: 2
|
||
standard_required_votes: 1
|
||
vote_expiry_minutes: 30
|
||
```
|
||
|
||
---
|
||
|
||
## 分級決策標準
|
||
|
||
| 分級 | 標準 |
|
||
|------|------|
|
||
| `BLOCK` | 有 PostgreSQL WAL / ClickHouse 列欄資料 / 重啟必然造成資料遺失或損壞 |
|
||
| `CRITICAL_HITL` | 有 Volume 掛載 / 重啟可能中斷活躍寫入 / AWOOOI 核心依賴 |
|
||
| `STANDARD_HITL` | 有 WAL 或狀態但可安全 `docker start`（非 restart）/ 監控基礎設施 |
|
||
| `AUTO` | 無狀態 / K3s Pod（有 PDB 保護）/ 重啟只影響短暫可用性 |
|
||
|
||
---
|
||
|
||
## 維護流程
|
||
|
||
1. 新增服務 → PR to `ops/config/service-registry.yaml`
|
||
2. PR 描述必須說明：服務名稱、分級、理由
|
||
3. 統帥審核後 merge
|
||
4. ServiceRegistryClient 下次載入時自動生效（singleton 有 lazy load）
|
||
|
||
---
|
||
|
||
## 失敗行為（Fail-Safe）
|
||
|
||
ServiceRegistryClient 讀取失敗時 **fallback AUTO**（不阻擋告警流程），並記錄 ERROR log。此設計確保 Service Registry 本身的故障不會導致整個告警鏈路中斷。
|
||
|
||
---
|
||
|
||
## 未來擴充
|
||
|
||
- 服務依賴關係（dependency edges）→ Sprint 5 拓撲圖使用
|
||
- 備份策略客製化（每個服務獨立設定）
|
||
- 動態覆寫（緊急情況時可 kubectl configmap 注入）
|