Kubernetes 系列【3】使用 kubeadm 创建 K8s 集群

文章目录

[1. 前言](#1. 前言)
[2. 基于 Kubeadm 部署](#2. 基于 Kubeadm 部署)
- [2.1 环境准备](#2.1 环境准备)
- - [2.1.1 基础要求](#2.1.1 基础要求)
  - [2.1.2 配置主机名](#2.1.2 配置主机名)
  - [2.1.3 关闭 swap](#2.1.3 关闭 swap)
  - [2.1.4 加载内核模块](#2.1.4 加载内核模块)
  - [2.1.5 配置内核参数](#2.1.5 配置内核参数)
  - [2.1.6 安装基础工具](#2.1.6 安装基础工具)
  - [2.1.7 关闭防火墙或开放端口](#2.1.7 关闭防火墙或开放端口)
- [2.2 安装 Docker](#2.2 安装 Docker)
- - [2.2.1 添加 Docker 官方源](#2.2.1 添加 Docker 官方源)
  - [2.2.2 安装 Docker CE](#2.2.2 安装 Docker CE)
  - [2.2.3 配置 Docker](#2.2.3 配置 Docker)
  - [2.2.4 安装 cri-dockerd](#2.2.4 安装 cri-dockerd)
- [2.3 安装 kubeadm/kubelet/kubectl](#2.3 安装 kubeadm/kubelet/kubectl)
- - [2.3.1 添加 Kubernetes apt 源](#2.3.1 添加 Kubernetes apt 源)
  - [2.3.2 安装 Kubernetes 组件](#2.3.2 安装 Kubernetes 组件)
- [2.4 初始化 Master](#2.4 初始化 Master)
- - [2.4.1 预拉取 Kubernetes 镜像](#2.4.1 预拉取 Kubernetes 镜像)
  - [2.4.2 初始化集群](#2.4.2 初始化集群)
  - [2.4.3 配置 kubectl](#2.4.3 配置 kubectl)
  - [2.4.4 安装 Calico 网络插件](#2.4.4 安装 Calico 网络插件)
- [2.5 Worker 加入集群](#2.5 Worker 加入集群)
- [2.6 验证集群](#2.6 验证集群)
- - [2.6.1 查看节点状态](#2.6.1 查看节点状态)
  - [2.6.2 查看系统组件](#2.6.2 查看系统组件)
  - [2.6.3 创建测试应用](#2.6.3 创建测试应用)
  - [2.6.4 常用排查命令](#2.6.4 常用排查命令)
[3. 安装 Kuboard （可选）](#3. 安装 Kuboard （可选）)
- [3.1 部署说明](#3.1 部署说明)
- [3.2 单机 Docker 部署](#3.2 单机 Docker 部署)
- - [3.2.1 启动 Kuboard 容器](#3.2.1 启动 Kuboard 容器)
  - [3.2.2 查看 Kuboard 状态](#3.2.2 查看 Kuboard 状态)
  - [3.2.3 访问 Kuboard](#3.2.3 访问 Kuboard)
- [3.3 添加集群](#3.3 添加集群)
- - [3.3.1 使用 Kuboard-Agent 添加集群](#3.3.1 使用 Kuboard-Agent 添加集群)
[4. 总结](#4. 总结)

部署目标：在 3 台 Ubuntu Server 24.04 服务器上，使用 kubeadm 部署 1 个 Master 节点和 2 个 Worker 节点的 Kubernetes 集群，并使用 Docker 单机模式部署 Kuboard 管理界面。

1. 前言

Kubernetes 集群常见部署方式主要有两类：kubeadm 部署和二进制部署。

kubeadm 是 Kubernetes 官方提供的集群初始化工具，可以帮助我们完成控制平面初始化、证书生成、核心组件配置、Worker 节点加入集群等操作。它的优点是部署流程标准、维护成本低、社区资料丰富，适合测试环境、学习环境以及中小规模生产环境。

二进制部署是指手动下载并配置 kube-apiserver、kube-controller-manager、kube-scheduler、kubelet、kube-proxy、etcd 等组件。二进制部署的优点是可控性强，适合对证书、参数、高可用架构有深度定制需求的场景；缺点是步骤复杂、排障成本高，对 Kubernetes 组件原理要求更高。

核心特性对比表：

对比维度	kubeadm部署	二进制部署
部署难度	低，自动化流程	极高，全手动配置
自定义能力	有限，仅少量参数可修改	完全自由，所有组件可深度调优
组件运行形态	容器（静态Pod）	宿主机系统进程
证书管理	自动生成，默认1年有效期	自主生成、自定义有效期、加密算法
集群升级	官方工具一键升级	手动逐个更新组件
学习成本	低，屏蔽底层细节	高，吃透全部控制平面组件原理
典型使用场景	测试环境、中小规模标准生产集群	大型集群、金融合规、边缘定制、底层原理学习

本文选择使用 kubeadm 部署 Kubernetes 集群，整体架构如下：

节点	示例主机名	示例内网 IP	角色
Master	k8s-master	172.17.172.87	控制平面节点
Worker 1	k8s-worker1	172.17.172.89	工作节点
Worker 2	k8s-worker2	172.17.172.90	工作节点

本文使用组件版本：

组件	版本 / 说明
操作系统	Ubuntu Server 24.04
Kubernetes	v1.32.x
容器运行时	Docker CE + cri-dockerd
网络插件	Calico
Pod 网段	100.64.0.0/10
Service 网段	10.96.0.0/12
管理面板	Kuboard v3

注意：文中的 IP 只是示例，请根据自己的服务器实际内网 IP 修改。

2. 基于 Kubeadm 部署

kubeadm 是 CNCF 官方原生集群引导工具，用来快速搭建符合标准的纯净版 Kubernetes 集群，替代二进制手动部署，只负责集群初始化、节点接入、版本升级、证书管理，不管理操作系统、不安装网络插件、监控等附加组件。

2.1 环境准备

以下操作除特别说明外，三台服务器都需要执行。

2.1.1 基础要求

项目	要求
CPU	至少 2 核
内存	至少 2 GB，建议 4 GB 以上
磁盘	至少 20 GB
网络	三台服务器内网互通
用户	root 用户，或具备 sudo 权限的用户

如果使用云服务器，需要确保三台机器在同一个内网环境，或者内网 IP 之间可以互相访问。

2.1.2 配置主机名

Master 节点执行：

bash 复制代码

hostnamectl set-hostname k8s-master

Worker 1 节点执行：

bash 复制代码

hostnamectl set-hostname k8s-worker1

Worker 2 节点执行：

bash 复制代码

hostnamectl set-hostname k8s-worker2

三台服务器都配置 hosts：

bash 复制代码

cat >> /etc/hosts << 'EOF'
172.17.172.87 k8s-master
172.17.172.89 k8s-worker1
172.17.172.90 k8s-worker2
EOF

验证：

bash 复制代码

ping -c 2 k8s-master
ping -c 2 k8s-worker1
ping -c 2 k8s-worker2

2.1.3 关闭 swap

Kubernetes 要求关闭 swap。

bash 复制代码

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

验证：

bash 复制代码

free -h

如果 Swap 一行显示为 0B，说明 swap 已关闭。

2.1.4 加载内核模块

bash 复制代码

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

modprobe overlay
modprobe br_netfilter

验证：

bash 复制代码

lsmod | grep overlay
lsmod | grep br_netfilter

2.1.5 配置内核参数

bash 复制代码

cat > /etc/sysctl.d/k8s.conf << 'EOF'
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sysctl --system

验证：

bash 复制代码

sysctl net.ipv4.ip_forward
sysctl net.bridge.bridge-nf-call-iptables

预期输出：

text 复制代码

net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-iptables = 1

2.1.6 安装基础工具

bash 复制代码

apt-get update
apt-get install -y apt-transport-https ca-certificates curl gpg lsb-release wget vim

2.1.7 关闭防火墙或开放端口

如果是测试环境，可以直接关闭 Ubuntu 默认防火墙：

bash 复制代码

systemctl stop ufw
systemctl disable ufw

如果是生产环境，建议按端口精确放行。

Master 节点需要放行：

端口	协议	用途
6443	TCP	Kubernetes API Server
2379-2380	TCP	etcd
10250	TCP	kubelet
10257	TCP	kube-controller-manager
10259	TCP	kube-scheduler
30000-32767	TCP	NodePort 服务

Worker 节点需要放行：

端口	协议	用途
10250	TCP	kubelet
30000-32767	TCP	NodePort 服务

Calico 网络插件可能需要：

端口	协议	用途
179	TCP	Calico BGP 模式
4789	UDP	Calico VXLAN 模式

2.2 安装 Docker

以下操作三台服务器都执行。

2.2.1 添加 Docker 官方源

bash 复制代码

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

cat > /etc/apt/sources.list.d/docker.list << EOF
deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu noble stable
EOF

apt-get update

如果服务器访问 Docker 官方源较慢，可以替换为可用的国内 Docker apt 镜像源。

2.2.2 安装 Docker CE

bash 复制代码

apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2.2.3 配置 Docker

Kubernetes 推荐 Docker 使用 systemd 作为 cgroup driver。

bash 复制代码

mkdir -p /etc/docker
cat > /etc/docker/daemon.json << 'EOF'
{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "registry-mirrors": ["https://docker.m.daocloud.io"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m"
  }
}
EOF

systemctl daemon-reload
systemctl enable docker --now
systemctl restart docker

验证 Docker：

bash 复制代码

docker version
docker info | grep -i 'Cgroup Driver'

预期输出包含：

text 复制代码

Cgroup Driver: systemd

2.2.4 安装 cri-dockerd

Kubernetes 从 1.24 开始移除了内置的 dockershim。如果继续使用 Docker 作为容器运行时，需要额外安装 cri-dockerd。

查看服务器架构：

bash 复制代码

uname -m

常见架构对应关系：

uname -m 输出	cri-dockerd 包架构
x86_64	amd64
aarch64	arm64

以 cri-dockerd 0.3.16 为例，x86_64 服务器执行：

bash 复制代码

cd /tmp
wget https://github.com/Mirantis/cri-dockerd/releases/download/v0.3.16/cri-dockerd-0.3.16.amd64.tgz
tar -xzf cri-dockerd-0.3.16.amd64.tgz
install -m 0755 cri-dockerd/cri-dockerd /usr/local/bin/cri-dockerd

ARM64 服务器执行：

bash 复制代码

cd /tmp
wget https://github.com/Mirantis/cri-dockerd/releases/download/v0.3.16/cri-dockerd-0.3.16.arm64.tgz
tar -xzf cri-dockerd-0.3.16.arm64.tgz
install -m 0755 cri-dockerd/cri-dockerd /usr/local/bin/cri-dockerd

创建 systemd 服务：

bash 复制代码

cat > /etc/systemd/system/cri-docker.service << 'EOF'
[Unit]
Description=CRI Interface for Docker Application Container Engine
Documentation=https://docs.mirantis.com
After=network-online.target docker.service
Wants=network-online.target
Requires=cri-docker.socket

[Service]
Type=notify
ExecStart=/usr/local/bin/cri-dockerd --container-runtime-endpoint fd:// --pod-infra-container-image=registry.aliyuncs.com/google_containers/pause:3.10
ExecReload=/bin/kill -s HUP $MAINPID
TimeoutSec=0
RestartSec=2
Restart=always
LimitNOFILE=infinity
LimitNPROC=infinity
LimitCORE=infinity
TasksMax=infinity
Delegate=yes
KillMode=process

[Install]
WantedBy=multi-user.target
EOF

cat > /etc/systemd/system/cri-docker.socket << 'EOF'
[Unit]
Description=CRI Docker Socket for the API
PartOf=cri-docker.service

[Socket]
ListenStream=/var/run/cri-dockerd.sock
SocketMode=0660
SocketUser=root
SocketGroup=docker

[Install]
WantedBy=sockets.target
EOF

systemctl daemon-reload
systemctl enable --now cri-docker.socket
systemctl enable --now cri-docker.service

验证 cri-dockerd：

bash 复制代码

systemctl status cri-docker.service --no-pager
cri-dockerd --version

2.3 安装 kubeadm/kubelet/kubectl

以下操作三台服务器都执行。

kubeadm 仅仅是集群初始化工具，它生成静态 Pod 清单后，必须依靠本机常驻进程 kubelet 来启动控制平面容器，而 kubectl 是客户端工具，用来操作和管理集。

2.3.1 添加 Kubernetes apt 源

本文使用 Kubernetes v1.32。

bash 复制代码

mkdir -p /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.32/deb/Release.key \
  | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

cat > /etc/apt/sources.list.d/kubernetes.list << 'EOF'
deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /
EOF

apt-get update

2.3.2 安装 Kubernetes 组件

bash 复制代码

apt-get install -y kubelet kubeadm kubectl
apt-mark hold kubelet kubeadm kubectl
systemctl enable kubelet

验证版本：

bash 复制代码

kubeadm version
kubelet --version
kubectl version --client

此时 kubelet 可能不是 Running 状态，这是正常的。等 Master 初始化或 Worker 加入集群后，kubelet 会正常工作。

2.4 初始化 Master

以下操作只在 Master 节点执行。

2.4.1 预拉取 Kubernetes 镜像

bash 复制代码

kubeadm config images pull \
  --kubernetes-version=v1.32.0 \
  --image-repository=registry.aliyuncs.com/google_containers \
  --cri-socket=unix:///var/run/cri-dockerd.sock

2.4.2 初始化集群

将 172.17.172.87 替换为你的 Master 内网 IP。

bash 复制代码

kubeadm init \
  --apiserver-advertise-address=172.17.172.87 \
  --pod-network-cidr=100.64.0.0/10 \
  --kubernetes-version=v1.32.0 \
  --image-repository=registry.aliyuncs.com/google_containers \
  --cri-socket=unix:///var/run/cri-dockerd.sock

初始化成功后，会看到类似输出：

bash 复制代码

kubeadm join 172.17.172.87:6443 --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash>

请保存这段 kubeadm join 命令，后面 Worker 节点加入集群需要使用。

2.4.3 配置 kubectl

root 用户执行：

bash 复制代码

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

验证：

bash 复制代码

kubectl get nodes

此时 Master 可能显示 NotReady，这是因为还没有安装网络插件。

2.4.4 安装 Calico 网络插件

下载 Calico manifest：

bash 复制代码

curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.29.1/manifests/calico.yaml

由于本文初始化集群时使用的 Pod 网段是 100.64.0.0/10，需要确认 Calico 的 CALICO_IPV4POOL_CIDR 与该网段一致。

如果 calico.yaml 中存在 CALICO_IPV4POOL_CIDR，可以这样替换：

bash 复制代码

sed -i 's#192.168.0.0/16#100.64.0.0/10#g' calico.yaml

应用 Calico：

bash 复制代码

kubectl apply -f calico.yaml

查看系统 Pod 状态：

bash 复制代码

kubectl get pods -n kube-system -w

等 calico-node、calico-kube-controllers 等组件变为 Running 后，再查看节点状态：

bash 复制代码

kubectl get nodes -o wide

2.5 Worker 加入集群

以下操作在两台 Worker 节点分别执行。

使用 Master 初始化时输出的 kubeadm join 命令，并追加 --cri-socket 参数：

bash 复制代码

kubeadm join 172.17.172.87:6443 --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash> \
  --cri-socket=unix:///var/run/cri-dockerd.sock

如果忘记保存 join 命令，可以在 Master 节点重新生成：

bash 复制代码

kubeadm token create --print-join-command

然后把输出命令复制到 Worker 节点执行，并追加：

bash 复制代码

--cri-socket=unix:///var/run/cri-dockerd.sock

Worker 加入成功后，在 Master 节点查看：

bash 复制代码

kubectl get nodes -o wide

2.6 验证集群

以下操作在 Master 节点执行。

2.6.1 查看节点状态

bash 复制代码

kubectl get nodes -o wide

预期结果：

text 复制代码

NAME          STATUS   ROLES           AGE   VERSION
k8s-master    Ready    control-plane   10m   v1.32.x
k8s-worker1   Ready    <none>          5m    v1.32.x
k8s-worker2   Ready    <none>          5m    v1.32.x

2.6.2 查看系统组件

bash 复制代码

kubectl get pods -A

重点确认以下组件为 Running：

kube-apiserver
kube-controller-manager
kube-scheduler
etcd
kube-proxy
calico-node
calico-kube-controllers

2.6.3 创建测试应用

创建 nginx Deployment：

bash 复制代码

kubectl create deployment nginx --image=nginx:1.25

暴露 NodePort 服务：

bash 复制代码

kubectl expose deployment nginx --port=80 --type=NodePort

查看 Pod 和 Service：

bash 复制代码

kubectl get pod -o wide
kubectl get svc nginx

输出示例：

text 复制代码

NAME    TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)
nginx   NodePort   10.96.xxx.xxx   <none>        80:30xxx/TCP

浏览器或命令行访问任意节点的 NodePort：

bash 复制代码

curl http://172.17.172.87:30xxx
curl http://172.17.172.89:30xxx
curl http://172.17.172.90:30xxx

测试完成后清理：

bash 复制代码

kubectl delete svc nginx
kubectl delete deployment nginx

2.6.4 常用排查命令

bash 复制代码

kubectl get nodes
kubectl get pods -A
kubectl describe node <node-name>
kubectl describe pod <pod-name> -n <namespace>
journalctl -u kubelet -f
journalctl -u docker -f
journalctl -u cri-docker -f

如果需要重置节点：

bash 复制代码

kubeadm reset -f --cri-socket=unix:///var/run/cri-dockerd.sock
rm -rf /etc/cni/net.d /var/lib/kubelet /var/lib/etcd $HOME/.kube

3. 安装 Kuboard （可选）

3.1 部署说明

Kuboard 是 Kubernetes 的图形化管理工具，可以通过 Web 页面查看和管理集群资源，包括 Namespace、Deployment、Service、Pod、ConfigMap、Secret、日志、终端等。

Kuboard 常见部署方式如下：

部署方式	说明	适用场景
Docker 单机部署	Kuboard 运行在某台服务器的 Docker 容器中，集群内通过 Agent 接入	简单、稳定、适合学习和中小环境
Kubernetes 内部署	Kuboard 作为工作负载运行在 Kubernetes 集群中	希望所有组件都由 Kubernetes 管理
Kuboard-Spray	通过图形化方式安装和维护 Kubernetes 集群	希望使用 Web 页面管理集群生命周期

本文使用 Docker 单机部署方式：

Kuboard 容器运行在 Master 宿主机上。
Kuboard 不部署到 Kubernetes 集群内部。
Kubernetes 集群通过 Kuboard-Agent 接入 Kuboard。
Agent 通过 Master 内网 IP 访问 Kuboard。

本文端口规划：

端口	用途
38000	Kuboard Web 页面访问端口
38001	Kuboard-Agent 回连端口

如果使用云服务器，需要在安全组中放行 38000。38001 建议仅允许集群内网访问。

3.2 单机 Docker 部署

以下操作在 Master 节点执行。

3.2.1 启动 Kuboard 容器

将 172.17.172.87 替换为 Master 内网 IP。

bash 复制代码

docker pull swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3

mkdir -p /root/kuboard-data

docker run -d \
  --restart=unless-stopped \
  --privileged \
  --name=kuboard \
  -p 38000:80/tcp \
  -p 38001:10081/tcp \
  -e KUBOARD_ENDPOINT="http://172.17.172.87:58094" \
  -e KUBOARD_AGENT_SERVER_TCP_PORT="58099" \
  -v /root/kuboard-data:/data \
  swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3

参数说明：

参数	说明
`-p 38000:80`	浏览器访问 Kuboard Web 页面
`-p 38001:10081`	Kuboard-Agent 回连 Kuboard
`KUBOARD_ENDPOINT`	Agent 访问 Kuboard 的地址，必须使用集群内可达 IP
`KUBOARD_AGENT_SERVER_TCP_PORT`	Agent 回连端口，需要与宿主机映射端口一致
`/root/kuboard-data:/data`	Kuboard 数据持久化目录

注意：KUBOARD_ENDPOINT 不要写成 127.0.0.1 或 localhost，否则集群内的 Agent 无法访问 Kuboard。

3.2.2 查看 Kuboard 状态

bash 复制代码

docker ps --filter name=kuboard
docker logs -f kuboard

容器状态为 Up 即表示启动成功。

3.2.3 访问 Kuboard

浏览器访问：

text 复制代码

http://<Master公网IP>:38000

默认账号密码：

项目	值
用户名	admin
密码	Kuboard123

首次登录后建议立即修改默认密码。

3.3 添加集群

Kuboard 启动后，需要将 Kubernetes 集群添加到 Kuboard。

3.3.1 使用 Kuboard-Agent 添加集群

操作步骤：

登录 Kuboard。
点击「添加集群」。
选择「Kuboard-Agent」方式。
填写集群名称，例如 ubuntu24-k8s。
Kuboard 页面会生成一段 kubectl apply 命令。
复制该命令，在 Master 节点执行。

执行完成后，查看 Agent Pod：

bash 复制代码

kubectl get pods -n kuboard

等待 Agent 相关 Pod 变为 Running 后，Kuboard 页面中的集群状态会变为正常。

4. 总结

本文完成了 Ubuntu Server 24.04 环境下一主两从 Kubernetes 集群的部署，主要步骤包括：

初始化三台服务器环境。
安装 Docker 和 cri-dockerd。
安装 kubeadm、kubelet、kubectl。
使用 kubeadm 初始化 Master。
安装 Calico 网络插件。
将两个 Worker 节点加入集群。
验证 Kubernetes 集群状态。
使用 Docker 单机模式部署 Kuboard。
通过 Kuboard-Agent 添加 Kubernetes 集群。

对于学习、测试和中小规模集群来说，kubeadm + Docker + cri-dockerd + Calico + Kuboard 是一套比较容易理解和维护的部署方案。生产环境中还需要进一步考虑高可用 Master、etcd 备份、镜像仓库、监控告警、日志采集、证书轮换和安全加固等内容。