Kubeadm on Liangweidong's blog

Kubernetes 1.x 部署实战：Debian/Ubuntu Kubeadm 初始化与集群规划

Sun, 15 Jun 2025 00:00:00 +0800

背景

Kubernetes（K8s）2014-06 由 Google 开源，2015-07 推出 1.0 版本，如今已是容器编排领域的事实标准。

K8s 解决了什么：

跨机器调度容器（哪台机器跑哪个 Pod）
自愈（容器挂了自动重启）
滚动升级（无停机发布）
服务发现 + 负载均衡
配置管理（ConfigMap / Secret）
存储编排（PV / PVC）

部署 K8s 集群的几种方式：

方式	难度	适用
kubeadm	中	官方推荐、学习首选
kubespray	中	裸金属/混合云，Ansible 自动化
Kops	中	AWS 专用
minikube / kind	低	本地学习
RKE / K3s	低	轻量级、边缘
云厂商托管（EKS/AKS/ACK）	最低	生产首选，免运维

本篇：用 kubeadm 在 Debian/Ubuntu 上手把手部署 1.x 集群，并讲清楚集群规模怎么选。

一、集群规模规划

1.1 最小集群

2 节点：1 master + 1 worker

不推荐生产——master 单点
适合个人学习、临时测试

1.2 推荐最小生产

3 节点：1 master + 2 worker

master 单点（生产勉强）
worker 至少 2 台做 HA 业务

1.3 标准生产

5 节点：3 master + 2 worker

3 master 跑 etcd 集群（容忍 1 台挂）
2 worker 跑业务（容忍 1 台挂）

1.4 规模生产

7 节点：3 master + 4 worker

3 master + 4 worker（worker 可以再多）
7 节点是 K8s 官方文档举例的标准规模

1.5 大规模集群

20+ 节点：

master 必须 3 台或 5 台
worker 数量按业务量扩展
配合 Ingress Controller、Pod 网络 CNI、存储 CSI 等组件

1.6 选型原则

业务规模	推荐节点数	说明
个人/学习	1-2	跑 minikube 就够
小团队（< 50 服务）	3-5	单 master 也能用
中型企业（50-200 服务）	7-10	3 master + 5+ worker
大型企业（200+ 服务）	20+	拆多集群

集群不是越大越好：

节点越多，网络/etcd 同步成本越高
100 节点以上的集群，K8s 控制面性能开始下降
一般 30-50 节点一个集群 较优

二、环境准备

2.1 硬件要求

角色	CPU	内存	磁盘
master	≥ 2 核	≥ 2 GB	≥ 20 GB
worker	≥ 1 核	≥ 1 GB	≥ 20 GB
etcd 专用	≥ 4 核	≥ 8 GB	SSD ≥ 50 GB

生产 master 建议：

4 核 8 GB 起
SSD（etcd 写延迟敏感）

2.2 系统要求

OS：Ubuntu 20.04+ / Debian 11+
内核：≥ 4.19（Ubuntu 20.04 / Debian 11 默认）
网络：所有节点互通
关闭 swap：swapoff -a
关闭防火墙 或放行 K8s 端口（6443、10250、8472/UDP）

2.3 必备设置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 1. 关闭 swap
swapoff -a
sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# 2. 加载内核模块
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
br_netfilter
EOF
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
EOF
sudo sysctl --system

# 3. 设置 hostname（每台不同）
hostnamectl set-hostname master1
# 或 worker1

三、安装 kubeadm / kubelet / kubectl

3.1 更新 apt 索引

1
2


sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl

3.2 添加 Kubernetes apt 仓库

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 下载 Google Cloud 公开签名密钥
sudo curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg \
 https://packages.cloud.google.com/apt/doc/apt-key.gpg

# 添加 apt 源
echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] \
https://apt.kubernetes.io/ kubernetes-xenial main" | \
 sudo tee /etc/apt/sources.list.d/kubernetes.list

# 更新索引
sudo apt-get update

3.3 安装组件并锁定版本

1
2


sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

apt-mark hold 至关重要：

K8s 组件必须保持版本一致（kubelet 1.28.2 配 kubeadm 1.28.2）
apt 自动升级会破坏集群
升级必须手动用 kubeadm upgrade 流程

3.4 三个组件的关系

组件	作用	装在
kubeadm	初始化集群的指令	所有节点
kubelet	在每个节点上启动 Pod 和容器的代理	所有节点
kubectl	与集群通信的命令行工具	通常只在 master / 运维机器

