Merge pull request 'docs(analysis): 新增 K8s 本機模擬待辦記錄' (#77) from docs/k8s-local-simulation-todo into master
Reviewed-on: #77
This commit was merged in pull request #77.
This commit is contained in:
@@ -0,0 +1,132 @@
|
||||
# CFDivePlatform K8s 本機模擬待辦
|
||||
|
||||
> 記錄日期：2026-10-29
|
||||
> 狀態：**僅記錄，尚未規劃、尚未動工**（Hank 指示「先記待辦」）。
|
||||
> 範圍：在本機以 Docker Desktop Kubernetes 模擬部署，驗證 manifest 與流程；`docker-compose.yml` 維持本地開發用，不更動。
|
||||
> 實作原則：涉及行為或部署流程變更，先走 OpenSpec（`/opsx:propose`）；本文的決策與清單是規劃輸入，不是 spec。
|
||||
> 搭配閱讀：`docs/analysis/2026-10-14-project-review-todo.md`（M6、M8 與本項有相依）。
|
||||
|
||||
---
|
||||
|
||||
## 已做的決策（2026-10-29 討論）
|
||||
|
||||
| 項目 | 決策 | 理由 |
|
||||
|---|---|---|
|
||||
| 模擬環境 | Docker Desktop 內建 Kubernetes，**Kubeadm（單節點）模式** | 目的是驗證 manifest 與部署流程，不需要多節點；設定最簡單 |
|
||||
| 與 Compose 的關係 | Compose 照舊作為本地開發環境，K8s 另放獨立目錄（暫定 `k8s/`） | 兩邊互不影響，避免動到現有 `deploy.yml` |
|
||||
| image | 沿用現有 `Dockerfile` 的 `app`、`web` 兩個 target | 與正式環境的 compose（不含 `compose.override.yml`）同一種形態，落差最小 |
|
||||
| 隔離 | 每個專案一個 namespace | 另一個 .NET 專案會一起模擬 |
|
||||
| 上機器的時機 | 本機模擬驗證完成後，再決定實際叢集 | VPS 資源不足，見下節 |
|
||||
|
||||
## 為什麼不直接在現有 VPS 上裝 K3s
|
||||
|
||||
2026-10-29 實測：2 核、1.9GB RAM（可用約 770MB）、磁碟剩 9.2GB（72%），且已跑 13 個容器（含 Gitea、Gitea runner、Nginx Proxy Manager）。
|
||||
K3s 單節點自身約需 0.5–1GB，會讓 OOM 風險落在現有正式站與 CI。若之後要上實體叢集，建議另租至少 2 核 4GB、40GB 磁碟的機器。
|
||||
|
||||
---
|
||||
|
||||
## 總覽
|
||||
|
||||
| # | 項目 | 依賴 | 是否走 OpenSpec |
|
||||
|---|------|------|----------------|
|
||||
| K1 | 決定 Ingress controller | — | 否（決策） |
|
||||
| K2 | 盤點 CFDive 的 K8s 資源清單 | — | 否（盤點） |
|
||||
| K3 | 撰寫 CFDive manifest（`k8s/`） | K1、K2 | 是 |
|
||||
| K4 | 本機部署與驗證 | K3 | 是（含驗證項目） |
|
||||
| K5 | 另一個 .NET 專案納入同一叢集 | K1、K4 | 另案（該專案的 repo） |
|
||||
| K6 | 上傳檔案切 S3／R2 | 外部帳號 | 是（既有暫緩項目） |
|
||||
| K7 | 上實體叢集前的差距清單 | K4 | 否（文件） |
|
||||
|
||||
---
|
||||
|
||||
## K1 決定 Ingress controller
|
||||
|
||||
**現況**
|
||||
Docker Desktop 沒有內建 Ingress。K3s 預設是 Traefik；原本考慮的 ingress-nginx，**據我所知 Kubernetes 社群已宣布它在 2026 年 3 月退役，此點為記憶，尚未查證**。
|
||||
|
||||
**待辦**
|
||||
- [ ] 查證 ingress-nginx 目前的維護狀態（官方公告）
|
||||
- [ ] 在 Traefik 與 Gateway API 實作之間決定（暫定傾向 Traefik：與 K3s 預設一致，之後搬 K3s 的 manifest 改動最少）
|
||||
- [ ] 確認 Reverb（WebSocket）在所選 Ingress 上的路由與逾時設定
|
||||
|
||||
## K2 盤點 CFDive 的 K8s 資源清單
|
||||
|
||||
**現況（依 `docker-compose.yml` 服務名稱，2026-10-29 核對）**
|
||||
`app`、`nginx`、`frontend`、`db`、`scheduler`、`queue-worker`、`redis`、`reverb`。volumes 為 `mysql-data`、`redis-data`、`storage-app-public`。
|
||||
|
||||
**暫定對應（未驗證）**
|
||||
- `app`、`nginx`、`frontend`、`queue-worker`、`reverb`：各一個 Deployment＋必要的 Service
|
||||
- `scheduler`：Deployment，**副本固定 1**（多副本會讓排程重複執行）
|
||||
- migration／cache／swagger：目前在 `deploy.yml`，需改為 Job（或 initContainer）
|
||||
- `.env`：拆成 ConfigMap（非機密）與 Secret（機密）；`env_file:` 在 K8s 沒有對等物
|
||||
- `db`、`redis`：本機模擬時先決定放叢集內，或沿用 Compose 容器經 `host.docker.internal` 連線
|
||||
|
||||
**待辦**
|
||||
- [ ] 逐一核對各服務的 port、healthcheck、啟動指令、依賴順序
|
||||
- [ ] 決定 MySQL／Redis 放叢集內還是沿用 Compose（叢集內較貼近正式環境，Compose 較省事）
|
||||
- [ ] 注意 `tests/bootstrap.php` 的覆蓋清單：擴大環境變數注入範圍時需同步檢查（見專案記憶中 `env_file` 事件）
|
||||
|
||||
## K3 撰寫 CFDive manifest
|
||||
|
||||
**待辦**
|
||||
- [ ] 目錄結構（`k8s/` 下用 Kustomize 或純 YAML，擇一）
|
||||
- [ ] 各 Deployment 的探針（readiness／liveness）對應現有 healthcheck
|
||||
- [ ] 加上 `requests`／`limits`，總量抓接近目標機器（例如 4GB 節點），避免本機資源充裕而漏掉 OOM 問題
|
||||
- [ ] Secret 結構與正式環境相同，本機只用假值
|
||||
- [ ] 環境值用正式設定：`APP_ENV=production`、`APP_DEBUG=false`、MySQL `8.0`、Redis `alpine`
|
||||
- [ ] 不帶入 `compose.override.yml` 的 bind mount
|
||||
|
||||
## K4 本機部署與驗證
|
||||
|
||||
**待辦**
|
||||
- [ ] Docker Desktop 啟用 Kubernetes（Kubeadm 模式），確認 `kubectl` 指向正確 context
|
||||
- [ ] 本機 build `app`、`web`、`frontend` image，`imagePullPolicy` 設為 `IfNotPresent`（或 `Never`）
|
||||
- [ ] 驗證：登入、預約、評價主流程；Reverb 即時訊息（WebSocket 經 Ingress）；queue job 實際被消化；scheduler 只有一個實例
|
||||
- [ ] 驗證：migration Job 失敗時的行為（不應讓新版本 Pod 起來）
|
||||
- [ ] 驗證：滾動更新與回滾（`kubectl rollout`）
|
||||
- [ ] 記錄與 Compose 行為不一致之處
|
||||
|
||||
## K5 另一個 .NET 專案納入同一叢集
|
||||
|
||||
**注意事項（屬該專案 repo，這裡只記備忘）**
|
||||
- ASP.NET Core（.NET 8 以後）官方 image 預設非 root、監聽 8080，Service 的 `targetPort` 要對
|
||||
- 巢狀設定以環境變數覆蓋時用雙底線，例如 `ConnectionStrings__Default`
|
||||
- 需自行提供健康檢查端點供探針使用
|
||||
- EF migration 用 Job，不要在應用啟動時跑
|
||||
- 多副本時需處理 Data Protection 金鑰共用，否則副本間 cookie／antiforgery 互相無法解密
|
||||
|
||||
**待辦**
|
||||
- [ ] 兩個專案用不同 namespace 與 hostname（例如 `cfdive.localhost`、`other.localhost`），共用同一個 Ingress controller
|
||||
|
||||
## K6 上傳檔案切 S3／R2
|
||||
|
||||
**現況**
|
||||
`storage:migrate-to-s3` 指令與 `FILESYSTEM_DISK` 設定已完成（PR #55、#56），但 R2／S3 帳號尚未申請，VPS 仍是 `FILESYSTEM_DISK=local`，上傳檔案存在具名 volume `storage-app-public`。
|
||||
多副本時 ReadWriteMany 儲存是最大阻礙；**本機 hostpath 單機無法代表這個問題**，所以這項要在上實體叢集前完成。
|
||||
|
||||
**待辦**
|
||||
- [ ] 取得 S3 相容服務帳號後，另開 OpenSpec change 接續（不要回頭改已歸檔的 `cloud-ready-s3-storage`）
|
||||
|
||||
## K7 上實體叢集前的差距清單
|
||||
|
||||
本機模擬**無法**驗證的項目，上實體叢集後需另外確認：
|
||||
|
||||
| 項目 | 原因 |
|
||||
|---|---|
|
||||
| 多節點調度、節點故障 | Kubeadm 模式為單節點 |
|
||||
| 檔案儲存的 ReadWriteMany | 本機 hostpath 僅單機 |
|
||||
| TLS／憑證、真實網域 | 本機用 `*.localhost`，無 Let's Encrypt |
|
||||
| 真實流量與資源競爭 | 本機資源充裕 |
|
||||
| Gitea Actions 到叢集的部署流程 | 需等有目標叢集；另需 image registry（目前 image 在 VPS 上 build，是否有 registry 未確認） |
|
||||
|
||||
**待辦**
|
||||
- [ ] 確認 VPS 現行部署是否有 image registry；沒有的話，上叢集前要決定放哪裡
|
||||
- [ ] 決定實體叢集（另租 K3s 機器，或雲端託管）
|
||||
|
||||
---
|
||||
|
||||
## 開放問題
|
||||
|
||||
- 本機機器規格（Docker Desktop 分配給 WSL2 的記憶體）未確認；兩個專案加 MySQL／Redis 同時跑，建議 8GB 以上
|
||||
- Kubeadm 模式下本機 image 是否可直接被 Pod 使用，依記憶判斷為可，**尚未在實際版本驗證**
|
||||
- Ingress 最終選哪個（K1）
|
||||
Reference in New Issue
Block a user