# ADR-026: CoreDNS GitOps 管控架構

**狀態**: 批准
**日期**: 2026-03-26 (台北時區)
**決策者**: 統帥
**觸發**: DNS 解析問題 + NetworkPolicy 連鎖事故 (ADR-011)

## 問題陳述

```
事故時間線：
├── 2026-03-26: Telegram 告警失敗 → 發現 Pod 無法解析外部 DNS
├── 根因: CoreDNS forward 設定使用 /etc/resolv.conf
│         → 解析到 127.0.0.53 (systemd-resolved)
│         → 容器內無法使用宿主機 loopback
└── 修復後: 需要版本控制防止再次發生
```

**核心問題**:
1. CoreDNS 配置沒有版本控制
2. 手動修改容易遺失或被覆蓋
3. 與 K3s 內建 Helm Controller 衝突風險

---

## 決策：K3s HelmChartConfig + GitOps

### 為什麼不用純 ArgoCD？

| 方案 | 問題 |
|------|------|
| ArgoCD 管 kube-system | 與 K3s Helm Controller 衝突 |
| 直接 kubectl apply ConfigMap | K3s 會覆蓋手動修改 |
| **HelmChartConfig** | K3s 原生支援，不衝突 |

### 架構設計

```
┌─────────────────────────────────────────────────────────┐
│                 CoreDNS GitOps 架構                      │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Git Repository (版本控制)                               │
│  └── k8s/k3s-system/coredns-custom.yaml                 │
│           │                                              │
│           ▼                                              │
│  CD Pipeline (GitHub Actions)                           │
│  └── kubectl apply -f k8s/k3s-system/                   │
│           │                                              │
│           ▼                                              │
│  K3s Helm Controller                                    │
│  └── 偵測 HelmChartConfig 變更                          │
│           │                                              │
│           ▼                                              │
│  CoreDNS Deployment 更新                                │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

---

## 實作細節

### 1. 配置檔案 (`k8s/k3s-system/coredns-custom.yaml`)

```yaml
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: coredns
  namespace: kube-system
spec:
  valuesContent: |-
    servers:
      - zones:
          - zone: .
        port: 53
        plugins:
          - name: forward
            parameters: . 8.8.8.8 1.1.1.1  # 禁止使用 /etc/resolv.conf
```

### 2. CD 整合 (`.github/workflows/cd.yaml`)

```yaml
- name: Sync CoreDNS Config
  if: needs.detect-changes.outputs.k3s-system == 'true'
  run: kubectl apply -f k8s/k3s-system/coredns-custom.yaml
```

### 3. 路徑偵測

```yaml
k3s-system:
  - 'k8s/k3s-system/**'
```

---

## DNS 上游選擇

| 優先順序 | DNS 伺服器 | 說明 |
|----------|-----------|------|
| 1 | 8.8.8.8 | Google Public DNS |
| 2 | 1.1.1.1 | Cloudflare DNS |

**禁止清單**:
- `127.0.0.53` - systemd-resolved (容器無法使用)
- `/etc/resolv.conf` - 可能指向宿主機 loopback

---

## 驗收標準

| 項目 | 狀態 |
|------|------|
| HelmChartConfig 建立 | ✅ |
| CD workflow 整合 | ✅ |
| 版本控制於 Git | ✅ |
| 禁止 systemd-resolved | ✅ |

---

## 關聯文件

- ADR-011: NetworkPolicy 變更治理架構
- ADR-025: CI/CD AI 整合架構

---

## 附錄：驗證指令

```bash
# 檢查 CoreDNS ConfigMap
kubectl get cm coredns -n kube-system -o yaml

# 測試 DNS 解析
kubectl run dns-test --rm -it --image=busybox --restart=Never -- nslookup google.com

# 檢查 HelmChartConfig 狀態
kubectl get helmchartconfig -n kube-system
```