如何搭建 Kubernetes 一站式平台

1. 什麼是 Kubernetes / k8s

k8s 也就是 Kubernetes 是一個面向容器化應用的自動化管理平台, 核心職責是管理程序運行的環境, 包括 部署应用/调度资源/维护副本/处理故障/对外暴露服务等等...

對於初學者來說可以把它理解成一個專門管理容器集群的平台, 當你只有一個容器時也許還感覺不到它的必要性

但當你需要同時運行多個服務, 需要讓服務彼此通信, 需要保證應用異常後自動恢復, 甚至需要後續擴容到多台機器時 Kubernetes 的價值就會非常明顯

而本文要做的事情, 就是在一台主機上先搭建一個最小可運行的 Kubernetes 環境, 藉助這個過程去理解 Kubernetes 是怎樣從零開始被組織起來的

為了易讀性, 在這裡會將 Kubernetes 簡稱為 k8s

2. 環境說明

運行 kubeadm 集群建議 control plane 節點至少具備 2 Core CPU 和 2 GiB 運存, 推薦購買搬瓦工的 ECOMMERCE SLA 套餐

操作系統以 Debian13 為例
主機數量 1 台
使用 root 用戶
主機承擔 control plane 和 workload 調度
k8s pod網段為 10.10.0.0/16 , service網段為 192.168.0.0/16
使用 Headlamp 管理k8s pods

3. 前置準備

3.1 加載模塊並啟用轉發

cat <<'EOF' | tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

modprobe overlay
modprobe br_netfilter

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
net.ipv6.conf.all.forwarding = 1
EOF
sysctl --system

3.2 配置 hosts

tee -a /etc/hosts > /dev/null <<'EOF'
127.0.0.1 k8s-master
EOF

3.3 關閉 swap (可選)

swapoff -a
sed -ri '/\sswap\s/s/^/#/' /etc/fstab

4. 安裝 containerd

更新軟件源並安裝 containerd 與其他核心組件

apt update
apt install -y containerd apt-transport-https ca-certificates curl gpg

生成默認配置文件並修改配置文件, 這裡為了防止後續可能報錯, 修改了 bin_dir

mkdir -p /etc/containerd
containerd config default | tee /etc/containerd/config.toml > /dev/null
sed -i 's#bin_dir = "/usr/lib/cni"#bin_dir = "/opt/cni/bin"#' /etc/containerd/config.toml
sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml

重啟並設置自啟

systemctl daemon-reload
systemctl restart containerd
systemctl enable containerd
systemctl status containerd

5. 安裝 kubeadm kubelet kubectl

mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.35/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.35/deb/ /' | tee /etc/apt/sources.list.d/kubernetes.list
apt-get update
apt-get install -y kubelet kubeadm kubectl
apt-mark hold kubelet kubeadm kubectl
systemctl enable --now kubelet

檢查

kubeadm version
kubectl version --client
kubelet --version

6. 初始化單節點 k8s 集群

新建一個初始化配置

mkdir -p /main/k8s
nano /main/k8s/kubeadm-config.yaml

粘貼並自行修改配置後進行保存

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
nodeRegistration:
  name: master
  criSocket: "unix:///run/containerd/containerd.sock"
localAPIEndpoint:
  advertiseAddress: <你的公网主机IP>
  bindPort: 6443

---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
kubernetesVersion: v1.35.0
networking:
  podSubnet: 10.10.0.0/16
  serviceSubnet: 192.168.0.0/16
  dnsDomain: cluster.local

# 若开启了Swap需要解除此注释!
#---
#apiVersion: kubelet.config.k8s.io/v1beta1
#kind: KubeletConfiguration
#cgroupDriver: systemd
#failSwapOn: false
#memorySwap:
#  swapBehavior: LimitedSwap

開始初始化

kubeadm init --config /main/k8s/kubeadm-config.yaml

初始化完成後配置 kubectl

mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown "$(id -u)":"$(id -g)" $HOME/.kube/config

因為我們是單節點, 需要移除 control plane 污點, 除非多台主機節點

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

檢查

kubectl get nodes
kubectl get pods -A

這時 master 大概率是 NotReady 狀態, 目前 CNI 還沒有安裝, CoreDNS 也通常不會處於 Running 狀態

7. 安裝 Helm並設置補全

安裝 Helm

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4
chmod 700 get_helm.sh
./get_helm.sh
helm version

命令補全:

zsh

echo 'source <(kubectl completion zsh)' >> ~/.zshrc
echo 'source <(helm completion zsh)' >> ~/.zshrc
source ~/.zshrc

bash

echo 'source <(kubectl completion bash)' >> ~/.bashrc
echo 'source <(helm completion bash)' >> ~/.bashrc
source ~/.bashrc

fish

kubectl completion fish | sudo tee /etc/fish/completions/kubectl.fish > /dev/null
helm completion fish | sudo tee /etc/fish/completions/helm.fish > /dev/null