为什么不只装一个？kubeadm 是"一次性启动器"，kubelet 是"持续运行代理"，kubectl 是"客户端工具"，三者各司其职。

3.5 kubelet 的"死循环"问题

安装完 kubelet 后，每隔几秒就会重启——

kubelet 现在每隔几秒就会重启，因为它陷入了一个等待 kubeadm 指令的死循环。

正常现象！kubelet 启动后等 kubeadm init 或 kubeadm join 指令，没有指令就一直重启。kubeadm init 完成后就不再重启。

3.6 启用 bash 自动补全

1
2
3
4
5
6
7
8


apt-get install bash-completion

# 临时生效
source <(kubectl completion bash)

# 永久生效
echo "source <(kubectl completion bash)" >> ~/.bashrc
source ~/.bashrc

按 Tab 就能补全 kubectl 子命令。

3.7 拉取 K8s 所需镜像

1
2
3
4
5
6
7
8
9


kubeadm config images list
# 列出 kubeadm init 时要拉的所有镜像
# k8s.gcr.io/kube-apiserver:v1.28.x
# k8s.gcr.io/kube-controller-manager:v1.28.x
# k8s.gcr.io/kube-scheduler:v1.28.x
# k8s.gcr.io/kube-proxy:v1.28.x
# k8s.gcr.io/pause:3.9
# k8s.gcr.io/etcd:3.5.x
# k8s.gcr.io/coredns/coredns:v1.10.x

⚠️ 2024-05 之后的版本：k8s.gcr.io 改为 registry.k8s.io（Google 自有域名）。老教程里的 k8s.gcr.io 可能要改。

国内用户（gcr.io 被墙）：

1
2


# 用国内镜像
kubeadm init --image-repository registry.aliyuncs.com/google_containers

四、初始化 master 节点

4.1 一行命令

1
2
3
4
5
6


sudo kubeadm init \
 --apiserver-advertise-address=<master-ip> \
 --image-repository registry.aliyuncs.com/google_containers \
 --kubernetes-version v1.28.0 \
 --service-cidr=10.96.0.0/12 \
 --pod-network-cidr=10.244.0.0/16

参数说明：

参数	作用
`--apiserver-advertise-address`	master 节点 IP（worker 连这个）
`--image-repository`	镜像仓库（国内用阿里云）
`--kubernetes-version`	K8s 版本（必须与 apt 装的 kubeadm 一致）
`--service-cidr`	Service IP 段
`--pod-network-cidr`	Pod IP 段（必须与 CNI 插件一致）

4.2 安装 CNI 网络插件

K8s 不自带网络，必须装一个 CNI：

Flannel（最简单）：

1

kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

Calico（功能强、推荐生产）：

1

kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

Cilium（eBPF、性能最强）：

1

kubectl create -f https://raw.githubusercontent.com/cilium/cilium/v1.14/install/kubernetes/quick-install.yaml

4.3 配置 kubectl

1
2
3


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

4.4 验证 master 节点

1
2
3
4
5
6


kubectl get nodes
# NAME STATUS ROLES AGE VERSION
# master1 Ready control-plane 5m v1.28.0

kubectl get pods -A
# 所有系统 Pod 应该是 Running

五、worker 节点加入

5.1 在 master 上获取 join 命令

1
2
3
4


kubeadm token create --print-join-command
# 输出类似：
# kubeadm join 10.0.0.10:6443 --token abcdef.0123456789abcdef \
# --discovery-token-ca-cert-hash sha256:xxxxx

5.2 在每个 worker 上执行

1
2
3


sudo kubeadm join 10.0.0.10:6443 \
 --token abcdef.0123456789abcdef \
 --discovery-token-ca-cert-hash sha256:xxxxx

5.3 验证集群

1
2
3
4
5


kubectl get nodes
# NAME STATUS ROLES AGE VERSION
# master1 Ready control-plane 10m v1.28.0
# worker1 Ready <none> 2m v1.28.0
# worker2 Ready <none> 2m v1.28.0

六、常见问题

6.1 kubeadm init 失败：端口占用

1

[ERROR Port-6443]: Port 6443 is in use

对策：

1
2
3


# 找到占用进程
lsof -i :6443
# 杀掉

6.2 kubeadm init 失败：镜像拉不到

国内：

1

sudo kubeadm init --image-repository registry.aliyuncs.com/google_containers ...

国外：

1
2
3
4


# 看具体哪个镜像失败
kubeadm config images list
docker pull <image>
# 重试

