在 Ubuntu 上部署 Kubernetes 集群实战指南

k8s-master 节点修改后：

network:
  ethernets:
    enp0s3:
      dhcp4: false
      addresses:
        - 192.168.31.10/24
      routes:
        - to: default
          via: 192.168.31.1
      nameservers:
        addresses:
          - 192.168.31.1
          - 8.8.8.8
      dhcp6: false
      match:
        macaddress: 08:00:27:2d:a1:c0
      set-name: enp0s3
      version: 2

k8s-node1 节点修改后：

network:
  ethernets:
    enp0s3:
      dhcp4: false
      addresses:
        - 192.168.31.11/24
      routes:
        - to: default
          via: 192.168.31.1
      nameservers:
        addresses:
          - 192.168.31.1
          - 8.8.8.8
      dhcp6: false
      match:
        macaddress: 08:00:27:2d:a1:c0
      set-name: enp0s3
      version: 2

设置主机名

# Master 节点
sudo hostnamectl set-hostname k8s-master

# Node1 节点
sudo hostnamectl set-hostname k8s-node1

配置 /etc/hosts

确保所有节点能解析彼此的主机名。

sudo tee -a /etc/hosts <<EOF
192.168.31.10 k8s-master
192.168.31.11 k8s-node1
EOF

禁用 Swap

Kubernetes 默认要求关闭 Swap，否则 kubeadm 初始化会报错。

sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

启用内核模块 & 调整参数

需要加载 overlay 和 br_netfilter 模块，并开启 IP 转发。

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

sudo modprobe overlay
sudo modprobe br_netfilter

cat <<EOF | sudo 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

sudo sysctl --system

开放端口

不同角色节点开放的端口略有差异，请根据实际规划操作。

Master 节点

# 启用 UFW（如果未启用）
sudo ufw enable

# 默认允许出站，限制入站
sudo ufw default allow outgoing
sudo ufw default deny incoming

# 开放 K8s 相关端口
sudo ufw allow 6443/tcp
sudo ufw allow 2379:2380/tcp
sudo ufw allow 10250/tcp
sudo ufw allow 10259/tcp
sudo ufw allow 10257/tcp
sudo ufw allow 8472/udp
sudo ufw allow 30000:32767/tcp

# 重新加载并查看状态
sudo ufw reload
sudo ufw status verbose

Node 节点

# 启用 UFW
sudo ufw enable

# 默认允许出站，限制入站
sudo ufw default allow outgoing
sudo ufw default deny incoming

# 开放必要端口
sudo ufw allow 22/tcp
sudo ufw allow 10250/tcp
sudo ufw allow 8472/udp
sudo ufw allow 30000:32767/tcp

# 重新加载并查看状态
sudo ufw reload
sudo ufw status verbose

端口详情表

安装组件（所有节点）

安装 containerd

Kubernetes 推荐使用 containerd 作为容器运行时。

# 安装依赖
sudo apt update && sudo apt install -y ca-certificates curl gnupg lsb-release

# 清理旧的 Docker 源配置
sudo rm -f /etc/apt/sources.list.d/docker.list
sudo rm -f /etc/apt/sources.list.d/download_docker_com_linux_ubuntu.list

################# 添加 Docker GPG 密钥 #################
# 第一种方式：国内建议（containerd 来自阿里云镜像加速）
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 第二种方式：需要支持访问外网（containerd 来自 Docker 官方仓库）
# sudo install -m 0755 -d /etc/apt/keyrings
# curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
# sudo chmod a+r /etc/apt/keyrings/docker.gpg

##########################################################################
# 添加仓库
sudo echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 下载 containerd
sudo apt update
sudo apt install -y containerd.io

# 配置 containerd
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# 修改 config.toml：将 SystemdCgroup = false 改为 true
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml

# 重启 containerd
sudo systemctl restart containerd
sudo systemctl enable containerd

安装 kubeadm、kubelet、kubectl

方案一：支持访问外网

# 添加 Kubernetes APT 仓库（使用 Google Cloud 官方源）
sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl
curl -fsSLo /etc/apt/keyrings/kubernetes-archive-keyring.gpg https://packages.cloud.google.com/apt/doc/apt-key.gpg
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt update
sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

如果这一步报错：curl: (28) Failed to connect to packages.cloud.google.com port 443 after 148795 ms: Could not connect to server.，表示无法访问外网，请直接使用方案二。

方案二：国内建议

sudo rm -f /etc/apt/sources.list.d/kubernetes.list
sudo rm -f /etc/apt/keyrings/kubernetes-archive-keyring.gpg
sudo mkdir -p /etc/apt/keyrings
sudo rm -f /etc/apt/keyrings/kubernetes-aliyun.gpg &&\
curl -fsSL https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.31/deb/Release.key |\
sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-aliyun.gpg
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-aliyun.gpg] https://mirrors.aliyun.com/kubernetes-new/core/stable/v1.31/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt update
sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

