K3s 讓一條指令變叢集

K3s quick-start 讓一條 shell 指令直接變成可用的 Kubernetes 叢集。

我玩 Kubernetes 夠久了，最怕那種號稱 quick start 的文件。表面上很快，實際上是「你先貼上去，剩下自己猜」。命令跑完，log 一大坨，然後你開始找 kubeconfig、懷疑 node 名稱、再懷疑自己剛剛是不是把叢集裝成一台會鬧脾氣的小家電。

K3s 不一樣，但不是那種行銷話術講的「超簡單」。我看的是這份 K3s Quick-Start Guide，它厲害的地方在於很會處理無聊但致命的事：預設安裝路徑、服務化、工具放哪、怎麼加節點。這些都先幫你收好，讓你先有叢集，再談優化。

但這份文件短，短到有點像在故意考你。因為它假設你知道 sharp edges 在哪。我這篇不是重寫文件，是把每一段背後真正的意思拆開，順便補上我踩過的坑，讓你可以直接拿去用，不用把 quick-start 當魔法。

來源我主要看官方 quick-start：docs.k3s.io/quick-start。它沒有提供瀏覽數或書籤數，所以我不亂編。安裝腳本入口是 get.k3s.io，這個也一起放進來，因為那才是文件真正指向的東西。

這不是下載 binary，是把服務一起裝好

curl -sfL https://get.k3s.io | sh -

白話翻譯一下，這不是單純把 K3s 下載到磁碟上而已。它是在 systemd 或 openrc 上把服務也一起設好，讓它能在重開機、崩掉之後自動起來，還順便把你會真的用到的 client 工具放好。

我喜歡這點，因為它直接砍掉那種「裝好了，但只活在當前 shell」的尷尬。你如果手動拼過 Kubernetes 元件，就知道中間最煩的不是安裝，是讓它持久化。K3s 直接把這一段收掉，少掉很多半夜 debug 的鬼故事。

文件把腳本放在 https://get.k3s.io，這不是隨便貼個網址而已，是在劃邊界：這是官方支持的預設安裝路徑。很多團隊太早把 bootstrap 包成自己的流程，結果每台機器長得不一樣，之後再來怪叢集行為不一致。我真的看過太多次。

實操寫法很簡單：先在一台乾淨機器上跑一次官方腳本，先看它到底改了什麼，再決定要不要自動化。不要一開始就套五層 wrapper。先搞懂 service 名稱、設定檔位置、卸載方式，才知道你在自動化的是什麼。

• 先用官方腳本跑預設安裝。
• 把它當成 service 安裝，不是一次性的 local binary。
• 先看產生了什麼設定，再談客製化。

單機 K3s 本來就是完整叢集

文件有一句我覺得很多人會直接滑過去：單一 server 安裝就是「a fully-functional Kubernetes cluster」。這句很重要，因為很多人會不自覺覺得至少要三台機器才算數。不是這樣。

翻成工程語言就是，一台 server 已經自己扛了 datastore、control plane、kubelet、container runtime，整套都在。你不需要先加 agent 才算合法。agent 是為了容量或備援，不是因為第一台少了什麼神秘元件。

這也是 K3s 在邊緣設備、dev cluster 會被拿出來講的原因。我要測一個 manifest，真的不想先開三台 lab 機器。我要的是一台機器、一條指令、然後立刻拿到 kubeconfig 去打 API。quick-start 給的就是這個。

實操上，你就把第一台 server 當成完整叢集看待，除非你的需求真的不是這樣。做 demo、lab、小型內部工具，先停在單機沒問題。等你真的需要更多節點，再加 agent 或升級成高可用，不要一開始就把複雜度拉滿。

如果你要對照 Kubernetes 本體概念，官方文件還是值得開著：Kubernetes documentation。K3s 只是把安裝路徑簡化，不是把底層概念消失。

kubeconfig 才是你明天真的會用的東西

文件說 K3s 會把 kubeconfig 寫到 /etc/rancher/k3s/k3s.yaml，而且安裝好的 kubectl 會直接用它。這句很小，但實際上超有用。

也就是說，安裝完你已經有 credential 和 context 的 wiring，可以直接跟 API server 講話。你不用去家目錄亂翻，不用猜哪個 admin config 才是真的。預設路徑很明確，對半夜 debug 的人來說，這種明確很救命。

我之前在一台 spare box 上做小型測試叢集，就卡在這裡。安裝明明成功了，我卻還是下意識去找 ~/.kube。結果當然找不到。後來才想到 K3s 的路徑不是我習慣的那套。這種小細節看起來不重要，實際上很容易白白浪費二十分鐘。

實操寫法：裝完立刻驗證 kubeconfig 能不能讀、API server 能不能通。如果你用的不是 K3s 內建那個 kubectl，就明確指向那個檔案。不要假設你本機 shell 的設定知道 K3s 幹了什麼。

• 先找 /etc/rancher/k3s/k3s.yaml。
• 先用安裝時附的 kubectl，再換你自己的工具。
• 先驗證連線，再加 add-on 或自動化。

加入 agent 其實就兩個值，但 token 不能亂玩

curl -sfL https://get.k3s.io | K3S_URL = https://myserver:6443 K3S_TOKEN = mynodetoken sh -

文件展示的是 agent 節點的加入方式：把 K3S_URL 指到 server endpoint，再把 K3S_TOKEN 填上 server token。整個 handshake 就這樣。