6.3 kubectl get nodes 显示 NotReady

1
2
3
4
5


# 看 kubelet 日志
journalctl -u kubelet -f

# 常见：CNI 没装
# 装 flannel/calico

6.4 节点加入后 5 分钟还是 NotReady

1
2
3
4


# 在 worker 上看 kubelet 日志
journalctl -u kubelet -f

# 常见：网络不通（6443 端口）、token 过期（默认 24h）、ca hash 不对

6.5 重置集群（重新 init）

1
2
3


# 在每个节点上
sudo kubeadm reset
sudo rm -rf /etc/kubernetes /var/lib/etcd

七、升级（必须按 kubeadm 流程）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# 1. 升级 kubeadm
sudo apt-get update
sudo apt-get install -y kubeadm=1.29.x-00
sudo apt-mark hold kubeadm

# 2. drain 节点
kubectl drain <node-name> --ignore-daemonsets

# 3. 升级
sudo kubeadm upgrade apply v1.29.x

# 4. 升级 kubelet/kubectl
sudo apt-get install -y kubelet=1.29.x-00 kubectl=1.29.x-00
sudo apt-mark hold kubelet kubectl
sudo systemctl restart kubelet

# 5. uncordon
kubectl uncordon <node-name>

升级顺序：

先 master（一台一台滚）
再 worker（kubectl drain → upgrade → uncordon）
不要跨大版本（1.28 → 1.30 风险大，逐版本 1.28 → 1.29 → 1.30）

八、生产级建议

8.1 高可用 master

3 master 模式（堆叠 etcd）：

1
2
3
4
5
6


# 第一台 master
sudo kubeadm init --control-plane-endpoint "lb-vip:6443" --upload-certs

# 其他 master 用同一命令的 join 输出
sudo kubeadm join lb-vip:6443 --token xxx --discovery-token-ca-cert-hash xxx \
 --control-plane --certificate-key xxx

前置条件：

3 台 master 节点
一个负载均衡 VIP（HAProxy / 云 LB）
VIP 后端 3 台 master 的 6443 端口

8.2 关闭 master 上的业务 Pod

1
2
3


kubectl taint nodes --all node-role.kubernetes.io/control-plane-
# 或反操作：加 taint 让 master 不跑业务
kubectl taint nodes master1 node-role.kubernetes.io/control-plane:NoSchedule

8.3 备份 etcd

1
2
3
4
5
6
7
8
9


# 找 etcd pod
kubectl get pods -n kube-system | grep etcd

# 备份
ETCDCTL_API=3 etcdctl snapshot save /backup/etcd-$(date +%F).db \
 --endpoints=https://127.0.0.1:2379 \
 --cacert=/etc/kubernetes/pki/etcd/ca.crt \
 --cert=/etc/kubernetes/pki/etcd/server.crt \
 --key=/etc/kubernetes/pki/etcd/server.key

8.4 监控与日志

metrics-server：kubectl top node/pod
Prometheus + Grafana：监控指标
Loki + Promtail：日志聚合
Jaeger / Tempo：链路追踪

九、卸载

1
2
3
4
5


# 在每个节点
sudo kubeadm reset
sudo apt remove kubeadm kubelet kubectl -y
sudo apt-mark unhold kubeadm kubelet kubectl
sudo rm -rf /etc/kubernetes /var/lib/etcd ~/.kube

小结

K8s 1.x 部署的核心三件套：

kubeadm（init/join 工具）
kubelet（节点代理，每台都装）
kubectl（客户端工具）

集群规模：

学习：1-2 节点（minikube / kind）
生产：3 master + N worker（推荐起点 5 节点）
超大规模：拆多集群，单集群 ≤ 50 节点

生产部署三原则：

HA master（3 台）+ 负载均衡 VIP
apt-mark hold 锁定版本
按官方 kubeadm 流程升级（不要 apt 升级破坏集群）

下一步：

装 Helm（K8s 包管理）
部署 Ingress Controller（Nginx / Traefik）
用 ArgoCD / Flux 做 GitOps
上 Istio / Linkerd 服务网格

源文档：

os/linux/第三方tools/dev/kubernetes/debian安装kubernetes.md（apt 源、版本锁定、bash-completion）
os/linux/第三方tools/dev/kubernetes/k8s集群.md（2/3/5 节点规模选型）

K8s Kubeadm 一键部署：从节点规划到应用上线

Wed, 15 Jun 2022 00:00:00 +0800

