# 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 注入）