修改 kubectl 镜像源（可选，国内建议）

国内用户常遇到拉取镜像超时的问题，可以通过配置 containerd 的镜像代理来解决。

sudo vim /etc/containerd/config.toml

#################### 修改 1：找到以下配置 ######################
[plugins.'io.containerd.cri.v1.images'.pinned_images]
#################### 将 sandbox 的 value 修改为以下值 ###########################
sandbox = 'registry.aliyuncs.com/google_containers/pause:3.10.1'

#################### 修改 2：找到以下配置 ######################
[plugins.'io.containerd.cri.v1.images'.registry]
#################### 将 config_path 的 value 修改为以下值 ###########################
config_path ='/etc/containerd/certs.d'

#################### 修改 3 #############################
sudo mkdir -p /etc/containerd/certs.d/docker.io
sudo tee /etc/containerd/certs.d/docker.io/hosts.toml <<EOF
server = "https://registry-1.docker.io"
[host."https://docker.m.daocloud.io"]
capabilities = ["pull", "resolve"]
EOF

###################### 重启 container ######################
sudo systemctl restart containerd

初始化 Master 节点

第一步：初始化 kubeadm

注意：--pod-network-cidr 需与你后续安装的 CNI 插件设定一致。这里以 Flannel 为例（使用 10.244.0.0/16）。生产环境建议使用 Calico。

方式一：支持访问外网

sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --apiserver-advertise-address=192.168.31.10 

方式二：国内建议

sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --apiserver-advertise-address=192.168.31.10 --image-repository=registry.aliyuncs.com/google_containers 

常见报错解决

报错：[ERROR FileExisting-conntrack]: conntrack not found in system path

原因：缺少 conntrack 工具。 解决：安装 conntrack 包：

sudo apt update && sudo apt install -y conntrack

第二步：配置 kubectl

初始化成功后，按提示配置本地 kubectl 权限：

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

安装 CNI 网络插件（Master 节点）

以 Flannel 为例，这是最简单的网络插件。

kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

PS：碰上网络问题，可以先在浏览器下载 -> 上传到服务器，然后执行 kubectl apply -f kube-flannel.yml

检查网络插件安装情况

kubectl get pods -n kube-flannel

# 输出类似
# NAME READY STATUS RESTARTS AGE
# kube-flannel-ds-68fsw 1/1 Running 0 23m

kubectl get pods -n kube-system

# 输出类似
# NAME READY STATUS RESTARTS AGE
# coredns-855c4dd65d-g2pgd 1/1 Running 0 26m
# ...

# 如果没成功，可以通过查看安装进展定位问题
kubectl describe pod coredns-855c4dd65d-g2pgd -n kube-system

将 Node 加入集群

Master 节点执行

获取 join 命令：

kubeadm token create --print-join-command

输出类似：

kubeadm join 192.168.31.10:6443 --token i50jq7.xxxx --discovery-token-ca-cert-hash sha256:xxxxxxxxxxxxxxxxxxxxx

Node 节点执行

复制上述命令并在 Node 节点执行：

sudo kubeadm join 192.168.31.10:6443 --token i50jq7.xxxx --discovery-token-ca-cert-hash sha256:xxxxxxxxxxxxxxxxxxxxx

常见报错解决

报错：[ERROR FileExisting-conntrack]: conntrack not found in system path

问题：缺少 conntrack 工具 解决：安装 conntrack：

sudo apt update && sudo apt install -y conntrack

验证阶段（master 节点上验证）

kubectl get nodes

# OUTPUT
# NAME STATUS ROLES AGE VERSION
# k8s-master Ready control-plane 30m v1.31.14
# k8s-node1 Ready <none> 96s v1.31.14

部署一个测试应用

创建一个简单的 Nginx Deployment 和 Service 来验证调度和网络功能：

# 创建 Deployment
kubectl create deployment nginx --image=nginx

# OUTPUT
# deployment.apps/nginx created

# 查看 Pod 是否被调度到工作节点
kubectl get pods -o wide

# OUTPUT
# NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
# nginx-676b6c5bbc-wdz4w 1/1 Running 0 23s 10.244.1.2 k8s-node1 <none><none>

# 暴露服务（可选）
kubectl expose deployment nginx --port=80 --type=NodePort

# OUTPUT
# service/nginx exposed

# 查看服务
kubectl get svc nginx

# OUTPUT
# NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
# nginx NodePort 10.97.208.222 <none>80:31301/TCP 5s

# 访问服务
curl -I 192.168.31.11:31301

# OUTPUT
# HTTP/1.1 200 OK
# Server: nginx/1.29.5
# Date: Thu, 12 Feb 2026 02:31:16 GMT
# Content-Type: text/html
# Content-Length: 615
# Last-Modified: Wed, 04 Feb 2026 15:12:20 GMT
# Connection: keep-alive
# ETag: "698361d4-267"
# Accept-Ranges: bytes

至此，集群搭建完成。