写于 2022-06，背景：K8s 1.24 正式移除 dockershim，1.25 GA。本文以 kubeadm 1.25 + containerd 1.7 + Ubuntu 22.04 为模板，覆盖从单机到多节点 kubeadm 部署完整流程。

一、Kubeadm vs 二进制部署

维度	kubeadm	二进制
学习成本	低（1 行 init）	高（30+ 步骤）
灵活度	中（kubeadm 配置项可调）	极高（所有 systemd 单元自己写）
升级	官方 `kubeadm upgrade` 一条命令	手动替换二进制 + 改配置
适合场景	生产首选	学习 / 深度定制
证书管理	kubeadm 自动签发 + 90 天续期	自己签 + 自己续
集群自举	kubeadm 自动完成所有控制平面组件部署	自己启动 6+ 个 systemd 单元

结论：生产用 kubeadm，学习用二进制。两者结合最理想。

二、集群规划

3 master + N worker HA 集群（生产推荐）：

主机名	IP	角色	OS
master1	192.168.139.133	master	Ubuntu 22.04
master2	192.168.139.134	master	Ubuntu 22.04
master3	192.168.139.135	master	Ubuntu 22.04
worker1	192.168.139.136	worker	Ubuntu 22.04
worker2	192.168.139.137	worker	Ubuntu 22.04
VIP	192.168.139.150	浮动	（Keepalived）

单 master 集群（测试）：

主机名	IP
master1	192.168.139.133
worker1	192.168.139.136

网络规划：

Node 网络：192.168.139.0/24
Service 网络：10.96.0.0/12
Pod 网络：172.218.0.0/16（Calico）

三、所有节点系统配置

3.1 主机名 + hosts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 每个节点
hostnamectl set-hostname master1 # 各节点不同

# 所有节点
cat >> /etc/hosts <<EOF
192.168.139.133 master1
192.168.139.134 master2
192.168.139.135 master3
192.168.139.136 worker1
192.168.139.137 worker2
EOF

3.2 关闭 swap / 防火墙 / SELinux

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# swap（K8s 强制关）
swapoff -a
sed -ri 's/.*swap.*/#&/' /etc/fstab

# 防火墙（K8s 自己用 iptables）
systemctl stop ufw && systemctl disable ufw
# CentOS: systemctl stop firewalld && systemctl disable firewalld

# SELinux（CentOS 才有）
setenforce 0
sed -i 's#SELINUX=enforcing#SELINUX=disabled#g' /etc/selinux/config

3.3 时间同步

1
2
3


timedatectl set-timezone Asia/Shanghai
apt install -y ntpdate
echo "0 */1 * * * ntpdate time1.aliyun.com" >> /var/spool/cron/crontabs/root

3.4 内核模块与参数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 加载模块
cat <<EOF > /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF
modprobe overlay
modprobe br_netfilter

# 内核参数
cat <<EOF > /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

3.5 ulimit / IPVS（master 节点）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


ulimit -SHn 65535
cat >> /etc/security/limits.conf <<EOF
* soft nofile 655360
* hard nofile 131072
* soft nproc 655350
* hard nproc 655350
EOF

apt install -y ipset ipvsadm
cat <<EOF | tee /etc/modules-load.d/ipvs.conf
ip_vs
ip_vs_rr
ip_vs_wrr
ip_vs_sh
nf_conntrack
EOF
systemctl restart systemd-modules-load.service
lsmod | grep ip_vs

四、安装 containerd（K8s 1.24+）

K8s 1.24 移除 dockershim，必须装 containerd / CRI-O。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 下载
wget https://github.com/containerd/containerd/releases/download/v1.7.11/cri-containerd-1.7.11-linux-amd64.tar.gz

# 解压到根目录
tar Cxzvf / cri-containerd-1.7.11-linux-amd64.tar.gz

# 生成配置
mkdir /etc/containerd
containerd config default > /etc/containerd/config.toml

# 改 sandbox_image 为阿里云镜像
sed -i 's#k8s.gcr.io/pause:3.8#registry.aliyuncs.com/google_containers/pause:3.9#g' /etc/containerd/config.toml

# 改 SystemdCgroup
sed -i 's#SystemdCgroup = false#SystemdCgroup = true#g' /etc/containerd/config.toml

# 启动
systemctl daemon-reload
systemctl enable --now containerd
systemctl status containerd

五、安装 kubeadm / kubelet / kubectl

5.1 阿里云镜像源（推荐 cn region）

1
2
3
4
5


