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 主要移除了兩大類內容:

  1. Alpha 與非預設功能:清理未穩定的上游功能與相容層,縮小程式碼體積與潛在攻擊面。
  2. In-tree 雲端與儲存外掛程式:早期 Kubernetes 將各公有雲與儲存廠商驅動程式直接編譯進核心二進位檔(In-tree)。K3s 移除了這些龐大外掛程式,順應上游的兩項演進:將雲端整合拆為外部的 Cloud Controller Manager(CCM),並將儲存標準化為 CSI。K3s 依然能掛載各公有雲的外部 CCM 與標準 CSI 驅動程式。

內建打包的完整生態

K3s 在小於 100 MB 的單一二進位檔中整合了完整運作環境:

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 能夠直接與關聯式資料庫溝通。

  1. kube-apiserver
  2. etcd v3 gRPC APIKine (Datastore Shim)
  3. SQL (Prepared Statements)SQLite / MySQL / PostgreSQL

資料層規則與限制

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 能處理成員故障,備份才能處理資料遺失;兩者解決的是不同問題。


維運實務對照:憑證、升級與負載平衡

K3s 透過發行版的整合優勢,簡化了多項日常維運流程。

維運面向K3s 發行版kubeadm Vanilla 叢集
安裝部署單行 Shell 指令自動完成,內建 k3s kubectl手動安裝套件、手動初始化並自行設定 CNI
控制平面模型單行程 Goroutine 運作,containerd 為子行程靜態 Pod 由 kubelet 管理,各元件獨立行程
資料庫儲存單機預設 SQLite,HA 支援 Embedded etcd、外部 etcd 或外部 SQLStacked 或 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 代表接受了發行版預先選定的技術組合,使用者需留意以下邊界條件:

  1. Windows 節點限制:K3s Server 必須運作於 Linux 環境;官方 FAQ 目前明載 K3s 不原生支援 Windows。早期官方文件曾記載以實驗性 Worker Agent 搭配 Calico 網路加入的作法,該頁現已移除,採用前需自行驗證。
  2. 網路後端的選擇:預設 Flannel 支援 vxlan、host-gw 與 wireguard-native。若需使用 Cilium 等進階 CNI,須在啟動時指定 --flannel-backend=none,並建議同時設定 --disable-network-policy,避免與 CNI 自帶的 network policy 引擎衝突。
  3. ServiceLB 埠衝突:內建 ServiceLB 採用 HostPort 機制佔用節點實體通訊埠(Port)。若叢集內多個 Service 同時請求同一個通訊埠(如 80),只有其中一個能綁定成功,其餘 Service 將無法綁定。
  4. 雙協定堆疊限制:IPv4/IPv6 Dual-Stack 必須於叢集初始化時設定完成,無法於建立後動態啟用。

技術選擇與架構建議

  1. Need custom control-plane flags or 1000+ nodes?
  2. YESkubeadm / Managed K8s
  3. NOEdge, CI/CD, homelab, or limited etcd SRE capacity?
  4. YESK3s distribution
  5. NOCompare operational needs