用 k3sup 快速建立 K3s 叢集：從安裝到多節點一鍵搞定

前言

在日常維運與測試的過程中，我常常需要在乾淨的環境裡反覆建立和拆除 Kubernetes 叢集。不管是在自己的 HomeLab 還是雲端虛擬機上，這種需求幾乎是家常便飯。雖然透過 Terraform 可以迅速處理 VM 的生命週期管理，但叢集本身的安裝步驟仍然讓人覺得瑣碎——SSH 進主機、跑安裝指令、複製 token、再 SSH 到另一台機器重複同樣的動作。

直到我接觸到 k3sup（唸作 "ketchup"），才發現原來建立 K3s 叢集可以這麼省事。這篇文章就來分享一下我使用 k3sup 的心得與完整操作流程。

k3sup 透過 SSH 從本機操控遠端 VM 安裝 K3s（圖片來源：k3sup GitHub）

k3sup 是什麼？

k3sup 是由 Alex Ellis 所開發的一套輕量級命令列工具，專門用來透過 SSH 快速部署 K3s 叢集。它的核心概念很簡單：你只需要在本機執行一道指令，k3sup 就會幫你完成以下所有事情：

換句話說，你不用再手動 SSH 進每一台機器，k3sup 全部幫你搞定。不管是本機、雲端 VM 還是樹莓派，只要能通 SSH 就能用。

k3sup 也支援在樹莓派上建立叢集（圖片來源：k3sup GitHub）

安裝 k3sup

k3sup 提供多平台支援，安裝方式如下：

Linux

curl -sLS https://get.k3sup.dev | sh
sudo install k3sup /usr/local/bin/

macOS

brew install k3sup

核心指令介紹

k3sup 的指令不多，但每個都很實用：

實戰：建立 K3s 叢集

Step 1：安裝 Server 節點

使用 install 指令即可在遠端主機上部署 K3s Server。--ip 指定目標主機位址，--user 為 SSH 使用者，--k3s-channel 指定版本，--local-path 則是 kubeconfig 在本機的儲存路徑。

k3sup 預設使用 ~/.ssh/id_rsa 做身份驗證，也可以透過 --ssh-key 指定其他金鑰。

export MASTER_IP=192.168.1.11
k3sup install --ip $MASTER_IP \
  --user ******** \
  --k3s-channel v1.24 \
  --local-path /tmp/config

安裝完成後，會在本機產生 kubeconfig 檔案，可以直接使用：

export KUBECONFIG=/tmp/config
kubectl get node -o wide

輸出範例：

NAME     STATUS   ROLES                  AGE   VERSION         INTERNAL-IP    OS-IMAGE             CONTAINER-RUNTIME
master   Ready    control-plane,master   1m    v1.24.17+k3s1  10.0.2.4       Ubuntu 20.04.6 LTS   containerd://1.7.3-k3s1

如果只需要單節點叢集，到這裡就完成了。

Step 2：加入 Agent 節點

若需要多節點叢集，使用 join 指令將 Agent 加入。需要透過 --server-ip 指定 Server 的位址，建議使用與 Server 相同的版本。

export AGENT_IP=192.168.1.12
k3sup join --ip $AGENT_IP \
  --user ******** \
  --server-ip $MASTER_IP \
  --k3s-channel v1.24

完成後查看節點：

kubectl get no
NAME     STATUS   ROLES                  AGE     VERSION
node-1   Ready    <none>                 43s     v1.24.17+k3s1
master   Ready    control-plane,master   2m58s   v1.24.17+k3s1

進階：一鍵建立叢集的腳本

如果你跟我一樣經常需要建立多節點叢集，可以把整個流程寫成腳本。以下腳本會從環境變數 HOSTS 讀取節點 IP，第一個作為 Server，其餘作為 Agent：

export HOSTS="192.168.1.11 192.168.1.12"

建立叢集腳本

#!/bin/bash
set -euo pipefail

IP_ADDRESSES=($HOSTS)
K3S_VERSION="v1.24"

if [ ${#IP_ADDRESSES[@]} -eq 0 ]; then
    echo "未偵測到 IP 位址，請確認 HOSTS 環境變數已正確設定。"
    exit 1
fi

# 安裝 Server 節點
MASTER_IP=${IP_ADDRESSES[0]}
echo "正在安裝 Server 節點：$MASTER_IP"
k3sup install --ip $MASTER_IP \
    --user ******** \
    --k3s-channel $K3S_VERSION \
    --k3s-extra-args '--write-kubeconfig-mode 644 --write-kubeconfig ~/.kube/config --disable traefik --disable metrics-server --disable local-storage --disable servicelb' \
    --local-path /tmp/config

# 安裝 Agent 節點
for i in "${!IP_ADDRESSES[@]}"; do
    if [ $i -ne 0 ]; then
        AGENT_IP=${IP_ADDRESSES[$i]}
        echo "正在安裝 Agent 節點：$AGENT_IP"
        k3sup join --ip $AGENT_IP \
            --server-ip $MASTER_IP \
            --user ******** \
            --k3s-channel $K3S_VERSION
    fi
done

echo "K3s 叢集安裝完成！"

卸載叢集腳本

#!/bin/bash
set -euo pipefail

IP_ADDRESSES=($HOSTS)

if [ ${#IP_ADDRESSES[@]} -eq 0 ]; then
    echo "未偵測到 IP 位址，請確認 HOSTS 環境變數已正確設定。"
    exit 1
fi

MASTER_IP=${IP_ADDRESSES[0]}
echo "正在清理 Server 節點：$MASTER_IP"
ssh -i ~/.ssh/id_rsa $MASTER_IP k3s-uninstall.sh

for i in "${!IP_ADDRESSES[@]}"; do
    if [ $i -ne 0 ]; then
        AGENT_IP=${IP_ADDRESSES[$i]}
        echo "正在清理 Agent 節點：$AGENT_IP"
        ssh -i ~/.ssh/id_rsa $AGENT_IP k3s-agent-uninstall.sh
    fi
done

echo "K3s 叢集清理完成！"

我自己實測建立雙節點叢集大約只需要 30 多秒，真的是非常快速。

小結

k3sup 解決了手動部署 K3s 叢集時最煩人的部分——反覆 SSH、複製 token、跑安裝指令。對於經常需要建立測試環境的人來說，這個工具可以大幅節省時間。搭配 Terraform 管理 VM 生命週期，基本上從建立虛擬機到叢集就緒，整個流程都可以自動化完成。

有興趣的朋友可以到 k3sup 的 GitHub 了解更多細節。

參考資料

• k3sup GitHub Repository
• K3s 官方網站
• K3s Architecture