curl https://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg | \
 gpg --dearmor > /usr/share/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/kubernetes-apt-keyring.gpg] https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main' | \
 sudo tee /etc/apt/sources.list.d/kubernetes.list
apt update

5.2 安装

1
2
3
4
5
6
7
8


# 查看可用版本
apt-cache madison kubeadm

# 安装指定版本（1.28.2 阿里云镜像版本）
apt install -y kubelet=1.28.2-0 kubeadm=1.28.2-0 kubectl=1.28.2-0

# 锁定版本（防止 apt upgrade 误升）
apt-mark hold kubelet kubeadm kubectl

5.3 命令补全（所有节点）

1
2
3


echo 'source <(kubectl completion bash)' >> ~/.bashrc
alias k=kubectl
complete -F __start_kubectl k

六、初始化 master 节点

6.1 单 master 集群

1
2
3
4
5
6
7
8
9


# 预下载镜像（可选，但生产推荐）
kubeadm config images pull --image-repository=registry.aliyuncs.com/google_containers

# 初始化（默认 /etc/kubernetes/admin.conf）
kubeadm init \
 --image-repository=registry.aliyuncs.com/google_containers \
 --kubernetes-version=v1.28.2 \
 --pod-network-cidr=172.218.0.0/16 \
 --service-cidr=10.96.0.0/12

6.2 高可用集群（3 master）

先用 kubeadm-config.yaml 配置 VIP：

1

kubeadm config print init-defaults > kubeadm-config.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


# 编辑 kubeadm-config.yaml
apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
localAPIEndpoint:
 advertiseAddress: 192.168.139.133 # master1 IP
 bindPort: 6443
nodeRegistration:
 criSocket: unix:///var/run/containerd/containerd.sock
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: v1.28.2
controlPlaneEndpoint: "192.168.139.150:6443" # VIP（Keepalived 漂移）
imageRepository: registry.aliyuncs.com/google_containers
networking:
 podSubnet: 172.218.0.0/16
 serviceSubnet: 10.96.0.0/12
etcd:
 local:
 extraArgs:
 listen-client-urls: "https://127.0.0.1:2379,https://192.168.139.133:2379"
 advertise-client-urls: "https://192.168.139.133:2379"

1
2
3
4
5


# 初始化
kubeadm init --config kubeadm-config.yaml --upload-certs

# 注意：--upload-certs 自动把证书上传到 etcd
# 其他 master 用 kubeadm join 时加 --certificate-key

保存 join 命令：

1
2
3
4
5
6


# 输出末尾会有 join 命令，复制保存
# 其他 master：
kubeadm join 192.168.139.150:6443 --token xxx --discovery-token-ca-cert-hash sha256:xxx --control-plane --certificate-key xxx

# worker：
kubeadm join 192.168.139.150:6443 --token xxx --discovery-token-ca-cert-hash sha256:xxx

6.3 配置 kubectl

1
2
3
4
5
6
7


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

# 验证
kubectl get nodes
# master1 NotReady control-plane 1m v1.28.2 ← NotReady 因为还没装 CNI

七、安装 CNI（Calico）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# Tigera Operator
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/tigera-operator.yaml

# Custom Resources
cat <<EOF | kubectl apply -f -
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
 name: default
spec:
 calicoNetwork:
 ipPools:
 - blockSize: 26
 cidr: 172.218.0.0/16
 encapsulation: VXLANCrossSubnet
 natOutgoing: Enabled
 nodeSelector: all()
---
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
 name: default
spec: {}
EOF

# 等待所有 calico pod running
kubectl get pods -n calico-system -w

八、加入其他节点

8.1 加入 master 节点

1
2
3
4
5
6


# 在 master2 执行
kubeadm join 192.168.139.150:6443 \
 --token abcdef.0123456789abcdef \
 --discovery-token-ca-cert-hash sha256:xxx \
 --control-plane \
 --certificate-key xxx

8.2 加入 worker 节点

1
2
3
4


# 在 worker1 执行
kubeadm join 192.168.139.150:6443 \
 --token abcdef.0123456789abcdef \
 --discovery-token-ca-cert-hash sha256:xxx

8.3 token 过期

master 节点重新生成：

1
2


kubeadm token create --print-join-command
# 输出直接可用的 join 命令

8.4 验证集群

1
2
3
4
5
6
7


kubectl get nodes
# NAME STATUS ROLES AGE VERSION
# master1 Ready control-plane 10m v1.28.2
# master2 Ready control-plane 5m v1.28.2
# master3 Ready control-plane 3m v1.28.2
# worker1 Ready <none> 1m v1.28.2
# worker2 Ready <none> 1m v1.28.2