白話就是，installer 會切模式。只要有 K3S_URL，它就知道你要裝成 agent，不是 server。agent 接著去連你指定的 K3s server。那個 token 不是裝飾品，它就是讓這台機器有資格加入叢集的憑證。

我看過很多人卡在這裡，因為他們把 token 當成一次性 bootstrap 雜訊，覺得可有可無。不要。文件也直接告訴你，server 上 token 在 /var/lib/rancher/k3s/server/node-token。你如果不把它管好，之後每次加新節點都在猜，這不是運維，這是賭博。

實操寫法：先從 server 把 token 取出來，server URL 寫準，agent 一台一台加。加不上去先看最基本的四件事：URL、token、網路可達性、hostname 是否重複。大多數「K3s 壞掉了」其實只是環境變數值打錯。

如果你想理解更完整的叢集行為，可以看 K3s architecture：K3s Architecture。quick-start 故意不把每個元件講滿，這是對的。

重複 hostname 不是小事，是你自己挖的坑

文件那句「每台機器都要有唯一 hostname」看起來像註腳，但真的能救命。如果不是唯一，你就得用 K3S_NODE_NAME 明確指定一個合法且唯一的值。

翻譯一下，node identity 是有意義的。兩台機器報同樣 hostname，等於你叫叢集把它們當成同一台，這種事怎麼可能不出事。K3s 給你 K3S_NODE_NAME 這個逃生門，特別適合 clone 出來的 VM 或環境預設名很爛的情況。

我之前在一批複製出來的 lab VM 上踩過這個洞。前面都正常，第二台一加入，叢集 UI 直接把我的命名問題攤在臉上。那時候我才承認，不能再假設作業系統會幫我把名字處理好。

實操寫法：把 hostname 設定納入 provisioning checklist。你如果是 clone image，就在 clone 後加一個唯一命名步驟。你如果用 cloud-init，就在那裡設好。真的無法保證唯一，就在 install 時直接帶 K3S_NODE_NAME，讓叢集拿到乾淨的 node identity。

• 不要假設 cloned machine 會自己長出唯一名稱。
• hostname 不可靠時，用 K3S_NODE_NAME。
• 先查 node name，再查網路或排程問題。

HA 不是預設功能，是另一個決定

quick-start 會把你導去 High Availability Embedded etcd 和 High Availability External DB 兩頁，這其實已經在告訴你：HA 不是預設安裝的一部分，它是另一套 setup。

也就是說，預設安裝是為了讓你快點拿到可用叢集。HA 問的是別的事：要幾台 server、用什麼 datastore、失敗模式怎麼看、維運成本誰扛。K3s 沒有把這些複雜度硬塞進 quick-start，我反而覺得這很老實。

實操寫法：除非你已經知道為什麼需要 HA，不然先不要把它塞進第一次安裝。你如果只是測試、驗證 manifest，或跑一個可接受短暫中斷的小型 production，預設 server 加 agent 可能就夠了。只有當 control plane 自己也不能掛，你才該先讀 HA 文件，再動手。

要看 HA 路徑，從這兩頁開始：High Availability Embedded etcd 和 High Availability External DB。quick-start 故意不展開細節，我認為這是對的。

這份 quick-start 其實是一個短版決策樹

我把這份文件拆開後，看到的不是「安裝說明」，而是一個決策樹：先裝 server，確認 kubeconfig，再加 agent，需要再談 HA，最後才是更深的設定。

白話就是，文件在教你最短路徑拿到可用叢集，不是在教你把所有可能的叢集型態一次學完。這比很多平台文件成熟太多。它承認大多數人先需要一個能用的環境，再需要理論課。

實操寫法：照順序走，不要跳去 add-on 或多 server 架構。你如果要寫內部 runbook，也保留這個順序：先安裝，再存取，再擴充。這樣每一步都有明確成功條件，支援成本會低很多。

如果你要一個心智模型，就把文件想成三段：先 bootstrap 一台 server，再加入 worker，最後再決定要不要 HA。這才是它真正的結構，就算原文比我這篇短很多，意思也一樣。

可抄的模板

# K3s quick-start runbook for Taiwan dev teams

## 1) Install the first server
curl -sfL https://get.k3s.io | sh -

## 2) Confirm the service is up
sudo systemctl status k3s

## 3) Read the kubeconfig
sudo cat /etc/rancher/k3s/k3s.yaml

## 4) Use kubectl from the installed path
sudo kubectl get nodes

## 5) Join an agent node
# On the server node, read the token:
sudo cat /var/lib/rancher/k3s/server/node-token

# On the agent node, replace values and run:
curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -

## 6) Fix hostname collisions if needed
# If a node name is duplicated, set a unique one during install:
curl -sfL https://get.k3s.io | K3S_NODE_NAME=my-unique-node-name sh -

## 7) HA only if you need it
# Read these before adding more server nodes:
# https://docs.k3s.io/datastore/ha-embedded
# https://docs.k3s.io/datastore/ha-external

## 8) What to verify
# - service restarts after reboot
# - kubeconfig points to the right server
# - node names are unique
# - agents join with the expected token
# - cluster is healthy before adding add-ons

我把這段做成跟 quick-start 同一條路徑，但把文件沒明講的操作步驟補齊了。它不是替代官方文件，而是我會丟給同事的版本，省得大家自己猜。

原始來源從這裡開始：https://docs.k3s.io/quick-start。安裝腳本入口是 https://get.k3s.io。上面的大方向來自官方文件，我補的是實作語氣、踩坑提醒和可直接複製的 runbook。