8. 安裝 CNI 插件

在資源緊湊的主機中我更推薦使用 Flannel , 這裡也會提供 Calico 與 Cilium 的安裝, 根據應用場景自行選擇其一

資源占用: Flannel < Calico < Cilium

8.1 Flannel

kubectl create namespace kube-flannel
kubectl label namespace kube-flannel --overwrite pod-security.kubernetes.io/enforce=privileged
kubectl label namespace kube-flannel --overwrite pod-security.kubernetes.io/audit=privileged
kubectl label namespace kube-flannel --overwrite pod-security.kubernetes.io/warn=privileged
helm upgrade --install flannel -n kube-flannel --create-namespace --set podCidr=10.10.0.0/16 https://github.com/flannel-io/flannel/releases/download/v0.28.1/flannel.tgz

8.2 Calico

helm repo add projectcalico https://docs.tigera.io/calico/charts
helm repo update
kubectl create namespace tigera-operator
helm upgrade --install calico projectcalico/tigera-operator --version v3.31.4 --namespace tigera-operator --set installation.calicoNetwork.ipPools[0].cidr=10.10.0.0/16 --set installation.calicoNetwork.ipPools[0].encapsulation=VXLAN

8.3 Cilium

helm repo add cilium https://helm.cilium.io/
helm repo update
helm upgrade --install cilium cilium/cilium --version 1.19.1 --namespace kube-system

檢查CNI

kubectl get nodes
kubectl get pods -A

節點狀態從 NotReady 變為 Ready , CoreDNS 進入 Running 狀態, 至此, k8s 已經初步部署完成

9. Headlamp (可選)

9.1 什麼是 `Headlamp`

Headlamp是一個面向 k8s 的圖形化管理界面, 它的目標是用更直觀的方式幫助用戶查看和管理集群資源, 例如節點/Pod/Deployment/Service/ConfigMap/Secret 等常見對象, 都可以通過 Web 頁面進行瀏覽和操作

它定義為一個易用且可擴展的 Kubernetes WebUI 並強調它既可以作為集群內 Web 應用運行, 也可以作為桌面應用使用, 和很多傳統 Dashboard 相比

Headlamp 的特點主要有三點:

界面更現代更偏向日常運維與開發使用
它支持基於 Kubernetes RBAC 的權限控制用戶能看到和操作的資源會自動受當前權限約束
它具備插件擴展能力可以根據團隊需求定製界面和功能

我個人認為可以幫助初學者擺脫只看命令行輸出的方式, 更直觀地觀察集群中資源的創建/狀態變化/日誌/配置情況, 因此很適合作為 k8s 學習和演示環境中的可視化入口.

9.2 開始安裝

先新建一個 values.yml 文件

mkdir -p /main/k8s/headlamp
nano /main/k8s/headlamp/values.yml

粘貼並自行修改配置後進行保存

replicaCount: 1

image:
  registry: ghcr.io
  repository: headlamp-k8s/headlamp
  tag: ""
  pullPolicy: IfNotPresent

nameOverride: ""
fullnameOverride: "headlamp"
namespaceOverride: ""


service:
  type: NodePort
  port: 80
  # 宿主机开放端口
  nodePort: 30080


env:
  - name: TZ
    value: "Asia/Shanghai"

config:
  pluginsDir: /headlamp/plugins

volumes:
  - name: plugins-volume
    hostPath:
      path: /main/k8s/headlamp/plugins
      type: DirectoryOrCreate

volumeMounts:
  - name: plugins-volume
    mountPath: /headlamp/plugins


resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

用 Helm 安裝

helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm repo update
helm upgrade --install headlamp headlamp/headlamp -n headlamp --create-namespace -f /main/k8s/headlamp/values.yml

通過開放的端口訪問到 Headlamp, 初次加載需要等待一會, 之後需要輸入 token, 使用命令生成

kubectl create token headlamp --namespace headlamp --duration 168h

若不通則進行檢查

kubectl get nodes
kubectl get pods -A

9.3 查看資源使用概覽

Headlamp中各種資源顯示, 需要依賴 metrics-server

helm repo add metrics-server https://kubernetes-sigs.github.io/metrics-server/
helm repo update
helm upgrade --install metrics-server metrics-server/metrics-server -n kube-system --set "args[0]=--kubelet-insecure-tls"

安裝好後就可以正常顯示資源占用情況

10. 常見問題排查

10.1 Flannel 啟動失敗

優先檢查這幾個點, Flannel 官方 README 明確指出它依賴 br_netfilter 另外它默認使用 portmap 作為 CNI 網絡插件的一部分並要求相關 CNI 二進制位於 /opt/cni/bin

10.2 Headlamp 頁面能打開但無法登錄

重點檢查

token 是否複製完整
ServiceAccount 是否創建在 kube-system
ClusterRoleBinding 是否綁定成功
Headlamp 是否真的暴露成 NodePort

10.3 Pod 無法聯網