K3s 如何把 Kubernetes 控制平面裝進單一行程?
K3s 是一套輕量的 Kubernetes 發行版,把控制平面、容器執行環境、網路與儲存全部打包進一個不到 100 MB 的二進位檔。本文以 kubeadm 建立的標準叢集來對照,了解它修改、簡化了哪些地方。
kubeadm 是純粹的引導工具(Bootstrap Tool)。根據 kubeadm 官方文件說明:
kubeadm performs the actions necessary to get a minimum viable cluster up and running. By design, it cares only about bootstrapping, not about provisioning machines.
kubeadm 不負責節點佈建、網路外掛程式(CNI)、Ingress 或負載平衡器,連 CNI 都要求在初始化後手動部署。
K3s 則是發行版(Distribution),這些元件都已預先選好並內建。本文比較兩者建出的叢集,後續各項技術差異皆源自「發行版 vs. 引導工具」的定位落差。
起源與 CNCF 定位
K3s 由 Rancher Labs 的 Darren Shepherd 於 2019 年 2 月開發並開源(首個版本 v0.1.0 於 2019 年 2 月 26 日釋出)。其設計初衷是為了邊緣運算(Edge)、物聯網(IoT)、ARM 裝置與 CI 環境,提供一套資源消耗極低卻具備完整 API 的輕量化 Kubernetes。
所謂完整 API,是指上游 Kubernetes 的穩定版 API 在 K3s 上都能使用。Deployment、Service、CRD、RBAC 照常運作,原本的 kubectl 指令、Helm Chart 和 Operator 也不必修改。換言之,K3s 精簡了元件執行與打包方式,API 本身沒有縮水。
2020 年 Rancher Labs 併入 SUSE,同年 8 月將 K3s 捐贈予雲端原生運算基金會(CNCF),使其成為第一個進入 CNCF 的 Kubernetes 發行版。
CNCF 把專案分成 Sandbox、Incubating、Graduated 三個成熟度等級,截至 2026 年 10 月,K3s 仍是最初階的 Sandbox 專案。以 K3s 的普及程度,這個等級或許出乎意料;不過 CNCF 評估的是專案治理,不是使用規模,兩者不一定同步。
在相容性方面,K3s 擁有 CNCF Certified Kubernetes 一致性認證。官方文件強調:
K3s is a CNCF-certified Kubernetes distribution, and can do everything required of a standard Kubernetes cluster.
這項認證要求通過上游的一致性測試並由 CNCF 審核,讓前面提及的 API 相容性具備客觀依據。
架構簡化:移除與整合了哪些元件
K3s 的輕量化設計可以拆解為兩大面向:移除冗餘元件,以及將必要元件全數內建。
移除的元件與考量
K3s 主要移除了兩大類內容:
- Alpha 與非預設功能:清理未穩定的上游功能與相容層,縮小程式碼體積與潛在攻擊面。
- In-tree 雲端與儲存外掛程式:早期 Kubernetes 將各公有雲與儲存廠商驅動程式直接編譯進核心二進位檔(In-tree)。K3s 移除了這些龐大外掛程式,順應上游的兩項演進:將雲端整合拆為外部的 Cloud Controller Manager(CCM),並將儲存標準化為 CSI。K3s 依然能掛載各公有雲的外部 CCM 與標準 CSI 驅動程式。
內建打包的完整生態
K3s 在小於 100 MB 的單一二進位檔中整合了完整運作環境:
- 容器執行環境:containerd 與 runc
- 網路外掛程式(CNI):Flannel(預設)
- 叢集 DNS:CoreDNS
- 資源監控:metrics-server
- Ingress 控制器:Traefik
- 負載平衡實作:Klipper LoadBalancer(ServiceLB)
- 本地儲存:local-path-provisioner
- 套件管理:helm-controller
Flannel 本身不具備 NetworkPolicy 防火牆能力,因此 K3s 內建了 kube-router 的 netpol controller 函式庫。而社群常誤傳 kube-proxy 已被移除,實際上它依然存在,由 K3s Agent 透過 Goroutine 內建執行(可用 --disable-kube-proxy 參數停用)。
執行模型:Goroutine 單一行程 vs. 靜態 Pod
K3s 與 kubeadm 原生叢集最根本的結構差異,在於執行模型。
在 kubeadm 部署的叢集中,控制平面元件(kube-apiserver、kube-scheduler、kube-controller-manager 與 etcd)皆以靜態 Pod(Static Pod)的形式存在於 /etc/kubernetes/manifests 中,由 kubelet 監控並運作於 Host 網路。
K3s 則採取不同架構:所有控制平面元件皆以 Goroutine 形式運作於單一 K3s 行程內。
kubeadm Vanilla Cluster:
+-------------------------------+
| kubelet |
| Static Pods (Processes): |
| - kube-apiserver |
| - kube-controller-manager |
| - kube-scheduler |
| - etcd |
+-------------------------------+
K3s Distribution:
+-------------------------------+
| K3s Server (Single Process) |
| Goroutines: |
| - API Server |
| - Controller Manager |
| - Scheduler |
| - Embedded etcd / Kine Engine |
+-------------------------------+
| (supervises child process)
v
+-------------------------------+
| containerd (Process) |
+-------------------------------+
原始程式碼中,API Server 透過 apiapp.NewAPIServerCommand() 啟動,Scheduler 透過 sapp.NewSchedulerCommand() 啟動,Controller Manager、kubelet 與 kube-proxy 亦由同一個 Go runtime 統一排程。節點上另一個核心元件 containerd 則採用不同的執行方式:它作為子行程由 K3s 管理。
故障排除入口與重啟範圍如何改變
這個差異會直接改變故障排除入口。在 kubeadm 叢集中,管理員可以從 kube-system 裡的控制平面 Pod 檢視狀態與日誌;在 K3s 中,API Server 與 Scheduler 並沒有各自的控制平面 Pod。即使 kubectl get pods -n kube-system 看不到它們,也不代表元件未啟動。
以 systemd 管理的 Server 為例,應先檢視服務狀態與服務日誌:
# 在 K3s Server 主機上查看服務與控制平面日誌
sudo systemctl status k3s
sudo journalctl -u k3s -b --no-pager
# containerd 另有自己的日誌檔
sudo tail -n 100 /var/lib/rancher/k3s/agent/containerd/containerd.log
CoreDNS、Traefik 與 metrics-server 等內建附加元件仍以 Pod 運作,可以照常使用 kubectl logs 查修。打包成單一二進位檔,並不代表所有元件都在同一個行程裡執行;控制平面、containerd 與附加元件各有不同的執行與日誌位置。
共享行程也改變了重啟範圍。重啟 k3s 服務時,該 Server 的控制平面元件會一起重啟,無法像獨立靜態 Pod 那樣只重啟 Scheduler。這意味著維護單一元件時,必須考量同一台 Server 上其他控制平面元件的短暫中斷。
不過,K3s 停止時,已啟動的 Pod 容器仍會繼續執行。控制平面暫停與工作負載停止是不同的事件;既有容器能繼續跑,也不代表期間還能正常接受 API 請求或進行排程。
NOTE
日誌等級限制:Kubernetes 元件共用同一行程的 klog 設定,無法分別設定日誌等級與輸出位置。K3s 提供 --debug 增加日誌細節,但對個別元件傳入 -v= 或 --vmodule=,不一定會產生預期效果。
資料層抽象:Kine 與儲存選擇
標準 Kubernetes 僅支援 etcd 作為狀態儲存媒介。K3s 透過自行開發的資料庫轉換層 Kine(Kine Is Not etcd),打破了這項限制。
Kine 實作了 etcd v3 的 gRPC 介面,並將其翻譯為標準 SQL 查詢,使 API Server 能夠直接與關聯式資料庫溝通。
- kube-apiserver
- etcd v3 gRPC APIKine (Datastore Shim)
- SQL (Prepared Statements)SQLite / MySQL / PostgreSQL
資料層規則與限制
- 單節點預設 SQLite:單一 Server 節點預設採用 SQLite,完全免除外部儲存相依性。
- 高可用性架構選項:多 Server 部署時,可選用內建的嵌入式 etcd(Embedded etcd)、外部 etcd,或外部 SQL 資料庫(官方認證版本為 MySQL 8.0/8.4、MariaDB 10.11/11.4、PostgreSQL 15/16/17)。
- 嚴格的單調遞增限制:
kube-apiserver的 Watch 機制與快取同步嚴格依賴全域單調遞增的resourceVersion。Kine 為此要求資料庫的 revision 必須從 0 開始且每次嚴格遞增 1。 - 連線池限制:Kine 需要資料庫支援 Prepared Statements,使用 PgBouncer 等連線池中介軟體時需特別調整設定。
WARNING
多主寫入不相容:Kine 依賴嚴格單調遞增(+1)的 Revision 語意,無法搭配 Galera 等採用非連續跳號機制的多主寫入(Multi-Master)資料庫架構。
從單一 Server 走向高可用性
既有 SQLite 叢集可以在重啟 Server 時加入 --cluster-init,將資料層轉為 Embedded etcd。完成後,其他 Server 才能使用相同的 Server token,透過 --server https://<既有-server>:6443 加入叢集。
資料層轉換只完成第一步;容錯能力取決於 etcd 成員數。 官方的 Embedded etcd HA 架構要求至少三台 Server,並採用奇數成員數量。etcd 需要多數成員同意才能持續運作:兩台 Server 必須兩台都線上,三台則只需兩台。因此,加到兩台仍無法容忍任何一台故障;三台才具備容忍一台故障的能力。
增加 Agent 不會改善這項控制平面容錯能力,因為 Agent 不參與 etcd quorum。若希望從個人實驗環境擴充成可持續提供服務的叢集,規劃的應是 Server 數量與故障分布,而不只是總節點數。
多台 Server 還必須維持關鍵設定一致:包括 --cluster-cidr、--service-cidr、DNS 設定、元件停用選項與 --secrets-encryption。這些設定決定叢集共同使用的網路與功能;將它們納入同一套組態管理,才能避免各台 Server 逐漸產生差異。
快照與還原仍是維運責任
Embedded etcd 內建排程快照,也可使用 k3s etcd-snapshot save 手動建立快照,並將快照保存至 S3 相容儲存。對小型團隊而言,這省去了自行組裝 etcd 備份工具的工作。
但快照需要連同 Server token 一起保管。token 用於加密資料庫中的機密資料;還原時若沒有原本的 token,備份便無法使用。外部 SQL 資料庫的備份與還原則由資料庫管理工具負責,K3s 不會代為處理。
導入 HA 時仍需安排異地備份與還原演練。多台 Server 能處理成員故障,備份才能處理資料遺失;兩者解決的是不同問題。
NOTE
維運實務對照:憑證、升級與負載平衡
K3s 透過發行版的整合優勢,簡化了多項日常維運流程。
| 維運面向 | K3s 發行版 | kubeadm Vanilla 叢集 |
|---|---|---|
| 安裝部署 | 單行 Shell 指令自動完成,內建 k3s kubectl | 手動安裝套件、手動初始化並自行設定 CNI |
| 控制平面模型 | 單行程 Goroutine 運作,containerd 為子行程 | 靜態 Pod 由 kubelet 管理,各元件獨立行程 |
| 資料庫儲存 | 單機預設 SQLite,HA 支援 Embedded etcd、外部 etcd 或外部 SQL | Stacked 或 External etcd |
| 客戶端憑證 | 365 天效期,過期前 120 天內重啟服務自動續簽 | 365 天效期,僅在控制平面升級時續簽,否則需手動更新 |
| 版本升級 | 替換單一二進位檔或透過 CRD 自動控制器整套升級 | 依序執行 kubeadm upgrade,需自行維護 CNI 版本相容 |
| 高可用性負載 | Agent 內建 WebSocket 客戶端負載平衡,無需外部 LB | 控制平面前端必須自行設定外部負載平衡器 |
在憑證管理上,若 kubeadm 叢集長期未升級,管理員必須定期手動執行 kubeadm certs renew all 並重啟靜態 Pod;K3s 只要在憑證到期前 120 天內(舊版為 90 天)重啟服務,系統便會自動完成憑證續簽。
升級整合了什麼,又留下哪些工作
K3s 將 Kubernetes 與內建元件的版本組合放在同一個發行版中維護。採用預設組合的團隊,能少做一部分元件版本配對工作;但依然需要閱讀版本說明,確認升級後的 API、網路與 Ingress 行為符合現有工作負載。
手動升級可以重跑安裝腳本,或替換 /usr/local/bin/k3s 後重啟服務。重跑腳本時,原本透過環境變數或參數傳入的設定必須再次提供,否則可能遺失;若希望設定獨立於安裝腳本,可改用設定檔管理。
安裝腳本也不會自動 cordon 或 drain 節點。對短暫 API 中斷敏感的服務,需要由管理員規劃維護順序與節點處理方式。單一檔案讓升級操作簡單,服務影響仍須依叢集拓樸與工作負載判斷。
內建附加元件也有自己的設定邊界。K3s 會在每次啟動時重新產生內建元件的 manifest,直接修改這些檔案的內容無法可靠保留。若決定使用其他 Ingress 控制器,可以透過 --disable=traefik 停用內建 Traefik,再部署替代方案。
同樣地,自訂 CNI 可透過停用 Flannel 後安裝。採用自行部署的 CNI 或 Ingress,便需要自行追蹤其版本、安全更新與 Kubernetes 相容性。K3s 提供替換入口,團隊則接回被替換元件的維護責任。
Agent 端的負載平衡
在多節點高可用性架構下,K3s Agent 透過 WebSocket 向 Server 註冊並即時同步控制平面節點清單,原生具備客戶端負載平衡能力,免除了額外架設 HAProxy 或雲端 LB 的需求。
已知限制與架構邊界
選擇 K3s 代表接受了發行版預先選定的技術組合,使用者需留意以下邊界條件:
- Windows 節點限制:K3s Server 必須運作於 Linux 環境;官方 FAQ 目前明載 K3s 不原生支援 Windows。早期官方文件曾記載以實驗性 Worker Agent 搭配 Calico 網路加入的作法,該頁現已移除,採用前需自行驗證。
- 網路後端的選擇:預設 Flannel 支援
vxlan、host-gw與wireguard-native。若需使用 Cilium 等進階 CNI,須在啟動時指定--flannel-backend=none,並建議同時設定--disable-network-policy,避免與 CNI 自帶的 network policy 引擎衝突。 - ServiceLB 埠衝突:內建 ServiceLB 採用 HostPort 機制佔用節點實體通訊埠(Port)。若叢集內多個 Service 同時請求同一個通訊埠(如
80),只有其中一個能綁定成功,其餘 Service 將無法綁定。 - 雙協定堆疊限制:IPv4/IPv6 Dual-Stack 必須於叢集初始化時設定完成,無法於建立後動態啟用。
技術選擇與架構建議
- Need custom control-plane flags or 1000+ nodes?
- YESkubeadm / Managed K8s
- NOEdge, CI/CD, homelab, or limited etcd SRE capacity?
- YESK3s distribution
- NOCompare operational needs
- 適用 K3s 的情境:邊緣運算節點、IoT 裝置、內部 CI/CD 測試叢集、個人實驗室(Homelab),或缺乏專職 SRE 維運 etcd 叢集的中小型團隊。
- 適用 kubeadm 的情境:需要精準自訂控制平面各元件編譯參數、深度整合特定硬體或 Device Plugin、數千節點等級的大規模企業級叢集。
- 務實的視角:kubeadm 流程是理解 Kubernetes 底層運作與通過 CKA 認證的基石;而 K3s 則是驗證概念、部署邊緣服務與降低維運摩擦力的利器。