84 lines
2.5 KiB
Markdown
84 lines
2.5 KiB
Markdown
# ADR-057: Drift Adopt 端點 — Gitea PR API 實作路徑
|
||
|
||
> **狀態**: ✅ 已批准並實作
|
||
> **日期**: 2026-04-04
|
||
> **決策者**: 統帥 + 首席架構師
|
||
> **關聯 ADR**: ADR-056 (Config Drift Detection)
|
||
> **觸發原因**: 首席架構師 C2 裁示 — API Pod 內執行 git add -A 有安全漏洞
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
### 問題陳述
|
||
|
||
ADR-056 中 `adopt()` 端點的設計目標：將 K8s 實際狀態的合法漂移反向寫回 Git（使 Git 承認此次變更）。
|
||
|
||
原始實作使用 `_git_push()` 在 API Pod 內執行 `git add -A && git commit && git push gitea main`，存在：
|
||
|
||
1. **安全風險**: `git add -A` 可能誤提交 Secret/ConfigMap 等敏感資料
|
||
2. **多副本問題**: 多個 API Pod 同時執行 git 操作會造成 conflict
|
||
3. **認證問題**: API Pod 需要持有 Gitea 認證，擴大攻擊面
|
||
4. **Bypass 審核**: 直接 push main 繞過 PR review 流程
|
||
|
||
---
|
||
|
||
## 決策（草案）
|
||
|
||
### D1: adopt() 端點改用 Gitea PR API
|
||
|
||
流程：
|
||
```
|
||
用戶按下 adopt → API 呼叫 Gitea API 建立 PR → SRE review → merge
|
||
```
|
||
|
||
具體實作：
|
||
1. API 呼叫 `POST /api/v1/repos/{owner}/{repo}/pulls`（Gitea API）
|
||
2. PR title: `chore: adopt drift — {namespace} {summary}`
|
||
3. PR body: 包含漂移詳情、Nemotron 意圖分析、影響評估
|
||
4. PR 建立後推送 Telegram 通知 SRE review
|
||
|
||
### D2: 分支命名規範
|
||
|
||
```
|
||
drift/adopt-{report_id[:8]}-{timestamp}
|
||
```
|
||
|
||
API 建立 branch 並 commit 對應 YAML 變更，再開 PR。
|
||
|
||
### D3: API Pod 認證方式
|
||
|
||
使用 Gitea API Token（現有 `GITEA_API_TOKEN` secret），只需 PR 建立權限，不需要 push main 權限。
|
||
|
||
---
|
||
|
||
## 實作前置條件
|
||
|
||
- [x] 統帥批准此 ADR (2026-04-05)
|
||
- [x] 確認 `GITEA_API_TOKEN` 已在 K8s Secret 中（kubectl patch 注入）
|
||
- [x] 確認 Gitea API `/repos/wooo/awoooi/pulls` 端點可用（測試通過）
|
||
- [ ] Phase 2: YAML diff 精確生成邏輯（目前加注解，欄位值需人工更新）
|
||
|
||
---
|
||
|
||
## 替代方案
|
||
|
||
| 方案 | 理由未採用 |
|
||
|------|-----------|
|
||
| 繼續 git push main（原實作） | 安全風險 + 多副本問題 |
|
||
| 完全移除 adopt() | 失去 GitOps 閉環能力 |
|
||
| 透過 Webhook 觸發 Gitea CI | 複雜度高，與現有 CD 流程耦合 |
|
||
|
||
---
|
||
|
||
## 狀態追蹤
|
||
|
||
| 項目 | 狀態 |
|
||
|------|------|
|
||
| 首席架構師 C2 裁示（暫停 git push） | ✅ 2026-04-04 |
|
||
| adopt() 端點回傳 501 | ✅ 2026-04-04 |
|
||
| ADR-057 起草 | ✅ 2026-04-05 |
|
||
| 統帥批准 ADR-057 | ✅ 2026-04-05 |
|
||
| Gitea PR API 實作 | ✅ 2026-04-05 — commit a81bf50 |
|
||
| GITEA_API_TOKEN 注入 K8s Secret | ✅ 2026-04-05 |
|