awoooi/docs/adr/ADR-026-coredns-gitops.md

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)

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)

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

3. 路徑偵測

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 整合架構

---

附錄：驗證指令

# 檢查 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