0a9d94d82b
問題: DNS 配置沒有版本控制，手動修改易遺失 架構: - k8s/k3s-system/coredns-custom.yaml: HelmChartConfig - CD workflow: k3s-system 路徑偵測 + 自動 apply - ADR-026: CoreDNS GitOps 管控架構 DNS 上游: - 使用 8.8.8.8 + 1.1.1.1 - 禁止 /etc/resolv.conf (systemd-resolved) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
143 lines
4.1 KiB
Markdown
143 lines
4.1 KiB
Markdown
# 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
|
||
```
|