K8S-Installer
Overview
自動化安裝 Kubernetes 高可用（HA）叢集的 AI Agent Skill。預設配置為 5 個節點：3 個 Master（Control Plane）+ 2 個 Worker。透過 SSH 連線到目標 Linux 節點，依序執行前置作業、安裝 containerd 與 kubeadm 套件、初始化 HA Control Plane、安裝 Calico CNI 網路外掛與 MetalLB LoadBalancer，並將 Worker 節點加入叢集。
When to Use This Skill
使用此 Skill 當使用者：
- 要求「幫我安裝 K8S」或「建立 Kubernetes 叢集」
- 提供節點 IP 位址並詢問如何部署 K8S
- 詢問「如何自動化安裝 Kubernetes」
- 需要在多台 Linux 伺服器上建立 K8S 叢集
- 有 SSH 存取權限的伺服器並想要部署容器平台
Prerequisites
執行環境（AI Agent 端）
- 可執行 Python 3.11+ 腳本
- 需要
paramiko（SSH）、click（CLI）、pyyaml（設定檔）套件
目標節點（要安裝 K8S 的伺服器）
- 5 個節點（預設配置）：
- master-1, master-2, master-3（Control Plane HA）
- worker-1, worker-2（Worker 節點）
- Oracle Linux 9+ 或其他 RHEL 相容系統
- 每節點至少 2 CPU、2GB RAM
- 節點間網路互通
- 必要 Port：
- Control Plane：6443, 2379-2380, 10250, 10259, 10257
- Worker：10250, 30000-32767
- SSH 存取權限（root 或具 sudo 權限的使用者）
- 需要 internet 連線以下載套件
- 建議：設定 Load Balancer 指向 3 個 Master 的 6443 port
Parameters
向使用者收集以下資訊（預設 5 節點 HA 架構）：
| 參數 | 類型 | 必填 | 說明 | |------|------|------|------| | master_nodes | list | ✓ | Master 節點列表（預設 3 個），每個包含 host、user、password | | worker_nodes | list | ✓ | Worker 節點列表（預設 2 個），每個包含 host、user、password | | load_balancer_ip | string | | Load Balancer IP（HA 架構建議設定） | | pod_network_cidr | string | | Pod 網路 CIDR，預設 192.168.0.0/16（Calico 預設） | | metallb_ip_range | string | | MetalLB IP 位址範圍，例如 192.168.1.200-192.168.1.250 |
預設節點配置
| 節點 | 角色 | 說明 | |------|------|------| | node-1 | master-1 | 第一個 Control Plane（初始化節點） | | node-2 | master-2 | 第二個 Control Plane | | node-3 | master-3 | 第三個 Control Plane | | node-4 | worker-1 | 第一個 Worker 節點 | | node-5 | worker-2 | 第二個 Worker 節點 |
參數收集對話範例
我需要以下資訊來安裝 K8S HA 叢集（3 Master + 2 Worker）：
=== Master 節點（Control Plane HA）===
請提供 3 個 Master 節點的連線資訊：
--- master-1（初始化節點）---
IP 位址:
SSH 使用者: root
SSH 密碼:
--- master-2 ---
IP 位址:
SSH 使用者: root
SSH 密碼:
--- master-3 ---
IP 位址:
SSH 使用者: root
SSH 密碼:
=== Worker 節點 ===
請提供 2 個 Worker 節點的連線資訊：
--- worker-1 ---
IP 位址:
SSH 使用者: root
SSH 密碼:
--- worker-2 ---
IP 位址:
SSH 使用者: root
SSH 密碼:
=== Load Balancer（選填但建議）===
Load Balancer IP（指向 3 個 Master 的 6443 port）:
=== 網路設定（選填）===
Pod 網路 CIDR？（預設 192.168.0.0/16，Calico 預設）
=== MetalLB 設定（選填）===
MetalLB IP 位址範圍？（例如 192.168.1.200-192.168.1.250）
Execution Workflow
Step 1: 驗證連線
在開始安裝前，先測試所有節點的 SSH 連線：
# 對每個節點執行連線測試
ssh {user}@{host} -p {port} "echo 'Connection OK'"
如果連線失敗，報告錯誤並請使用者確認：
- SSH 服務是否啟動
- 防火牆是否允許 22 port
- 使用者名稱密碼是否正確
Step 2: 前置作業（所有節點）
在每個節點執行：
2.1 停用 Swap
swapoff -a
sed -i '/swap/d' /etc/fstab
2.2 載入核心模組
cat <<EOF | tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF
modprobe overlay
modprobe br_netfilter
2.3 設定 Sysctl 參數
cat <<EOF | tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF
sysctl --system
Step 3: 安裝套件（所有節點）
3.1 安裝 Containerd
dnf install -y containerd
mkdir -p /etc/containerd
containerd config default | tee /etc/containerd/config.toml
sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
systemctl enable --now containerd
3.2 安裝 Kubernetes 套件
cat <<EOF | tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.29/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.29/rpm/repodata/repomd.xml.key
EOF
dnf install -y kubelet kubeadm kubectl
systemctl enable --now kubelet
Step 4: 初始化第一個 Master（master-1）
僅在 master-1 執行：
4.1 執行 kubeadm init（HA 模式）
# 如果有 Load Balancer
kubeadm init \
--control-plane-endpoint "{load_balancer_ip}:6443" \
--upload-certs \
--pod-network-cidr={pod_network_cidr}
# 如果沒有 Load Balancer，使用 master-1 IP
kubeadm init \
--control-plane-endpoint "{master1_ip}:6443" \
--upload-certs \
--pod-network-cidr={pod_network_cidr}
4.2 設定 kubectl
mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config
4.3 安裝 Calico CNI
# 安裝 Calico operator
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/tigera-operator.yaml
# 安裝 Calico 自訂資源
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/custom-resources.yaml
# 等待 Calico 就緒
kubectl wait --for=condition=Ready pods -l k8s-app=calico-node -n calico-system --timeout=300s
4.4 記錄 Join 命令
kubeadm init 完成後會輸出兩個 join 命令：
- Control Plane join 命令（含
--control-plane --certificate-key） - Worker join 命令
Step 5: 加入其他 Master（master-2, master-3）
在 master-2 和 master-3 執行 Control Plane join 命令：
kubeadm join {endpoint}:6443 --token {token} \
--discovery-token-ca-cert-hash sha256:{hash} \
--control-plane --certificate-key {cert_key}
完成後在每個 Master 設定 kubectl：
mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config
Step 6: Worker 加入叢集（worker-1, worker-2）
在 worker-1 和 worker-2 執行 Worker join 命令：
kubeadm join {endpoint}:6443 --token {token} \
--discovery-token-ca-cert-hash sha256:{hash}
Step 7: 安裝 MetalLB LoadBalancer
在任一 Master 執行：
7.1 啟用 strictARP
# MetalLB 需要啟用 strictARP
kubectl get configmap kube-proxy -n kube-system -o yaml | \
sed -e 's/strictARP: false/strictARP: true/' | \
kubectl apply -f - -n kube-system
7.2 安裝 MetalLB
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.14.3/config/manifests/metallb-native.yaml
# 等待 MetalLB 就緒
kubectl wait --for=condition=Ready pods -l app=metallb -n metallb-system --timeout=120s
7.3 設定 IP 位址池
cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: default-pool
namespace: metallb-system
spec:
addresses:
- {metallb_ip_range} # 例如: 192.168.1.200-192.168.1.250
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: default
namespace: metallb-system
spec:
ipAddressPools:
- default-pool
EOF
Step 8: 驗證安裝
在任一 Master 執行：
kubectl get nodes
預期輸出（5 節點 HA 叢集）：
NAME STATUS ROLES AGE VERSION
master-1 Ready control-plane 10m v1.29.0
master-2 Ready control-plane 8m v1.29.0
master-3 Ready control-plane 6m v1.29.0
worker-1 Ready <none> 4m v1.29.0
worker-2 Ready <none> 3m v1.29.0
檢查 etcd 叢集狀態：
kubectl get pods -n kube-system -l component=etcd
預期有 3 個 etcd Pod 運行中。
檢查 Calico CNI 狀態：
kubectl get pods -n calico-system
預期所有 calico-node Pod 都為 Running。
檢查 MetalLB 狀態：
kubectl get pods -n metallb-system
kubectl get ipaddresspool -n metallb-system
Output
安裝完成後，回報以下資訊給使用者：
✅ K8S HA 叢集安裝完成！
叢集資訊：
- 架構：High Availability（HA）
- Master 節點：3 個（master-1, master-2, master-3）
- Worker 節點：2 個（worker-1, worker-2）
- Control Plane Endpoint: {endpoint}
- Pod 網路: {pod_network_cidr}
- CNI: Calico
- LoadBalancer: MetalLB（IP 範圍: {metallb_ip_range}）
- Kubernetes 版本: v1.29.0
📋 Join 命令（供未來新增節點使用）：
# 新增 Master（Control Plane）
kubeadm join {endpoint}:6443 --token {token} \
--discovery-token-ca-cert-hash sha256:{hash} \
--control-plane --certificate-key {cert_key}
# 新增 Worker
kubeadm join {endpoint}:6443 --token {token} \
--discovery-token-ca-cert-hash sha256:{hash}
下一步：
1. SSH 登入任一 Master: ssh {user}@{master_ip}
2. 檢查節點狀態: kubectl get nodes
3. 檢查 Calico 狀態: kubectl get pods -n calico-system
4. 檢查 MetalLB 狀態: kubectl get pods -n metallb-system
5. 部署第一個應用: kubectl create deployment nginx --image=nginx
6. 建立 LoadBalancer Service: kubectl expose deployment nginx --type=LoadBalancer --port=80
Error Handling
SSH 連線失敗
❌ 無法連線到 {host}
可能原因：
- SSH 服務未啟動：systemctl status sshd
- 防火牆阻擋：firewall-cmd --add-port=22/tcp --permanent
- 密碼錯誤
請確認後重試。
kubeadm init 失敗
❌ Control Plane 初始化失敗
可能原因：
- CPU 或記憶體不足（需至少 2 CPU、2GB RAM）
- swap 未停用：free -h 確認 swap 為 0
- 已有 K8S 殘留：kubeadm reset -f
錯誤訊息：{error_message}
Worker 加入失敗
❌ Worker {host} 無法加入叢集
可能原因：
- 無法連線 Control Plane 6443 port
- Token 已過期（24 小時有效）
- 網路不通
請確認後重試，或重新產生 token：kubeadm token create --print-join-command
Scripts Location
此 Skill 的執行腳本位於 scripts/ 目錄：
install.py- 主要安裝腳本ssh_client.py- SSH 連線封裝config.py- 設定檔處理
References
參考文件位於 references/ 目錄：
kubeadm_setup.md- kubeadm 官方安裝指南troubleshooting.md- 常見問題排除oracle_linux_notes.md- Oracle Linux 特定注意事項
Key Principles
收集完整資訊再執行：
- 在開始安裝前，確保已收集所有必要的節點連線資訊
- 先驗證 SSH 連線，避免安裝到一半失敗
逐步回報進度：
- 每完成一個步驟，告知使用者進度
- 如果某步驟耗時較長，提供預估時間
清楚的錯誤訊息：
- 發生錯誤時，提供具體的原因與解決建議
- 不要只說「安裝失敗」，要說明是哪個步驟、什麼錯誤
安全考量：
- 密碼等敏感資訊不要顯示或記錄
- 完成後提醒使用者變更預設密碼