九、部署测试应用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


# 1. 部署 Deployment + Service（Nginx）
cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx
spec:
 replicas: 2
 selector:
 matchLabels:
 app: nginx
 template:
 metadata:
 labels:
 app: nginx
 spec:
 containers:
 - name: nginx
 image: nginx
 imagePullPolicy: IfNotPresent
 ports:
 - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
 name: nginx
spec:
 type: NodePort
 selector:
 app: nginx
 ports:
 - protocol: TCP
 port: 80
 targetPort: 80
 nodePort: 30080
EOF

# 2. 查看
kubectl get pods
kubectl get svc nginx
# NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
# nginx NodePort 10.108.108.103 <none> 80:30080/TCP 30s

# 3. 测试访问
curl http://<任意节点 IP>:30080/

十、清理集群

10.1 优雅重置 master

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 先 drain 节点
kubectl drain master1 --delete-emptydir-data --force --ignore-daemonsets

# 删除所有节点
kubectl delete node --all

# 重置
kubeadm reset
rm -rf /etc/cni/net.d/*
rm -rf /var/lib/cni/calico
rm -rf $HOME/.kube
systemctl daemon-reload && systemctl restart kubelet

10.2 清理 worker 节点

1
2
3


kubeadm reset
# 清理 ipvs 规则
ipvsadm --clear

10.3 手动清理（kubeadm reset 失败时）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 停服务
systemctl stop kubelet kube-proxy containerd
systemctl disable kubelet kube-proxy containerd

# 删文件
rm -rf /var/lib/kubelet
rm -rf /var/lib/containerd
rm -rf /etc/kubernetes
rm -rf /etc/cni/net.d
rm -rf /opt/cni/bin
rm -rf /var/log/pods
rm -rf /var/log/containers

# 清 iptables
iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X
ipvsadm --clear

十一、升级集群

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# 1. 查看升级目标
kubeadm upgrade plan

# 2. 升级 kubeadm（先升第一个 master）
apt-mark unhold kubeadm kubelet kubectl
apt install -y kubeadm=1.28.5-00
apt-mark hold kubeadm kubelet kubectl

# 3. drain 节点
kubectl drain master1 --ignore-daemonsets

# 4. 升级 control-plane
kubeadm upgrade apply v1.28.5

# 5. 升级 kubelet + kubectl
apt install -y kubelet=1.28.5-00 kubectl=1.28.5-00
systemctl daemon-reload
systemctl restart kubelet

# 6. uncordon
kubectl uncordon master1

# 7. 其他 master / worker 重复

十二、常见坑

token 过期：默认 24h，过期后 worker 无法 join，重新生成
single master 改 HA：kubeadm 不支持，必须 reset 重装
CNI 没装先 join worker：worker 卡 NotReady，先装 Calico
controlPlaneEndpoint 用了 master1 IP：master1 挂了就完蛋，必须用 VIP 或 DNS
image-repository 没设：国内环境拉镜像超时
kubeadm reset 失败：手动清理（见 10.3）
Calico / CalicoTypha 内存不足：节点 < 2GB 会卡，加 –memory 限制

十三、前置知识 / 下一步

前置：

K8s 架构基础（参考 2017-06-15《Kubernetes 入门》）
Containerd 容器运行时（参考 2019-12-15《Containerd 实战》）
二进制部署（理解原理，参考 2020-03-15《K8s 二进制部署》）

下一步：

K8s 集群插件（2021-09-15）—— CNI/CoreDNS/Metrics/Dashboard
K8s 资源限制与探针（2022-03-15）—— Pod 调优
K8s 集群管理（2021-12-15）—— 升级 / 节点隔离

参考资料

K8s 工具链速装：kubectl / kubeadm / minikube / kind / helm

Sat, 15 Dec 2018 00:00:00 +0800

写于 2018-12，背景：K8s 1.13 GA、Helm v3 alpha 即将发布。客户端工具已经收敛到 kubectl/kubeadm/kubelet 三件套，本地实验工具有 minikube / kind 双雄，包管理是 helm。

一、工具全景图

K8s 生态里跟"集群打交道的"工具，按使用场景分四类：

场景	工具	角色
客户端	`kubectl`	必装，对集群执行命令的唯一官方 CLI
本地实验	`minikube` / `kind`	一键起本地 K8s 集群（学习/测试用）
集群初始化	`kubeadm`	官方推荐的集群 bootstrap 工具
包管理	`helm`	K8s 应用的包管理（类似 apt/yum）

二、kubectl 安装

2.1 二进制安装（推荐）

1
2
3
4
5
6
7
8
9


# 下载最新稳定版
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# 安装
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# 验证
kubectl version --client
kubectl version --client --output=yaml

2.2 apt 安装

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 国外官方源
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | \
 sudo 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.28/deb/ /' | \
 sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt-get install -y kubectl

# 国内阿里源（cn region 推荐）
curl https://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg | \
 gpg --dearmor > /usr/share/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/kubernetes-apt-keyring.gpg] https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main' | \
 sudo tee /etc/apt/sources.list.d/kubernetes.list
apt-get update && apt-get install -y kubectl

2.3 命令补全

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 装 bash-completion
apt-get install bash-completion

# 加到 .bashrc
echo 'source <(kubectl completion bash)' >> ~/.bashrc
source ~/.bashrc

# 推荐别名：把 kubectl 缩成 k
alias k=kubectl
complete -F __start_kubectl k

2.4 kubectl-convert 转换工具

K8s API 经常废弃/迁移，旧的 Deployment extensions/v1beta1 在 1.16 之后要换成 apps/v1。kubectl-convert 一键转换：

1
2
3
4
5


curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl-convert"
sudo install -o root -g root -m 0755 kubectl-convert /usr/local/bin/kubectl-convert

# 把老 API 转换成新 API
kubectl-convert -f old-deployment.yaml --output-version apps/v1

三、kubeadm / kubelet 安装

kubeadm 用于初始化集群，kubelet 是 worker 节点上的核心 agent。它们必须和 kubectl 版本一致（同 minor 版本）：

1
2
3
4
5
6
7


# apt 安装
sudo apt-get install -y kubelet kubeadm kubectl
# 锁定版本，防止 apt upgrade 时被升级
sudo apt-mark hold kubelet kubeadm kubectl

# 查看可用版本
apt-cache madison kubeadm

为什么 lock 版本？ K8s minor 版本升级时 API 可能废弃，跨版本 kubectl 可能无法解析新格式的 manifest。生产环境永远锁版本。

四、minikube：本地 K8s 一体化

minikube 在你本机（Windows/macOS/Linux）启动一个单节点 K8s 集群，适合学习/开发。

4.1 安装

1
2
3
4
5
6


# Linux
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# 验证
minikube version

4.2 启动集群

1
2
3
4
5
6
7
8
9


# 默认 driver（Linux 通常是 docker，macOS 是 hyperkit，Windows 是 hyperv）
minikube start

# 显式指定
minikube start --driver=docker --kubernetes-version=v1.28.5

# 国内环境加代理
minikube start --docker-env http_proxy=http://192.168.x.x:7890 \
 --docker-env https_proxy=http://192.168.x.x:7890

4.3 常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


minikube status # 集群状态
minikube ip # 集群 IP
minikube ssh # SSH 进节点
minikube dashboard --url # Dashboard URL
minikube addons enable metrics-server

# 镜像操作（minikube 自带 docker）
minikube image list
minikube image pull nginx:latest

# 清理
minikube delete --purge --all

五、kind：Docker-in-Docker 集群

kind（Kubernetes in Docker）用 Docker 容器模拟 K8s 节点，可以快速起多节点集群做测试。

5.1 安装

1
2
3
4
5
6


# AMD64 / x86_64
[ $(uname -m) = x86_64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
# ARM64
[ $(uname -m) = aarch64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-arm64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

5.2 与 minikube 对比

维度	minikube	kind
实现	VM / 容器	纯 Docker 容器
多节点	实验性	一等公民（multi-node config）
启动速度	较慢（拉镜像+启动 VM）	很快（共享 host docker 缓存）
适合场景	个人学习、单节点	CI/CD、e2e 测试、多节点演练

注意：kind 集群不能用于生产。它的"集群"本质是 Docker 容器，节点宕机 = 容器被回收，etcd 数据可能丢。

六、Helm：K8s 包管理

Helm 把 K8s 资源打成一个 “Chart”（类似 Debian 的 .deb / Python 的 wheel），方便应用分发和版本管理。

6.1 安装

1
2
3
4
5
6
7


# 下载
curl -L -O https://get.helm.sh/helm-v3.13.3-linux-amd64.tar.gz
tar xvf helm-v3.13.3-linux-amd64.tar.gz
sudo cp linux-amd64/helm /usr/local/bin/

# 验证
helm version

6.2 三大概念

概念	含义
Chart	应用包（yaml 模板 + values.yaml）
Release	Chart 的一个部署实例（同一 Chart 可装多次，每次一个 release）
Repository	Chart 仓库（公共有 artifacthub.io）

6.3 常用命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 添加仓库
helm repo add bitnami https://charts.bitnami.com/bitnami

# 搜索 chart
helm search repo nginx

# 安装（会生成一个 release）
helm install my-nginx bitnami/nginx

# 查看已安装
helm list -A

# 升级（改 values 后）
helm upgrade my-nginx bitnami/nginx --set replicaCount=3

# 回滚
helm rollback my-nginx 1

# 卸载
helm uninstall my-nginx

七、工具选型决策树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


你是要学习 K8s 概念？
 ↓
minikube start （最简单）
 ↓
你需要快速拉起多节点做 CI 测试？
 ↓
kind （Docker 容器，秒级启动）
 ↓
你要部署生产集群？
 ↓
kubeadm init（最常见）
 或
二进制部署（理解原理，2017-2018 主流）
 ↓
你要分发应用到多个集群？
 ↓
helm chart + 私有 repo

八、常见坑

kubectl 与集群版本不一致：kubectl get nodes 报 “couldn’t get version” 时，先 kubectl version 看 client/server 版本
apt 源没换 cn：国外源拉 kubectl 慢到怀疑人生，先换阿里源
minikube 启动失败：99% 是 driver 问题，Linux 推荐 docker，macOS 用 hyperkit
kind 容器间网络不通：通常是因为 host 防火墙，iptables 临时关一下验证
Helm v2 → v3 迁移：v2 还需要 Tiller（一个集群内 agent），v3 完全去除了，更安全

九、前置知识 / 下一步

前置：Docker 基础、K8s 架构概念（参考 2017-06-15《Kubernetes 入门》）

下一步：

Containerd 实战（2019-12-15）—— 替代 Docker 的轻量容器运行时
K8s 二进制部署（2020-03-15）—— 深入理解组件协作
Kubeadm 一键部署（2022-06-15）—— 生产环境部署实战

参考资料

2024+ 视角

K8s 工具链到 2024-2026 年整体走向"轻量化 + 声明式 + 多云"：

kubectl 被 Krew 增强：Krew 已成为 kubectl 插件事实标准（200+ 插件），推荐安装 ctx、ns、tail、images、resource-capacity、node-shell、mtail 等，把 kubectl 从 CLI 升级为"瑞士军刀"。
kind 持续领先本地多节点测试：kind v0.20+ 支持 loadbalancer mirror（模拟云 LB）、Ingress dual-stack、extraPortMappings；CI 集成（GitHub Actions、GitLab CI）首选 kind + MetalLB。k3d（k3s on Docker）在低资源 CI 环境也很流行。
minikube 地位变化：v1.32+ minikube 默认 driver 仍为 docker，但实际场景已被 kind/k3d 蚕食——CI 几乎全用 kind/k3d，个人学习仍可用 minikube（自带 dashboard、metrics-server addon）。
Helm 4.0 路线图（2025）：v3.x 仍是主流，但 Helm 4 计划将 --dependency-build 改为 helm dependency up 单一命令、引入 OCI registry 默认（Helm 3.8 已支持 OCI，Helm 4 默认全 OCI）。生产强烈建议 OCI 化——避免 HTTP tgz repo 不可达。
新工具崛起：
- k9s（终端 TUI，kubectl 的视觉化）——运维日常神器
- Lens / OpenLens（桌面 IDE）—— 团队协作场景
- Argo CD / Flux（GitOps）—— K8s 部署的事实标准
- Karpenter（AWS）或 Cluster Autoscaler（多云）——节点自动扩缩容
- Kustomize（裸 YAML 模板）—— 已被 kubectl 1.14+ 内置，kubectl apply -k
包管理二分：Helm 仍是 Chart 的事实标准，KubeVela / Open Application Model（OAM） 在多云/多集群部署场景作为补充。

实战选型更新（2024 视角）：

本地学习：minikube（dashboard 加分）
CI 集成：kind（首选） / k3d（低资源）
生产部署：Helm 3 + OCI + Argo CD（GitOps）
运维日常：k9s + Krew
集群自扩缩：Karpenter（AWS）或 Cluster Autoscaler（多云）

2018 年这篇的"kubectl/kubeadm/kind/helm 四件套"基础仍然成立，变化的是 OCI、GitOps、可视化运维这三层。