Kubernetes 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 二进制部署：软件准备 / 证书 / 工具 / 组件全流程

Thu, 15 May 2025 00:00:00 +0800

写于 2020-03，背景：K8s 1.18 刚 GA，二进制部署仍是国内大厂主流（比 kubeadm 灵活、可定制）。本文以 3 master 高可用集群 + Ubuntu 22.04 为模板，覆盖从软件准备到所有组件 systemd 启动的完整流程。

一、为什么还要学二进制部署

部署方式	优点	缺点
kubeadm	一行命令搞定，官方推荐	黑盒多，问题排查难
二进制	完全可控，组件协作透明	步骤多，容易踩坑
k8s-operator	适合自建 PaaS	上手成本高

结论：生产用 kubeadm 部署，但学习用二进制才能真正理解 K8s。

二、集群规划

3 master + N worker 高可用集群：

主机名	IP	角色
master1	`192.168.139.133`	master + worker（混合）
master2	`192.168.139.134`	master + worker
master3	`192.168.139.135`	master + worker
VIP	`192.168.139.150`	Keepalived 漂移的虚拟 IP
worker1~N	自定	纯 worker

网络规划：

名称	网段
Node 网络	`192.168.139.0/24`
Service 网络	`10.96.0.0/12`
Pod 网络	`172.218.0.0/16`

三、软件准备

所有节点创建统一目录：

1

mkdir -p /k8s/softs

3.1 下载 K8s Server 包

1
2


# 1.28.5 完整 server 包（含所有 master/worker 组件二进制）
wget https://dl.k8s.io/v1.28.5/kubernetes-server-linux-amd64.tar.gz

3.2 下载 etcd

1

wget https://github.com/etcd-io/etcd/releases/download/v3.5.11/etcd-v3.5.11-linux-amd64.tar.gz

3.3 下载 cfssl（证书签发工具）

1
2
3
4
5
6
7
8


wget https://github.com/cloudflare/cfssl/releases/download/v1.6.4/cfssl_1.6.4_linux_amd64
wget https://github.com/cloudflare/cfssl/releases/download/v1.6.4/cfssljson_1.6.4_linux_amd64
wget https://github.com/cloudflare/cfssl/releases/download/v1.6.4/cfssl-certinfo_1.6.4_linux_amd64

cp cfssl_1.6.4_linux_amd64 /usr/local/bin/cfssl
cp cfssljson_1.6.4_linux_amd64 /usr/local/bin/cfssljson
cp cfssl-certinfo_1.6.4_linux_amd64 /usr/local/bin/cfssl-certinfo
chmod +x /usr/local/bin/cfssl /usr/local/bin/cfssljson /usr/local/bin/cfssl-certinfo

四、系统配置（所有节点）

4.1 禁用 swap

1
2
3


free -m
swapoff -a
sed -ri 's/.*swap.*/#&/' /etc/fstab

4.2 禁用防火墙

1
2
3
4
5
6


# Ubuntu
sudo systemctl stop ufw
sudo systemctl disable ufw
# CentOS 7
systemctl stop firewalld
systemctl disable firewalld

4.3 关闭 SELinux（CentOS）

1
2


setenforce 0
sed -i 's#SELINUX=enforcing#SELINUX=disabled#g' /etc/selinux/config

4.4 时间同步

1
2
3


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

4.5 加载 IPVS 模块

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


apt install ipvsadm ipset sysstat conntrack -y
cat >> /etc/modules-load.d/ipvs.conf <<EOF
ip_vs
ip_vs_rr
ip_vs_wwr
ip_vs_sh
nf_conntrack
ip_tables
ip_set
xt_set
ipt_set
ipt_rpfilter
ipt_REJECT
ipip
EOF
systemctl restart systemd-modules-load.service
lsmod | grep -e ip_vs -e nf_conntrack

4.6 内核参数

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


cat << EOF > /etc/sysctl.d/k8s.conf
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
fs.may_detach_mounts = 1
vm.overcommit_memory = 1
vm.panic_on_oom = 0
fs.inotify.max_user_watches = 89100
fs.file-max = 52706963
fs.nr_open = 52706963
net.netfilter.nf_conntrack_max = 2310720
net.ipv4.tcp_keepalive_time = 600
net.ipv4.tcp_keepalive_probes = 3
net.ipv4.tcp_keepalive_intvl = 15
net.ipv4.tcp_max_tw_buckets = 36000
net.ipv4.tcp_tw_reuse = 1
net.core.somaxconn = 16384
EOF
sysctl --system

4.7 ulimit 调优

1
2
3
4
5
6
7
8
9


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

五、证书签发（master1 操作）

K8s 集群里几乎所有通信都走 TLS，证书是入门第一道坎。

5.1 etcd 证书

 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


mkdir -p /k8s/softs/pki && cd /k8s/softs/pki

# 写入 ca 配置
cat > ca-config.json << EOF
{
 "signing": {
 "default": { "expiry": "876000h" },
 "profiles": {
 "kubernetes": {
 "usages": ["signing", "key encipherment", "server auth", "client auth"],
 "expiry": "876000h"
 }
 }
 }
}
EOF

# etcd CA
cat > etcd-ca-csr.json << EOF
{
 "CN": "etcd",
 "key": { "algo": "rsa", "size": 2048 },
 "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "etcd", "OU": "Etcd Security" }],
 "ca": { "expiry": "876000h" }
}
EOF

cfssl gencert -initca etcd-ca-csr.json | cfssljson -bare /etc/etcd/ssl/etcd-ca

# etcd server 证书（注意 hostname 和 IP）
cat > etcd-csr.json << EOF
{
 "CN": "etcd",
 "key": { "algo": "rsa", "size": 2048 },
 "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "etcd", "OU": "Etcd Security" }]
}
EOF

cfssl gencert \
 -ca=/etc/etcd/ssl/etcd-ca.pem \
 -ca-key=/etc/etcd/ssl/etcd-ca-key.pem \
 -config=ca-config.json \
 -hostname=127.0.0.1,master1,master2,master3,192.168.139.133,192.168.139.134,192.168.139.135 \
 -profile=kubernetes \
 etcd-csr.json | cfssljson -bare /etc/etcd/ssl/etcd

5.2 K8s CA 与 apiserver 证书

 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


# K8s CA（10 年有效）
cat > ca-csr.json << EOF
{
 "CN": "kubernetes",
 "key": { "algo": "rsa", "size": 2048 },
 "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "kubernetes", "OU": "K8s CA" }],
 "ca": { "expiry": "876000h" }
}
EOF

cfssl gencert -initca ca-csr.json | cfssljson -bare /etc/kubernetes/pki/ca

# apiserver 证书（多个 hostname/IP）
cat > apiserver-csr.json << EOF
{
 "CN": "kube-apiserver",
 "key": { "algo": "rsa", "size": 2048 },
 "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "kubernetes", "OU": "K8s" }]
}
EOF

cfssl gencert \
 -ca=/etc/kubernetes/pki/ca.pem \
 -ca-key=/etc/kubernetes/pki/ca-key.pem \
 -config=ca-config.json \
 -hostname=10.96.0.1,192.168.139.133,192.168.139.134,192.168.139.135,192.168.139.150,127.0.0.1,kubernetes,kubernetes.default,kubernetes.default.svc,kubernetes.default.svc.cluster,kubernetes.default.svc.cluster.local \
 -profile=kubernetes \
 apiserver-csr.json | cfssljson -bare /etc/kubernetes/pki/apiserver

5.3 前置代理证书（aggregator）

1
2
3
4
5
6
7
8


# front-proxy CA + client
cfssl gencert -initca front-proxy-ca-csr.json | cfssljson -bare /etc/kubernetes/pki/front-proxy-ca
cfssl gencert \
 -ca=/etc/kubernetes/pki/front-proxy-ca.pem \
 -ca-key=/etc/kubernetes/pki/front-proxy-ca-key.pem \
 -config=ca-config.json \
 -profile=kubernetes front-proxy-client-csr.json | \
 cfssljson -bare /etc/kubernetes/pki/front-proxy-client

5.4 controller-manager / scheduler / admin / kube-proxy 证书

按角色签发，证书 CN 决定 K8s RBAC 里的身份（system:kube-controller-manager 等）：

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


# controller-manager
cfssl gencert -ca=/etc/kubernetes/pki/ca.pem \
 -ca-key=/etc/kubernetes/pki/ca-key.pem -config=ca-config.json \
 -profile=kubernetes manager-csr.json | \
 cfssljson -bare /etc/kubernetes/pki/controller-manager

# scheduler
cfssl gencert -ca=/etc/kubernetes/pki/ca.pem \
 -ca-key=/etc/kubernetes/pki/ca-key.pem -config=ca-config.json \
 -profile=kubernetes scheduler-csr.json | \
 cfssljson -bare /etc/kubernetes/pki/scheduler

# admin
cfssl gencert -ca=/etc/kubernetes/pki/ca.pem \
 -ca-key=/etc/kubernetes/pki/ca-key.pem -config=ca-config.json \
 -profile=kubernetes admin-csr.json | \
 cfssljson -bare /etc/kubernetes/pki/admin

# kube-proxy
cfssl gencert -ca=/etc/kubernetes/pki/ca.pem \
 -ca-key=/etc/kubernetes/pki/ca-key.pem -config=ca-config.json \
 -profile=kubernetes kube-proxy-csr.json | \
 cfssljson -bare /etc/kubernetes/pki/kube-proxy

5.5 SA（ServiceAccount）密钥对

1
2


openssl genrsa -out /etc/kubernetes/pki/sa.key 2048
openssl rsa -in /etc/kubernetes/pki/sa.key -pubout -out /etc/kubernetes/pki/sa.pub

5.6 同步证书到其他 master

1
2
3
4
5
6


for NODE in master2 master3; do
 ssh $NODE "mkdir -p /etc/kubernetes/pki /etc/etcd/ssl"
 for DIR in etcd/ssl kubernetes/pki; do
 scp -r /etc/$DIR/* $NODE:/etc/$DIR/
 done
done

六、生成 kubeconfig（每个组件一个身份）

kubeconfig 包含集群地址 + 用户证书 + 上下文：

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


KUBECONFIG_FILE=/etc/kubernetes/admin.kubeconfig
kubectl config set-cluster kubernetes \
 --certificate-authority=/etc/kubernetes/pki/ca.pem \
 --embed-certs=true --server=https://192.168.139.150:6443 \
 --kubeconfig=$KUBECONFIG_FILE

kubectl config set-credentials kubernetes-admin \
 --client-certificate=/etc/kubernetes/pki/admin.pem \
 --client-key=/etc/kubernetes/pki/admin-key.pem \
 --embed-certs=true \
 --kubeconfig=$KUBECONFIG_FILE

kubectl config set-context kubernetes-admin@kubernetes \
 --cluster=kubernetes --user=kubernetes-admin \
 --kubeconfig=$KUBECONFIG_FILE

kubectl config use-context kubernetes-admin@kubernetes --kubeconfig=$KUBECONFIG_FILE

controller-manager / scheduler / kube-proxy 各自生成一份 kubeconfig。

七、解压二进制到 /usr/local/bin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# K8s 组件（master + worker 都有）
cd /k8s/softs
tar -xf kubernetes-server-linux-amd64.tar.gz \
 --strip-components=3 -C /usr/local/bin \
 kubernetes/server/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy}

# etcd
tar -xf etcd-v3.5.11-linux-amd64.tar.gz
mv etcd-v3.5.11-linux-amd64/etcd /usr/local/bin/
mv etcd-v3.5.11-linux-amd64/etcdctl /usr/local/bin/
mv etcd-v3.5.11-linux-amd64/etcdutl /usr/local/bin/

同步到其他节点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# master 节点
for NODE in master2 master3; do
 scp /usr/local/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy} $NODE:/usr/local/bin/
 scp /usr/local/bin/etcd* $NODE:/usr/local/bin/
done

# worker 节点
for NODE in worker1 worker2; do
 scp /usr/local/bin/kube{let,-proxy} $NODE:/usr/local/bin/
done

八、systemd 单元文件

8.1 kube-apiserver.service

所有 master 节点都需要，注意 --advertise-address 每个 master 不同：

 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


[Unit]
Description=Kubernetes API Server
Documentation=https://github.com/kubernetes/kubernetes
After=network.target

[Service]
ExecStart=/usr/local/bin/kube-apiserver \
 --v=2 \
 --allow-privileged=true \
 --bind-address=0.0.0.0 \
 --secure-port=6443 \
 --advertise-address=192.168.139.133 \
 --service-cluster-ip-range=10.96.0.0/12,fd00:1111::/112 \
 --service-node-port-range=30000-32767 \
 --etcd-servers=https://192.168.139.133:2379,https://192.168.139.134:2379,https://192.168.139.135:2379 \
 --etcd-cafile=/etc/etcd/ssl/etcd-ca.pem \
 --etcd-certfile=/etc/etcd/ssl/etcd.pem \
 --etcd-keyfile=/etc/etcd/ssl/etcd-key.pem \
 --client-ca-file=/etc/kubernetes/pki/ca.pem \
 --tls-cert-file=/etc/kubernetes/pki/apiserver.pem \
 --tls-private-key-file=/etc/kubernetes/pki/apiserver-key.pem \
 --kubelet-client-certificate=/etc/kubernetes/pki/apiserver.pem \
 --kubelet-client-key=/etc/kubernetes/pki/apiserver-key.pem \
 --service-account-key-file=/etc/kubernetes/pki/sa.pub \
 --service-account-signing-key-file=/etc/kubernetes/pki/sa.key \
 --service-account-issuer=https://kubernetes.default.svc.cluster.local \
 --enable-admission-plugins=NamespaceLifecycle,LimitRanger,ServiceAccount,DefaultStorageClass,DefaultTolerationSeconds,NodeRestriction,ResourceQuota \
 --authorization-mode=Node,RBAC \
 --enable-bootstrap-token-auth=true \
 --requestheader-client-ca-file=/etc/kubernetes/pki/front-proxy-ca.pem \
 --proxy-client-cert-file=/etc/kubernetes/pki/front-proxy-client.pem \
 --proxy-client-key-file=/etc/kubernetes/pki/front-proxy-client-key.pem \
 --requestheader-allowed-names=aggregator \
 --requestheader-group-headers=X-Remote-Group \
 --requestheader-extra-headers-prefix=X-Remote-Extra- \
 --requestheader-username-headers=X-Remote-User \
 --enable-aggregator-routing=true
Restart=on-failure
RestartSec=10s
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

8.2 kube-controller-manager.service

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


[Unit]
Description=Kubernetes Controller Manager
Documentation=https://github.com/kubernetes/kubernetes
After=network.target

[Service]
ExecStart=/usr/local/bin/kube-controller-manager \
 --v=2 \
 --bind-address=0.0.0.0 \
 --root-ca-file=/etc/kubernetes/pki/ca.pem \
 --cluster-signing-cert-file=/etc/kubernetes/pki/ca.pem \
 --cluster-signing-key-file=/etc/kubernetes/pki/ca-key.pem \
 --service-account-private-key-file=/etc/kubernetes/pki/sa.key \
 --kubeconfig=/etc/kubernetes/controller-manager.kubeconfig \
 --leader-elect=true \
 --use-service-account-credentials=true
Restart=on-failure
RestartSec=10s
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

8.3 kube-scheduler.service

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


[Unit]
Description=Kubernetes Scheduler
Documentation=https://github.com/kubernetes/kubernetes
After=network.target

[Service]
ExecStart=/usr/local/bin/kube-scheduler \
 --v=2 \
 --bind-address=0.0.0.0 \
 --leader-elect=true \
 --kubeconfig=/etc/kubernetes/scheduler.kubeconfig
Restart=on-failure
RestartSec=10s
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

8.4 kubelet.service（所有 master + worker 节点）

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


[Unit]
Description=Kubernetes Kubelet
Documentation=https://github.com/kubernetes/kubernetes
After=network.target

[Service]
ExecStart=/usr/local/bin/kubelet \
 --v=2 \
 --bootstrap-kubeconfig=/etc/kubernetes/bootstrap-kubelet.kubeconfig \
 --kubeconfig=/etc/kubernetes/kubelet.kubeconfig \
 --config=/etc/kubernetes/kubelet-config.yaml \
 --cert-dir=/etc/kubernetes/pki \
 --hostname-override=<本节点主机名>
Restart=on-failure
RestartSec=10s
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

8.5 kube-proxy.service

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


[Unit]
Description=Kubernetes Kube-Proxy Server
Documentation=https://github.com/kubernetes/kubernetes
After=network.target

[Service]
ExecStart=/usr/local/bin/kube-proxy \
 --v=2 \
 --config=/etc/kubernetes/kube-proxy-config.yaml \
 --hostname-override=<本节点主机名>
Restart=on-failure
RestartSec=10s
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

九、启动顺序与验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 所有 master 节点
systemctl daemon-reload
systemctl enable --now kube-apiserver kube-controller-manager kube-scheduler kubelet kube-proxy
systemctl status kube-apiserver

# 验证（master1）
kubectl get componentstatuses
# NAME STATUS MESSAGE ERROR
# controller-manager Healthy ok
# scheduler Healthy ok
# etcd-0 Healthy {"health":"true"}

十、常见坑

证书 hostname 漏配：apiserver 报 “x509: certificate is not valid for any names”，重新签发并把 VIP、Service IP、k8s 域名都加进去
bootstrap token 过期：默认 24h，过期后 worker 无法 join，kubeadm token create --print-join-command 重新生成（kubeadm 部署）
etcd 启动后 apiserver 连不上：etcd 证书路径不对，配置里写 /etc/etcd/ssl/，但 cert 实际在 /etc/kubernetes/pki/etcd/，加软链
kubelet 起不来：bootstrap-kubelet.kubeconfig 不存在或 token 失效
kube-proxy 模式选错：默认 iptables，高并发场景（>5000 Service）改 IPVS 性能更好

十一、前置知识 / 下一步

前置：

K8s 架构概念（参考 2017-06-15《Kubernetes 入门》）
etcd 基本原理（参考 2020-09-15《etcd 集群部署》）
Linux 网络基础（iptables / IPVS / 网桥）

下一步：

etcd 集群部署（2020-09-15）—— K8s 数据层高可用
API Server 高可用（2021-03-15）—— Nginx 四层 + Keepalived VIP
K8s 集群插件（2021-09-15）—— CNI / CoreDNS / Metrics / Dashboard

参考资料

Kubernetes The Hard Way - Kelsey Hightower
Kubernetes 官方文档 - kubeadm 安装
cfssl 官方文档
Kubernetes 组件参数参考

Jenkins 镜像实战：JDK21 升级、Agent 集群、钉钉/企微通知、Kubernetes 动态 Agent 与流水线部署 Java/Golang/Vue

Sun, 15 Sep 2024 00:00:00 +0800

Jenkins 是 CI/CD 界的"老大哥"——2004 年从 Hudson 分支出来后，已经走了 20 年。2024 年 9 月它发布了基于 JDK21 的 LTS（2.504.x 系列），而 2024-09-24 正是 Jenkins 官方对 JDK11 镜像停止安全更新的日期。这篇文章不是"Jenkins 是什么"的科普文，而是把零散的实战笔记整理成"从镜像拉取到一条完整流水线"的路径：拉哪个镜像、Agent 怎么挂、钉钉/企微通知怎么接、Kubernetes 上的动态 Agent 怎么配、流水线部署 Java/Golang/Vue 项目分别怎么写。

阅读对象：需要从零搭一套 Jenkins CI/CD，或正在做 JDK8→JDK11→JDK21 升级的开发者、运维
覆盖范围：官方 LTS 镜像选择、Agent 节点（JNLP）、钉钉/企业微信 webhook 通知、Active Choices 级联参数、Generic Webhook Trigger 触发、SSH/Credentials 凭据、Kubernetes 动态 Agent（jnlp-slave）、自定义 sshpass/rsync Agent、流水线部署 Java/Golang/Vue 模板、常见排错

一、Jenkins 镜像选择：JDK8 / JDK11 / JDK21 LTS

Jenkins 官方镜像 jenkins/jenkins 有几个常用 tag，先把它们的关系理清楚：

Tag	含义	备注
`2.346.3-lts-jdk8`	JDK8 + Jenkins 2.346.3 LTS	2022 年主流选择，但 JDK8 已停止安全更新
`2.440.3-lts-jdk11`	JDK11 + Jenkins 2.440.3 LTS	2024 年过渡选择，2024-09-24 停止安全更新
`2.504.2-lts-jdk21`	JDK21 + Jenkins 2.504.2 LTS	当前推荐（LTS 路线）

When to use：JDK21 LTS（2.504.x 系列）已是新装 Jenkins 的默认推荐。JDK11 LTS 在 2024-09-24 之后不再收安全补丁——还在跑 JDK11 的同学需要规划升级。

1.1 最小启动：JDK8 老镜像

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


# 拉镜像
docker pull jenkins/jenkins:2.346.3-lts-jdk8

# 创建数据目录
mkdir -p /data/jenkins/home
chown -R 1000:1000 /data/jenkins/home

# 启动
docker run --name jenkins -d \
 -p 8090:8080 \
 -p 50000:50000 \
 -v /data/jenkins/apache-maven-3.8.6:/data/jenkins/apache-maven-3.8.6 \
 -v /data/jenkins/.nvm:/data/jenkins/.nvm \
 -v /data/jenkins/home:/var/jenkins_home \
 -v /etc/localtime:/etc/localtime \
 --restart=on-failure \
 jenkins/jenkins:2.346.3-lts-jdk8

坑 1：第一个启动慢是因为它要执行 init.groovy.d 下的初始化脚本，并下载默认插件。耐心等几分钟，初始密码可以通过 docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword 拿到。

1.2 JDK11 升级路径（已被 JDK21 取代）

如果已经在线上跑着 JDK8 或 JDK11，可以保留数据卷 jenkins_home，直接换镜像 tag 升级。

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


# docker-compose.yaml
version: '3'
services:
 jenkins:
 image: jenkins/jenkins:2.440.3-lts-jdk11
 container_name: jenkins11
 restart: always
 privileged: true
 environment:
 - TZ=Asia/Shanghai
 - JAVA_OPTS=-Duser.timezone=Asia/Shanghai
 ports:
 - "8091:8080"
 - "50001:50000"
 volumes:
 - "/var/run/docker.sock:/var/run/docker.sock" # 让 Jenkins 在容器内调 docker
 - "/usr/bin/docker:/usr/bin/docker"
 - "/home/docker/jenkins11/work:/var/jenkins_home"
 - "/usr/local/maven/apache-maven-3.9.3:/usr/local/maven/apache-maven-3.9.3"
 - "/etc/localtime:/etc/localtime:ro"

升级完后第一次启动会提示"java11 将在 2024-09-24 结束支持"——这是 Jenkins 内置的提示，不是 bug。

坑 2：挂 docker.sock 是为了在 Jenkins 容器内构建镜像（docker build）。但这等同于把宿主机的 docker 权限交给 Jenkins，多用户场景需要谨慎。

1.3 JDK21 升级路径（当前推荐）

1
2
3


docker pull jenkins/jenkins:2.504.2-lts-jdk21
docker tag jenkins/jenkins:2.504.2-lts-jdk21 <private-registry>/base/jenkins/jenkins:2.504.2-lts-jdk21
docker push <private-registry>/base/jenkins/jenkins:2.504.2-lts-jdk21

把启动脚本里的镜像 tag 换成 2.504.2-lts-jdk21 即可，数据卷 jenkins_home 完全兼容——Jenkins 2.504.x 会自动迁移配置。

坑 3：容器时区是对的，但 Jenkins 日志时间格式仍是 UTC。解决：在 系统管理 → 脚本命令行 执行 System.setProperty('org.apache.commons.jelly.tags.fmt.timeZone', 'Asia/Shanghai')，或启动时加 -e JAVA_OPTS=-Duser.timezone=Asia/Shanghai。新版本还支持在 用户列表 → admin → 设置 → 用户自定义时区 里改 UI 时区，但日志里那行仍是 UTC。

二、必备插件清单

Jenkins 的 90% 价值在插件。一份覆盖 90% 场景的最小集合：

插件	作用
`git` / `gitlab`	Git 源码拉取、GitLab 集成
`SSH plugin`	SSH 远程执行命令
`Publish Over SSH`	把构建产物 SCP 到远端并执行命令
`SSH Pipeline Steps` (`ssh-steps`)	流水线里用 `sshCommand` / `sshPut`
`Maven Integration`	构建 Maven 项目
`NodeJS`	构建 Node 项目
`Go`	构建 Golang 项目
`git-parameter`	构建时选择 Git 分支
`Active Choices` (`uno-choice`)	多级参数级联
`Generic Webhook Trigger`	接收 Git 服务的 webhook
`Qy Wechat Notification`	构建后发企业微信
`DingTalk`	构建后发钉钉
`Naginator`	构建失败后自动重试
`Environment Injector`	注入运行时环境变量
`Pipeline` / `Workflow Aggregator`	流水线基础
`Kubernetes`	在 K8s 上跑动态 Agent
`JDK Parameter`	多 JDK 项目里选择 jdk 版本
`Config File Provider`	集中管理 `settings.xml` / `npmrc` 等配置文件

坑 4：插件安装慢？Jenkins 4.x 之后插件源会从 updates.jenkins-ci.org 拉。国内网络下经常卡死，建议：

用 *.hpi 文件手动下载：https://updates.jenkins-ci.org/download/plugins/

或在 系统管理 → 插件管理 → 高级 里把 升级站点 换成国内镜像（如 https://mirror.tuna.tsinghua.edu.cn/jenkins/updates/）

三、钉钉 / 企业微信通知：3 行就能接

3.1 钉钉机器人

群设置 → 智能群助手 → 添加机器人 → 自定义
安全设置选"自定义关键词"或"加签"
拿到 webhook（形如 https://oapi.dingtalk.com/robot/send?access_token=xxxx）
Jenkins 安装 DingTalk 插件，在 Job 配置里填 webhook

curl 直接测试：

1
2
3


curl 'https://oapi.dingtalk.com/robot/send?access_token=<YOUR_TOKEN>' \
 -H 'Content-Type: application/json' \
 -d '{"msgtype":"markdown","markdown":{"title":"构建通知","text":"## ${JOB_NAME} 构建成功"}}'

3.2 企业微信机器人

群右键 → 群机器人 → 添加 → 选"群机器人"
拿到 webhook（形如 https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxx）
Jenkins 安装 Qy Wechat Notification 插件

1
2
3
4
5
6
7
8


curl "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<YOUR_KEY>" \
 -H "Content-Type: application/json" \
 -d '{
 "msgtype": "markdown",
 "markdown": {
 "content": "## ${JOB_NAME} 构建信息\n**构建ID**: ${BUILD_ID}\n**状态**: ${currentBuild.currentResult}\n[查看日志](${BUILD_URL}/console)"
 }
 }'

3.3 在 Pipeline 里推 commit 信息

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


sh '''
 git config --global log.date format:'%Y-%m-%d %H:%M:%S'
 commit_info=$(git log -1 --oneline --pretty=format:'%s by %an at %cd' --no-merges)
'''
def commitInfo = sh(script: "git log -1 --oneline --pretty=format:'%s by %an at %cd' --no-merges", returnStdout: true).trim()

httpRequest(
 url: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<YOUR_KEY>',
 httpMode: 'POST',
 contentType: 'APPLICATION_JSON',
 requestBody: """
 {"msgtype":"markdown","markdown":{"content":"<font color=\"warning\">**${env.JOB_NAME} 构建**</font>\n>提交：${commitInfo}\n>状态：${currentBuild.currentResult}\n[日志](${env.BUILD_URL}/console)"}}
 """
)

坑 5：把 webhook 凭据硬编码在脚本里？不要这样做。把 webhook 放进 Jenkins 凭据（Credentials）→ Secret text 里，再通过 withCredentials([string(credentialsId: 'wechat-webhook', variable: 'WEBHOOK')]) 引用。

四、Agent 集群：JNLP 节点 + K8s 动态 Agent

4.1 JNLP Agent（传统固定节点）

适合：物理机 / 虚拟机 / 容器化的固定 Agent。

前置：在 Agent 机器上装好 java、maven、git。

启动方式 A：java web 启动代理

1
2
3
4
5


nohup java -jar /usr/local/jenkins/agent.jar \
 -jnlpUrl http://<JENKINS_URL>/computer/<NODE_NAME>/jenkins-agent.jnlp \
 -secret <SECRET_FROM_JENKINS> \
 -workDir "/usr/local/jenkins/ws" \
 > nohup.log &

启动方式 B：Kubernetes 上的 JNLP 静态 Agent

1
2


# jenkins-master 上的 SSH remote hosts / Publish over SSH
# 用 Publish Over SSH 把 jar 推到远端, 然后 java -jar 启动

4.2 Kubernetes 动态 Agent（推荐）

Jenkins 装 Kubernetes 插件，每次 Job 触发时在 K8s 里拉一个临时 Pod，构建完销毁。

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


pipeline {
 agent {
 kubernetes {
 cloud 'k8s' # 配在 系统管理 → 节点管理 → Configure Clouds
 inheritFrom 'jnlp-slave' # 复用 Pod Template
 namespace 'kube-ops'
 }
 }
 stages {
 stage('build') {
 steps {
 container('jnlp') {
 sh 'mvn clean package -P prod'
 }
 }
 }
 }
}

前置：

制作 Jenkins 连接 K8s 的证书（K8s ~/.kube/config 的 certificate-authority-data / client-certificate-data / client-key-data 三个字段，base64 解码后保存）
把 kube-ca.crt + kube-cert.pfx 配到 Jenkins 凭据里
创建一个 jnlp-slave Pod Template（基础镜像 jenkins/inbound-agent:latest-jdk21）

K8s 集群配置：

1
2


Kubernetes Cloud URL: https://<K8S_API_SERVER>:6443
Kubernetes Cloud Credentials: <上面做的 pfx 凭据>

坑 6：Pod 启动失败？用 kubectl logs -f --tail=10 查看 Jenkins 动态创建的 Pod。80% 的情况是 jnlp-slave Pod Template 里的镜像拉不到（私有仓库没配 imagePullSecrets）或 Jenkins 容器内没装 rsync。

4.3 自定义 Agent 镜像（装 rsync + sshpass）

jenkins/inbound-agent 基础镜像不带 rsync 和 sshpass，但流水线里经常要用。两种方式：

方式 A：临时容器安装 + commit

1
2
3
4
5
6
7
8


docker run -u root -it --name jenkins-agent-temp \
 jenkins/inbound-agent:latest-jdk21 /bin/bash
# 容器内
apt update && apt install -y rsync sshpass
exit
# 宿主机
docker commit jenkins-agent-temp <private-registry>/base/jenkins/inbound-agent:latest-jdk21-rsync
docker push <private-registry>/base/jenkins/inbound-agent:latest-jdk21-rsync

方式 B：Dockerfile（推荐，可追溯）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


ARG version=latest-jdk21
FROM jenkins/inbound-agent:$version
ARG version
LABEL Description="Custom Jenkins Agent with rsync and sshpass" Vendor="某安全公司" Version="$version"
ARG user=jenkins
USER root
RUN apt-get update && \
 apt-get install -y rsync sshpass && \
 rm -rf /var/lib/apt/lists/*
USER ${user}
ENTRYPOINT ["/usr/local/bin/jenkins-agent"]

1
2


docker build -t <private-registry>/base/jenkins/inbound-agent:latest-jdk21-rsync .
docker push <private-registry>/base/jenkins/inbound-agent:latest-jdk21-rsync

五、流水线：声明式 vs 脚本式

5.1 声明式（推荐）

 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
47
48
49
50
51
52
53
54
55


pipeline {
 agent any
 options {
 buildDiscarder logRotator(daysToKeepStr: '10', numToKeepStr: '10')
 timeout(time: 30, unit: 'MINUTES')
 }
 parameters {
 choice(name: 'profiles', choices: ['dev', 'test', 'prod'], description: '请选择构建环境')
 }
 triggers {
 GenericTrigger(
 genericRequestVariables: [[key: 'profile', regexpFilter: '$']],
 token: 'test'
 )
 }
 stages {
 stage('git checkout') {
 steps {
 git branch: 'master', credentialsId: 'gitlab-cred', url: 'http://<GITLAB>/<your-org>/gdsTmqtt.git'
 }
 }
 stage('build') {
 steps {
 sh 'mvn clean package -P prod -DskipTests'
 }
 }
 stage('publish') {
 steps {
 sshPublisher(
 publishers: [sshPublisherDesc(
 configName: 'prod-server',
 transfers: [sshTransfer(
 cleanRemote: false,
 execCommand: '''
 mkdir -p /home/project/safety/gdsTmq/jar
 docker rm -f gdsTomq
 mv /home/tmp/safety-gdsTomq/*.jar /home/project/safety/gdsTmq/jar/
 docker run -d --restart=always --net=host --name=gdsTomq \
 -v /home/project/safety/gdsTmq/jar:/jar \
 <private-registry>/base/jdk:8u381-2 \
 java -jar /jar/gds-0.0.1-SNAPSHOT.jar
 ''',
 remoteDirectory: '/home/tmp/safety-gdsTomq',
 sourceFiles: 'target/gds-0.0.1-SNAPSHOT.jar'
 )]
 )]
 )
 }
 }
 }
 post {
 success { echo 'deploy success' }
 failure { echo 'deploy failed' }
 }
}

5.2 脚本式（灵活但难维护）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


node {
 stage('Remote SSH') {
 def remote = [:]
 remote.name = 'test'
 remote.host = '<INTERNAL_HOST>'
 remote.user = 'root'
 remote.password = '<REDACTED>'
 remote.allowAnyHosts = true
 sshCommand remote: remote, command: "ls -lrt"
 }
}

坑 7：声明式是 2017 年之后的官方推荐。新项目用声明式；老项目如果是脚本式，不要一次性重写，逐步迁移。

六、Active Choices：多级参数级联

真实场景：先选节点（master/dev/联创），再选项目（不同节点不同项目），再选主机（不同节点不同主机），再选分支（不同项目不同分支）。

步骤：

Job 选"参数化构建"
加 Active Choices Parameter，name=agent，Choice Type=Single
Script：

1

return ["master", "dev", "liangchuang"]

加 Active Choices Reactive Parameter，name=project，Referenced parameters=agent

1
2
3
4
5


if (agent.equals("master")) {
 return ["safetyBackend", "safetyAppBackend", "safetyFrontend", "safetyAuth", "safetyAppH5", "safetyGds"]
} else if (agent.equals("dev")) {
 return ["safetyBackend", "safetyAuth"]
}

同样做 host（referenced=agent）、branch（referenced=project）

坑 8：低版本 Jenkins（2.346.x）装 Active Choices 时提示依赖缺失，要先装 script-security 1.x 版本，再装 uno-choice。

七、流水线部署三类项目：Java / Golang / Vue

7.1 部署 Java 项目

参考第五章 5.1 的完整 pipeline。核心点：

mvn clean package -P <profile> 打 jar
sshPublisher 把 jar 传到目标机器
远端 docker rm -f <container> + docker run -d 重启

钉钉/企微通知 + commit 信息：

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


stage('notify') {
 steps {
 sh '''
 git config --global log.date format:'%Y-%m-%d %H:%M:%S'
 commit_info=$(git log -1 --oneline --pretty=format:'%s by %an at %cd' --no-merges)
 '''
 script {
 def commitInfo = sh(script: "git log -1 --oneline --pretty=format:'%s by %an at %cd' --no-merges", returnStdout: true).trim()
 httpRequest(
 url: "<WEBHOOK_URL>",
 httpMode: 'POST',
 contentType: 'APPLICATION_JSON',
 requestBody: "{\"msgtype\":\"markdown\",\"markdown\":{\"content\":\"**${env.JOB_NAME} 构建成功**\\n>提交：${commitInfo}\"}}"
 )
 }
 }
}

7.2 部署 Golang 项目

Golang 项目的特殊点：Go 安装路径、GOPATH 设置、交叉编译。

 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


pipeline {
 agent any
 environment {
 GOPATH = "${JENKINS_HOME}/golang_workspace"
 GOPROXY = "https://goproxy.cn"
 }
 stages {
 stage('build') {
 steps {
 sh '''
 export PATH=$PATH:$GOPATH/bin
 mkdir -p $GOPATH
 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o main main.go
 '''
 }
 }
 stage('publish') {
 steps {
 sshCommand remote: [...], command: '''
 rm -f /home/project/tailings/main
 mv /home/docker/jenkins/data/workspace/tailings-backend/main /home/project/tailings/
 chmod +x /home/project/tailings/main
 docker-compose -f /home/docker-compose.yml restart tailings-backend
 '''
 }
 }
 }
}

坑 9：Jenkins 装 Go 插件后，Go 路径会被装到 $JENKINS_HOME/tools/org.jenkinsci.plugins.golang.GolangInstallation/go/<version>/。如果手动 tar -C 解压到 /home/docker/jenkins/data/go/，路径对不上会找不到——解决方法是用 tar -C 时直接建 go1.21.5 子目录，让最终路径是 /home/docker/jenkins/data/go/go1.21.5/。

7.3 部署 Vue 项目

Vue 项目用 npm 构建，产物在 dist/：

 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


pipeline {
 agent any
 tools {
 nodejs 'node14.17.3' # 在 全局工具配置 里先加 NodeJS 安装
 }
 stages {
 stage('build') {
 steps {
 sh '''
 npx browserslist@latest --update-db
 npm install
 npm run build:test
 cd dist
 tar -zcvf dist.tar.gz *
 '''
 }
 }
 stage('publish') {
 steps {
 sshPublisher(
 publishers: [sshPublisherDesc(
 configName: 'frontend-server',
 transfers: [sshTransfer(
 sourceFiles: 'dist/dist.tar.gz',
 removePrefix: 'dist/',
 remoteDirectory: '/project/frontend/dist',
 execCommand: '''
 cd /home/project/frontend/dist
 shopt -s extglob
 rm -rf !(dist.tar.gz)
 tar -zxvf dist.tar.gz -C ./
 rm -rf dist.tar.gz
 cd /home
 docker-compose restart frontend
 '''
 )]
 )]
 )
 }
 }
 }
}

坑 10：docker-compose restart frontend 只重启容器，不会重新读 docker-compose.yaml 的端口/环境变量。改了 compose 文件必须 docker-compose up -d。

八、定时构建 + 自动合并代码

轮询 SCM（在 Job 的"构建触发器"里勾选"轮询 SCM"）：

1
2
3
4
5


TZ=Asia/Shanghai
0 9,13 * * * # 每天 9 点和 13 点
0 14,20 * * * # 每天 14 点和 20 点
*/5 16-17 * * * # 每天 16-17 点，每 5 分钟
H/5 * * * * # 每 5 分钟（H 是 hash 分散）

坑 11：5 个星分别是"分时日月周"，别写反。H/5 比 */5 好——Jenkins 会在集群内做 hash 分散，多个 Job 不会同时触发。

自动合并代码（在 SCM 的 Additional Behaviours 加）：

Clean before checkout（构建前清空工作区）
Prune stale remote-tracking branches（同步远程分支）
Merge before build（构建前 merge 目标分支）

坑 12：Name of repository 一定要写 origin，否则 Merge before build 报 Could not find remote ref。

九、常见排错

9.1 “Waiting for Jenkins to finish collecting data” 等待时间长

Jenkins 通过 Maven 构建 Java 项目后，会做 指纹验证——给每个 jar 算一个 SHA-1，写入数据库。Java 项目越大、依赖越多，等待时间越长。

解决：关掉指纹验证 → Job 配置 → 构建环境 → 勾选 “Disable deferred wipeout and improve performance”。

9.2 中文乱码

启动加：

1
2


LANG=zh_CN.UTF-8
JAVA_OPTS=-Dsun.jnu.encoding=UTF-8 -Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai

9.3 IllegalArgumentException: No enum constant io.jenkins.plugins.localization_zh_cn.UserCommunityProperty.ShowConditions

中文插件版本不兼容。解决：删除中文插件 → 重装匹配 Jenkins 版本的 localization-zh-cn 插件 → 重启。

9.4 Publish Over SSH 连接超时

检查：

~/.ssh/known_hosts 里有没有目标机器的公钥（StrictHostKeyChecking=no 可绕过）
远端 sshd_config 是否允许 PasswordAuthentication yes
网络是否可达（telnet <INTERNAL_HOST> 22）

9.5 流水线里 Git 拉取失败

1
2
3
4
5


git branch: 'master', 
 credentialsId: 'gitlab-cred', 
 url: 'http://<INTERNAL_HOST>:13000/<your-org>/gdsTmqtt.git',
 // 新版要加 poll: false 否则每分钟检查一次
 poll: false

9.6 Kubernetes 插件连接集群失败

1
2
3
4


# 查看 Jenkins 创建的 agent pod 日志
kubectl logs -f --tail=10 \
 $(kubectl get pods -n jenkins | grep <job-name> | awk '{print $1}' | head -1) \
 -n jenkins

80% 是这几个原因：

证书过期（K8s 证书默认 1 年）
镜像拉取失败（私有仓库没配 imagePullSecrets）
jnlp-slave Pod Template 里 command / args 写错

十、写在最后

Jenkins 的"全"是把双刃剑——插件生态丰富意味着学习曲线陡。从 2004 年走到 2024 年，Jenkins 仍是大量企业 CI/CD 的"事实标准"（不是"应该"，是"事实上"）。如果你正在做新项目选型，可以看看 GitHub Actions（云原生、YAML 优先）或 Drone（容器化、声明式），但对存量 Jenkins 集群，升级到 JDK21 LTS、关闭指纹验证、清理无用插件，就能让 80% 的项目跑得更稳。

下一步建议：

Jenkins on K8s 的完整部署：Jenkins Master 也跑在 K8s 里 + dynamic Agent
Jenkins Configuration as Code (JCasC)：用 jenkins.yaml 管理所有插件、凭据、节点
Pipeline as Code：把 Jenkinsfile 放进 Git 仓库，Job 通过 Multibranch Pipeline 自动发现

2024+ 视角补充

本文写于 2024-09，2025-2026 期间 Jenkins 关键演进：

Jenkins 2.516.x LTS（2025-04 起）：JDK 17 / 21 双轨 LTS，JDK 11 LTS 已于 2024-09-24 停止安全补丁——本文内容完全契合
Jenkins Evergreen 持续完善：CD-as-a-Service 模式，与 Kubernetes Operator 深度集成
Jenkins on K8s Operator（jenkinsci/kubernetes-operator）：Jenkins Master 本身也跑在 K8s 上，生产级高可用 + 自动备份
Pipeline as Code 主导：Jenkinsfile + Multibranch Pipeline 成为 2025+ 事实标准，老的 FreeStyle Job 模式逐步淘汰
AI 辅助插件（2025+）：Jenkins 接入 LLM 做"日志摘要 + 失败原因诊断"，但仅作为辅助——核心编排仍是声明式流水线

实战建议（2025-2026 视角）：Jenkins 仍是 Java 后端 CI/CD 事实标准；GitHub Actions / GitLab CI 在新项目是强力竞争者，但存量 Jenkins 集群升级到 JDK 21 LTS + 跑在 K8s 上仍是 2025+ 主路线。

参考资料

Jenkins 官方文档：https://www.jenkins.io/zh/doc/
Jenkins 官方镜像：https://hub.docker.com/r/jenkins/jenkins
Jenkins K8s Operator：https://github.com/jenkinsci/kubernetes-operator
Kubernetes 插件：https://plugins.jenkins.io/kubernetes
Active Choices 插件：https://plugins.jenkins.io/uno-choice
Generic Webhook Trigger：https://plugins.jenkins.io/generic-webhook-trigger
钉钉自定义机器人：https://open.dingtalk.com/document/orgapp/custom-robot-access
企业微信群机器人：https://developer.work.weixin.qq.com/document/path/91770

K8s 生产二进制集群前置：节点规划与 Linux 系统调优

Fri, 15 Dec 2023 00:00:00 +0800

写在前面

在 Kubernetes 1.6（2017 年）之前，社区主流的"高可用生产集群"基本是 3 master + N worker 手工二进制部署路线——比起 kubeadmin/kubeadm，手工二进制能完全掌控每个组件的 flag、证书路径和 systemd 单元，是国内大厂 2018-2022 年生产环境的标配方案。

本文是整个 K8s 二进制部署系列的前置篇，只讲集群起步：网络规划、服务器角色划分、Ubuntu 22.04 系统基础优化、IPVS/iptables 内核参数准备。不涉及任何 K8s 组件安装。

适用版本：Kubernetes 1.28.5 / etcd 3.5.11 / Ubuntu 22.04 server 集群规模：3 master（etcd + controlplane + nginx/keepalived）+ 10 worker

1. 集群网络与节点规划

1.1 角色划分

角色	数量	部署组件
master	3	etcd、kube-apiserver、kube-controller-manager、kube-scheduler、kubelet、kube-proxy、nginx、keepalived
worker	N	kubelet、kube-proxy、容器运行时
VIP	2	一个内网用，一个公网用，keepalived 漂移

1.2 IP 与 VIP 段（示例拓扑）

网段	用途	说明
`<node-network>`	节点操作系统网段	物理网络，所有节点 IP 都在此
`10.96.0.0/12`	Service 网段	kube-apiserver 默认 `--service-cluster-ip-range`
`10.96.0.10`	CoreDNS Service IP	kube-dns 固定 IP
`172.218.0.0/12`	Pod 网络	kube-controller-manager 的 `--cluster-cidr`
`<vip-internal>`	内网 VIP	漂移在 master1 / master2
`<vip-public>`	公网映射 VIP	漂移在 master1 / master2

Service 段、Pod 段在生产中可以按需调整，前提是所有节点路由可达。

1.3 NodePort 端口范围

K8s 默认 Service NodePort 范围是 30000-32767，如果需要在前面用 Nginx 4 层反代 NodePort，必须在 kube-apiserver 启动参数里显式声明：

1

--service-node-port-range=30000-32767

修改 /etc/systemd/system/kube-apiserver.service 后：

1
2


systemctl daemon-reload
systemctl restart kube-apiserver.service

1.4 主机名与 hosts

1
2
3
4


# 三个 master 设置 hostname
hostnamectl set-hostname master1 # 内网示例：<node-ip> 节点
hostnamectl set-hostname master2
hostnamectl set-hostname master3

所有节点配置 /etc/hosts（内网 IP 替换为实际值）：

1
2
3
4
5
6
7


cat << "EOF" >> /etc/hosts
<node-ip> master1
<node-ip> master2
<node-ip> master3
<node-ip> worker1
<node-ip> worker2
EOF

注意：内网 IP 已用占位符 <node-ip> 替代；实际操作时换成你集群的真实 IP。

2. 安装文件清单

在 master1 上准备好所有需要分发的二进制包（典型命名）：

文件	用途
`docker-24.0.7.tgz`	Docker 静态二进制包
`cri-dockerd-0.3.9.amd64.tgz`	cri-dockerd（K8s 1.24+ 不再内置 dockershim）
`nginx-1.24.0.tar.gz`	nginx 源码（编译 `--with-stream`）
`keepalived-2.2.8.tar.gz`	keepalived 源码
`etcd-v3.5.11-linux-amd64.tar.gz`	etcd 二进制
`kubernetes-server-linux-amd64.tar.gz`	K8s 1.28.5 服务端二进制
`cfssl_1.6.4_linux_amd64`	证书签发工具
`cfssljson_1.6.4_linux_amd64`	证书 JSON 化工具
`cfssl-certinfo_1.6.4_linux_amd64`	证书查看工具
`helm-v3.13.3-linux-amd64.tar.gz`	Helm 包管理
`coredns-1.29.0.tgz`	CoreDNS chart（DNS 插件）

3. 目录约定

每台机器统一下列目录结构，方便后面所有组件统一路径：

 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


# 系统服务目录
mkdir -p /etc/systemd/system

# 二进制目录
mkdir -p /usr/local/bin

# 所有节点安装包路径
mkdir -p /data/softs

# 所有节点 k8s 配置目录
mkdir -p /data/k8scnf

# 所有节点的 k8s 证书目录
mkdir -p /etc/kubernetes/pki

# 所有节点 k8s 运行目录
mkdir -p /etc/kubernetes/manifests/
mkdir -p /etc/systemd/system/kubelet.service.d
mkdir -p /var/lib/kubelet
mkdir -p /var/log/kubernetes

# 所有节点 docker 配置目录
mkdir -p /etc/docker

# 所有 master etcd 证书目录
mkdir -p /etc/etcd/ssl

# master1, master2 的 nginx 目录
mkdir -p /usr/local/nginx/conf/{conf.d,stream}
mkdir -p /usr/local/keepalived/conf

4. 节点免密登录（master1 推送前置）

master1 上一键推送 SSH 公钥到其他节点（密码用占位符）：

1
2
3
4
5
6


apt install -y sshpass
ssh-keygen -f /root/.ssh/id_rsa -P ''

for HOST in master2 master3 worker1 worker2 worker3 worker4 worker5 worker6 worker7 worker8 worker9; do \
 sshpass -p "{{SSH_PASSWORD}}" ssh-copy-id -o StrictHostKeyChecking=no $HOST; \
done

非 22 端口的节点：

1

ssh-copy-id -i ~/.ssh/id_rsa.pub "-p 10022 user@server"

文件批量推送到其他 master：

1

for HOST in master2 master3; do scp -r /data/softs $HOST:/data; done

5. Ubuntu 22.04 源切换

为了避免 apt install 卡顿，所有节点切到清华源（或其他国内源）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


mv /etc/apt/sources.list /etc/apt/sources.listbak

cat > /etc/apt/sources.list << "EOF"
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb http://security.ubuntu.com/ubuntu/ jammy-security main restricted universe multiverse
EOF

apt update

6. 系统基础优化

6.1 禁用 swap

K8s 1.20+ 仍要求关闭 swap（kubelet 默认 failSwapOn: true）：

1
2
3
4


free -m
swapoff -a
sed -ri 's/.*swap.*/#&/' /etc/fstab
cat /etc/fstab

6.2 关闭防火墙

1
2
3


sudo systemctl stop ufw
sudo systemctl disable ufw
systemctl status ufw # 状态应为 inactive (dead)

6.3 关闭 systemd-resolved（关键）

Ubuntu 22.04 默认的 systemd-resolved 占用 53 端口，导致 CoreDNS 装不上：

1
2
3
4
5


sudo apt install -y unbound
sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved
sudo rm -rf /etc/resolv.conf
sudo touch /etc/resolv.conf

6.4 时间同步

1
2
3
4
5
6
7
8
9


timedatectl status # System clock synchronized 必须是 yes
timedatectl set-timezone Asia/Shanghai
apt install -y ntpdate
ntpdate time1.aliyun.com

# 定时同步
crontab -e
*/5 * * * * ntpdate time1.aliyun.com
crontab -l

常见报错：Waiting for cache lock: Could not get lock /var/lib/dpkg/lock-frontend 解决：用 lsof /var/lib/dpkg/lock-frontend 查到占用 PID 后 kill -9 杀掉。

6.5 ulimit 与文件描述符

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


ulimit -SHn 65535

cat >> /etc/security/limits.conf << "EOF"
* soft nofile 655360
* hard nofile 131072
* soft nproc 655350
* hard nproc 655350
* soft memlock unlimited
* hard memlock unlimited
EOF

6.6 内核升级

K8s 1.28 要求内核 ≥ 4.18，Ubuntu 22.04 默认 5.15 满足，无需额外升级。

1
2


uname -r
# 5.15.0-91-generic 满足

7. IPVS 与内核网络参数

K8s kube-proxy 的 IPVS 模式比 iptables 模式在大规模集群下性能更好：

7.1 安装 IPVS

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


apt install -y ipvsadm ipset sysstat conntrack

cat >> /etc/modules-load.d/ipvs.conf << "EOF"
ip_vs
ip_vs_rr
ip_vs_wrr
ip_vs_sh
nf_conntrack
ip_tables
ip_set
xt_set
ipt_set
ipt_rpfilter
ipt_REJECT
ipip
EOF

systemctl restart systemd-modules-load.service
lsmod | grep -e ip_vs -e nf_conntrack

7.2 sysctl 优化

 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


cat << "EOF" > /etc/sysctl.d/k8s.conf
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-iptables = 1
fs.may_detach_mounts = 1
vm.overcommit_memory = 1
vm.panic_on_oom = 0
fs.inotify.max_user_watches = 89100
fs.file-max = 52706963
fs.nr_open = 52706963
net.netfilter.nf_conntrack_max = 2310720

net.ipv4.tcp_keepalive_time = 600
net.ipv4.tcp_keepalive_probes = 3
net.ipv4.tcp_keepalive_intvl = 15
net.ipv4.tcp_max_tw_buckets = 36000
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_max_orphans = 327680
net.ipv4.tcp_orphan_retries = 3
net.ipv4.tcp_syncookies = 1
net.ipv4.tcp_max_syn_backlog = 16384
net.ipv4.ip_conntrack_max = 65536
net.ipv4.tcp_timestamps = 0
net.core.somaxconn = 16384
EOF

sysctl --system

8. 排错速查

现象	原因	解决
`apt` 卡 `dpkg lock-frontend`	后台 unattended-upgrade 占用	`lsof /var/lib/dpkg/lock-frontend` → `kill -9 PID`
CoreDNS Pod 一直 `CrashLoopBackOff`	systemd-resolved 占用 53	关闭 systemd-resolved，见 6.3
kubelet 启动失败 `failSwapOn`	swap 未关	`swapoff -a` + `/etc/fstab` 注释
NodePort 配 80 端口启动失败	不在 30000-32767 范围	kube-apiserver 加 `--service-node-port-range`
节点 `NotReady`	路由转发未开	`net.ipv4.ip_forward = 1`

9. 小结

集群前置看似都是"复制粘贴"的体力活，但每一步都是后面所有组件能起来的前提。最容易踩的坑是：

systemd-resolved 没关 → CoreDNS 起不来
swap 没禁 → kubelet 直接 failSwapOn 拒绝启动
防火墙没关 → 跨节点 Service 不通
时间不同步 → 证书签名失败、etcd 集群脑裂

下一步：容器运行时：Docker + cri-dockerd 二进制部署实战。

前置知识 / 下一步

前置：了解 Linux 基础（systemd、apt、sysctl）
本篇：所有 master/worker 节点一致的系统基线
下一步：在所有节点上部署容器运行时（Docker 24 + cri-dockerd）

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 集群管理：升级 / 节点隔离 / 常用 API 与排错清单

Wed, 15 Dec 2021 00:00:00 +0800

写于 2021-12，背景：K8s 1.23 GA，1.24 即将引入对 dockershim 移除。本文聚焦"集群日常运维"——升级、节点隔离、API 速查与排错清单。

一、kubectl 命令速查

1.1 资源操作

 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


# 查看（-o wide 显示节点，-A 所有 namespace）
kubectl get all -o wide -A
kubectl get pods -n test
kubectl get nodes -o wide

# 描述（看详细事件）
kubectl describe pod <pod-name> -n <ns>
kubectl describe node <node-name>

# 日志
kubectl logs -f <pod-name> -n <ns>
kubectl logs -f <pod-name> -c <container-name> -n <ns> # 多容器 Pod
kubectl logs --previous <pod-name> -n <ns> # 上一个崩溃实例

# 进入容器
kubectl exec -it <pod-name> -n <ns> -- sh
kubectl exec -it <pod-name> -c <container> -n <ns> -- sh

# 删除
kubectl delete pod <pod-name> -n <ns>
kubectl delete -f deployment.yaml
kubectl delete ns <ns-name>

# 强制删除卡 Terminating 的 Pod
kubectl delete pod <pod-name> -n <ns> --grace-period=0 --force

# 编辑（直接改集群里的配置）
kubectl edit deployment <name> -n <ns>
kubectl edit cm <configmap> -n <ns>

# apply / replace
kubectl apply -f deployment.yaml
kubectl replace -f deployment.yaml --force

1.2 排错三剑客

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


# describe：看 Event，最常用
kubectl describe pod <pod> -n <ns>
# 关键信息：
# Events:
# Type Reason Age From Message
# ---- ------ ---- ---- -------
# Normal Scheduled 60s default-scheduler Successfully assigned ...
# Normal Pulling 58s kubelet Pulling image "nginx:1.25"
# Warning Failed 30s kubelet Failed to pull image: ... timeout

# logs：看容器内输出
kubectl logs -f <pod> -n <ns>
kubectl logs --previous <pod> -n <ns> # 上一个实例

# exec：进容器内部
kubectl exec -it <pod> -n <ns> -- sh

二、版本升级

重要原则：K8s 一年发 4 个版本（1.24+），生产不要追新；只升补丁版本（z 版本）几乎零风险，升次要版本（y 版本）要谨慎。

2.1 升级前准备

检查项	命令
当前版本	`kubectl version`
节点数	`kubectl get nodes`
是否有运行中的 workload	`kubectl get pods -A`
备份 etcd	`etcdctl snapshot save /tmp/etcd.db`
备份 /etc/kubernetes	`cp -r /etc/kubernetes /etc/kubernetes.bak`
备份证书	`cp -r /etc/kubernetes/pki /etc/kubernetes/pki.bak`

2.2 升级流程（小版本，如 1.28.5 → 1.28.8）

步骤：

升级 master 节点（先升级第一个，验证后再升级其他）
升级 worker 节点（一次一个）
验证

master1 操作：

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


# 1. 备份
mkdir -p /usr/local/bin/bak
mv /usr/local/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy} /usr/local/bin/bak

# 2. 下载新包
wget https://dl.k8s.io/v1.28.8/kubernetes-server-linux-amd64.tar.gz
# （生产环境建议从内网文件服务器拉取）

# 3. 解压到 /usr/local/bin
tar -xf kubernetes-server-linux-amd64.tar.gz \
 --strip-components=3 -C /usr/local/bin \
 kubernetes/server/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy}

# 4. 重启组件
systemctl restart kube-apiserver.service
systemctl restart kube-controller-manager.service
systemctl restart kube-scheduler.service
systemctl restart kubelet.service
systemctl restart kube-proxy.service

# 5. 验证
kubectl version
kubectl get nodes

其他 master 节点（master2 / master3）：

1
2
3
4
5
6
7


# 一键批量升级
for NODE in master2 master3; do
 echo "===== $NODE ====="
 ssh $NODE "mkdir -p /usr/local/bin/bak && mv /usr/local/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy} /usr/local/bin/bak"
 scp /usr/local/bin/kube{let,ctl,-apiserver,-controller-manager,-scheduler,-proxy} $NODE:/usr/local/bin/
 ssh $NODE "systemctl restart kube-apiserver kube-controller-manager kube-scheduler kubelet kube-proxy"
done

worker 节点：

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


# worker 只跑 kubelet + kube-proxy
for NODE in worker1 worker2 worker3; do
 echo "===== $NODE ====="
 # 先 cordon + drain（见下节）
 kubectl cordon $NODE
 kubectl drain $NODE --delete-local-data --ignore-daemonsets --force
 
 # 升级
 ssh $NODE "mkdir -p /usr/local/bin/bak && mv /usr/local/bin/kube{let,-proxy} /usr/local/bin/bak"
 scp /usr/local/bin/kube{let,-proxy} $NODE:/usr/local/bin/
 ssh $NODE "systemctl restart kubelet kube-proxy"
 
 # 验证 + uncordon
 sleep 30
 kubectl uncordon $NODE
done

2.3 升级验证

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


# 所有节点版本一致
kubectl get nodes
# NAME STATUS ROLES AGE VERSION
# master1 Ready control-plane 50d v1.28.8
# master2 Ready control-plane 50d v1.28.8
# master3 Ready control-plane 50d v1.28.8
# worker1 Ready <none> 30d v1.28.8
# worker2 Ready <none> 30d v1.28.8

# 集群健康
kubectl get cs
kubectl get pods -A | grep -v Running

三、节点隔离：cordon / drain / uncordon

K8s 提供 3 个状态机操作：

命令	作用	是否驱逐 Pod
`kubectl cordon <node>`	标记节点 unschedulable	否
`kubectl drain <node>`	cordon + 驱逐所有 Pod	是
`kubectl uncordon <node>`	恢复 schedulable	否

3.1 维护前的标准操作

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


# 1. cordon：禁止新 Pod 调度上来
kubectl cordon master1
# node/master1 cordoned

# 2. drain：驱逐现有 Pod
kubectl drain master1 --delete-local-data --ignore-daemonsets --force
# --delete-local-data：删除带 emptyDir 的 Pod
# --ignore-daemonsets：忽略 DaemonSet（kube-proxy / calico 不能被驱逐）
# --force：强制驱逐没有 PDB 保护的 Pod

# 3. 维护：升级内核 / 改网络 / 重启 etcd
...

# 4. uncordon：恢复
kubectl uncordon master1
# node/master1 uncordoned

3.2 查看节点上的所有 Pod

1
2
3
4
5
6
7


# 某个节点上所有 Pod
kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=worker2

# 批量删除（驱逐后用）
kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=worker2 | \
 grep -v "kube-system" | awk '{print $1,$2}' | \
 xargs -n2 kubectl delete pod -n

四、强制删除卡住的 Pod

症状：kubectl delete pod xxx 后 Pod 一直 Terminating（>5 分钟）。

原因：

Pod 里有容器没响应 SIGTERM
Pod 有 finalizer 卡住
kubelet 与 apiserver 通信异常

解决：

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


# 强制删除（跳过 graceful period）
kubectl delete pod <pod> -n <ns> --grace-period=0 --force

# 还是卡？看 finalizer
kubectl get pod <pod> -n <ns> -o yaml | grep finalizers

# 移除 finalizer（必须先 kubectl edit）
kubectl edit pod <pod> -n <ns>
# 删除 metadata.finalizers 字段，保存

# 再删
kubectl delete pod <pod> -n <ns> --force --grace-period=0

五、备份与恢复

5.1 etcd 备份

1
2
3
4
5
6
7
8
9


# 在每个 etcd 节点执行（或一个能访问所有 etcd 的节点）
ETCDCTL_API=3 etcdctl snapshot save /tmp/etcd-snapshot-$(date +%Y%m%d).db \
 --endpoints=https://127.0.0.1:2379 \
 --cacert=/etc/etcd/ssl/etcd-ca.pem \
 --cert=/etc/etcd/ssl/etcd.pem \
 --key=/etc/etcd/ssl/etcd-key.pem

# 验证
etcdctl snapshot status /tmp/etcd-snapshot-20231215.db --write-out=table

定时备份（crontab）：

1

0 2 * * * /usr/local/bin/etcd-backup.sh >> /var/log/etcd-backup.log 2>&1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


#!/bin/bash
# /usr/local/bin/etcd-backup.sh
BACKUP_DIR=/var/backups/etcd
mkdir -p $BACKUP_DIR
ETCDCTL_API=3 etcdctl snapshot save $BACKUP_DIR/etcd-$(date +\%Y\%m\%d-\%H\%M\%S).db \
 --endpoints=https://127.0.0.1:2379 \
 --cacert=/etc/etcd/ssl/etcd-ca.pem \
 --cert=/etc/etcd/ssl/etcd.pem \
 --key=/etc/etcd/ssl/etcd-key.pem
# 保留 7 天
find $BACKUP_DIR -name "etcd-*.db" -mtime +7 -delete

5.2 etcd 恢复

 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


# 1. 停所有 master 上的 apiserver（避免新数据写入）
for NODE in master1 master2 master3; do
 ssh $NODE "systemctl stop kube-apiserver"
done

# 2. 在每个 etcd 节点恢复
etcdctl snapshot restore /tmp/etcd-snapshot.db \
 --name master1 \
 --initial-cluster master1=https://192.168.139.133:2380,... \
 --initial-advertise-peer-urls https://192.168.139.133:2380 \
 --data-dir /var/lib/etcd-restore

# 3. 改 etcd.service 指向新 data-dir
# ExecStart=/usr/local/bin/etcd --config-file=/etc/etcd/etcd.config.yml
# 改 data-dir: /var/lib/etcd → /var/lib/etcd-restore

# 4. 启动 etcd
systemctl start etcd

# 5. 启动 apiserver
for NODE in master1 master2 master3; do
 ssh $NODE "systemctl start kube-apiserver"
done

# 6. 验证
kubectl get nodes

六、master 节点 IP 更换

K8s master 节点 IP 变了（机房迁移），需要：

替换 /etc/kubernetes 下所有 IP
替换 /etc/etcd/etcd.config.yml IP
替换 kube-apiserver systemd unit
重新签发证书（新 IP 必须在证书 hostname 列表里）
重启所有组件

 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


# 1. 替换配置
oldip=192.168.0.121
newip=192.168.133.121

find /etc/kubernetes -type f -exec grep -l "$oldip" {} \;
find /etc/kubernetes -type f -exec sed -i "s/$oldip/$newip/g" {} \;

find /etc/etcd/etcd.config.yml -type f -exec grep -l "$oldip" {} \;
find /etc/etcd/etcd.config.yml -type f -exec sed -i "s/$oldip/$newip/g" {} \;

# 2. 重新签发所有证书（用新 IP）
cd /data/softs/pki
cfssl gencert -initca etcd-ca-csr.json | cfssljson -bare /etc/etcd/ssl/etcd-ca
cfssl gencert -ca=/etc/etcd/ssl/etcd-ca.pem -ca-key=/etc/etcd/ssl/etcd-ca-key.pem \
 -config=ca-config.json \
 -hostname=127.0.0.1,master1,$newip \
 -profile=kubernetes etcd-csr.json | cfssljson -bare /etc/etcd/ssl/etcd
# ... 同样方式签发 apiserver / front-proxy / controller-manager / scheduler / admin / kube-proxy

# 3. 重新生成 kubeconfig
kubectl config set-cluster kubernetes --certificate-authority=/etc/kubernetes/pki/ca.pem \
 --embed-certs=true --server=https://$newip:6443 \
 --kubeconfig=/etc/kubernetes/admin.kubeconfig
# ... controller-manager / scheduler / kube-proxy / bootstrap 都重做

# 4. 重启
systemctl daemon-reload
systemctl restart kube-apiserver kube-controller-manager kube-scheduler
systemctl restart kubelet kube-proxy

七、排错清单

7.1 Pod 排错

症状	排查命令	原因
Pending	`kubectl describe pod` 看 Events	资源不够 / 节点 selector 不匹配 / PVC 未绑定
ImagePullBackOff	`kubectl describe pod`	镜像拉取失败（私有仓库 auth 错 / 镜像名错 / 网络问题）
CrashLoopBackOff	`kubectl logs --previous`	容器启动后立即退出（应用配置错 / OOMKilled）
ContainerCreating	`kubectl describe pod` + `kubectl get events`	volume 挂载失败 / CNI 没就绪
Error	`kubectl logs`	镜像启动命令失败 / 配置文件错

7.2 节点排错

症状	排查命令	原因
NotReady	`kubectl describe node`	kubelet 没起 / 网络不通 / 磁盘满
内存压力	`kubectl describe node`	节点压力驱逐 Pod

7.3 网络排错

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


# 同 Pod 内容器互通（同 Pod 共享网络）
kubectl exec -it pod1 -c c1 -- ping <pod2-ip>

# 同节点不同 Pod 互通
kubectl exec -it pod1 -- ping <pod2-ip>

# 跨节点 Pod 互通
kubectl exec -it pod1 -- ping <node2-ip>

# Service 解析
kubectl exec -it pod1 -- nslookup kubernetes.default

# Service 访问
kubectl exec -it pod1 -- curl http://<service-ip>:<port>

7.4 性能问题

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


# 节点资源使用
kubectl top node
kubectl top pod -A

# 找最忙的 Pod
kubectl top pod -A --sort-by=memory | head -10
kubectl top pod -A --sort-by=cpu | head -10

# 找 Pending 原因
kubectl get pods -A | grep Pending
kubectl describe pod <pending-pod>

# kube-proxy 模式（iptables vs ipvs）
kubectl get cm kube-proxy -n kube-system -o yaml | grep mode

八、常见坑

升级大版本跳级：必须逐级升（1.27 → 1.28 → 1.29），不能 1.26 → 1.28 跳升
cordon 后忘了 uncordon：节点永久 unschedulable
drain 没加 –ignore-daemonsets：calico / kube-proxy 被驱逐，节点网络断
etcd 备份忘了定时：灾难时无法恢复
证书 hostname 漏配：节点迁移后 kubectl 报 x509 错误
kubeconfig 没更新：节点迁移后 kubectl 仍连老 IP

九、前置知识 / 下一步

前置：

K8s 集群完整部署（参考 2020-03-15《K8s 二进制部署》）
etcd 备份（参考 2020-09-15《etcd 集群部署》）

下一步：

K8s 资源限制与探针（2022-03-15）—— Pod 调优
Kubeadm 一键部署（2022-06-15）—— 生产部署实战

参考资料

K8s Master 三大组件安装：apiserver / scheduler / controller-manager

Tue, 15 Dec 2020 00:00:00 +0800

写于 2020-12，背景：K8s 1.20 弃用 dockershim 进入倒计时。本文聚焦 Master 三大组件的参数调优、systemd 守护、与 etcd / kubelet 的协作。

一、Master 三大组件的角色

K8s 控制平面（control plane）由三大组件组成，跑在 master 节点上：

组件	角色	端口
kube-apiserver	集群网关，所有组件都跟它通信	6443 (HTTPS)
kube-scheduler	调度器，决定 Pod 跑哪个节点	无监听端口（HTTP 10251）
kube-controller-manager	控制器集合（30+ 控制器，Deployment/Node/Endpoint…）	无监听端口（HTTP 10252）

协作流程：kubectl → apiserver → scheduler 看到 Pod 没绑定节点 → 选节点写回 apiserver → controller-manager 看到 Pod 被调度 → 创建容器（通过 kubelet）

二、前置准备

所有 master 节点创建目录：

1

mkdir -p /etc/kubernetes/manifests/ /etc/systemd/system/kubelet.service.d /var/lib/kubelet /var/log/kubernetes

前置依赖：

etcd 集群已部署（参考 2020-09-15《etcd 集群部署》）
K8s 证书已签发（参考 2020-03-15《K8s 二进制部署》）

三、kube-apiserver.service

3.1 systemd 单元文件

 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


[Unit]
Description=Kubernetes API Server
Documentation=https://github.com/kubernetes/kubernetes
After=network.target

[Service]
ExecStart=/usr/local/bin/kube-apiserver \
 --v=2 \
 --allow-privileged=true \
 --bind-address=0.0.0.0 \
 --secure-port=6443 \
 --advertise-address=192.168.139.133 \
 --service-cluster-ip-range=10.96.0.0/12,fd00:1111::/112 \
 --service-node-port-range=30000-32767 \
 --etcd-servers=https://192.168.139.133:2379,https://192.168.139.134:2379,https://192.168.139.135:2379 \
 --etcd-cafile=/etc/etcd/ssl/etcd-ca.pem \
 --etcd-certfile=/etc/etcd/ssl/etcd.pem \
 --etcd-keyfile=/etc/etcd/ssl/etcd-key.pem \
 --client-ca-file=/etc/kubernetes/pki/ca.pem \
 --tls-cert-file=/etc/kubernetes/pki/apiserver.pem \
 --tls-private-key-file=/etc/kubernetes/pki/apiserver-key.pem \
 --kubelet-client-certificate=/etc/kubernetes/pki/apiserver.pem \
 --kubelet-client-key=/etc/kubernetes/pki/apiserver-key.pem \
 --service-account-key-file=/etc/kubernetes/pki/sa.pub \
 --service-account-signing-key-file=/etc/kubernetes/pki/sa.key \
 --service-account-issuer=https://kubernetes.default.svc.cluster.local \
 --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname \
 --enable-admission-plugins=NamespaceLifecycle,LimitRanger,ServiceAccount,DefaultStorageClass,DefaultTolerationSeconds,NodeRestriction,ResourceQuota \
 --authorization-mode=Node,RBAC \
 --enable-bootstrap-token-auth=true \
 --requestheader-client-ca-file=/etc/kubernetes/pki/front-proxy-ca.pem \
 --proxy-client-cert-file=/etc/kubernetes/pki/front-proxy-client.pem \
 --proxy-client-key-file=/etc/kubernetes/pki/front-proxy-client-key.pem \
 --requestheader-allowed-names=aggregator \
 --requestheader-group-headers=X-Remote-Group \
 --requestheader-extra-headers-prefix=X-Remote-Extra- \
 --requestheader-username-headers=X-Remote-User \
 --enable-aggregator-routing=true
Restart=on-failure
RestartSec=10s
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

3.2 关键参数详解

参数	含义	调优建议
`--advertise-address`	apiserver 对外宣告的 IP	每个 master 不同
`--service-cluster-ip-range`	Service IP 段	/12 给 ~1M Service 够用
`--etcd-servers`	etcd 集群地址	多个用逗号分隔
`--enable-admission-plugins`	准入控制器	至少包含 `NamespaceLifecycle,LimitRanger,ServiceAccount`
`--authorization-mode`	鉴权模式	`Node,RBAC` 是标配
`--requestheader-allowed-names`	聚合层（metrics-server 等）	必须是 `aggregator`
`--enable-bootstrap-token-auth`	kubelet TLS bootstrap	kubeadm 部署必开
`--service-account-issuer`	SA token 签发者	1.20+ 必须配，否则 controller 报错

3.3 启动

1
2
3
4
5


# 所有 master 节点
systemctl daemon-reload
systemctl enable --now kube-apiserver
systemctl status kube-apiserver
journalctl -f -u kube-apiserver

验证（master1）：

1
2
3
4
5
6
7


curl -k https://192.168.139.133:6443/version
# {
# "major": "1",
# "minor": "28",
# "gitVersion": "v1.28.5",
# ...
# }

四、kube-controller-manager.service

4.1 systemd 单元文件

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


[Unit]
Description=Kubernetes Controller Manager
Documentation=https://github.com/kubernetes/kubernetes
After=network.target

[Service]
ExecStart=/usr/local/bin/kube-controller-manager \
 --v=2 \
 --bind-address=0.0.0.0 \
 --root-ca-file=/etc/kubernetes/pki/ca.pem \
 --cluster-signing-cert-file=/etc/kubernetes/pki/ca.pem \
 --cluster-signing-key-file=/etc/kubernetes/pki/ca-key.pem \
 --service-account-private-key-file=/etc/kubernetes/pki/sa.key \
 --kubeconfig=/etc/kubernetes/controller-manager.kubeconfig \
 --leader-elect=true \
 --use-service-account-credentials=true \
 --controllers=*,bootstrapsigner,tokencleaner
Restart=on-failure
RestartSec=10s
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

4.2 关键参数

参数	含义
`--leader-elect=true`	启用 leader 选举，多 master 时只有 leader 干活
`--use-service-account-credentials=true`	每个 controller 用独立 SA（1.20+ 必须）
`--controllers=*`	启用所有 controller（默认），可裁剪
`--cluster-signing-*`	给新节点签发证书用的 CA（kubelet 证书签发）

4.3 controller 分类

kube-controller-manager 实际上是 30+ 控制器的合集：

控制器	作用
Deployment controller	维护 Deployment 期望的副本数
ReplicaSet controller	维护 RS 副本
Node controller	监听节点心跳，标记 NotReady
Endpoint controller	维护 Service ↔ Pod 映射
ServiceAccount controller	自动给 namespace 创建 default SA
Token controller	给 SA 签发 token
Job controller	维护一次性任务
CronJob controller	维护定时任务
PV controller	处理 PV/PVC 绑定
Namespace controller	清理已删除 namespace 的资源
ResourceQuota controller	强制 namespace 资源配额
HorizontalPodAutoscaler	HPA 自动扩缩容
等等…

为什么不裁剪？ K8s 默认 --controllers=*，几乎所有 controller 都需要；只有定制化集群才裁剪（比如不要 serviceaccount-controller，因为用外部 SA 系统）。

五、kube-scheduler.service

5.1 systemd 单元文件

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


[Unit]
Description=Kubernetes Scheduler
Documentation=https://github.com/kubernetes/kubernetes
After=network.target

[Service]
ExecStart=/usr/local/bin/kube-scheduler \
 --v=2 \
 --bind-address=0.0.0.0 \
 --leader-elect=true \
 --kubeconfig=/etc/kubernetes/scheduler.kubeconfig \
 --config=/etc/kubernetes/scheduler-config.yaml
Restart=on-failure
RestartSec=10s
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

5.2 调度配置

/etc/kubernetes/scheduler-config.yaml：

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


apiVersion: kubescheduler.config.k8s.io/v1
kind: KubeSchedulerConfiguration
leaderElection:
 leaderElect: true
 resourceNamespace: kube-system
 resourceName: kube-scheduler
profiles:
 - schedulerName: default-scheduler
 plugins:
 score:
 enabled:
 - name: NodeResourcesFit
 - name: NodeAffinity
 - name: PodTopologySpread
 - name: InterPodAffinity
 - name: TaintToleration
 - name: ImageLocality

5.3 调度流程（两阶段）

1. Filtering（过滤）：把所有节点过一遍，留下"能跑"的节点

资源够不够（CPU/内存 request）
端口是否被占用
是否匹配 nodeSelector / nodeAffinity
是否容忍 Pod 的 toleration
是否有 PVC 满足条件

2. Scoring（打分）：对剩下的节点打分，选最高分

资源使用率均衡（避免热点节点）
镜像本地优先（pod 内已有镜像的节点加分）
拓扑打散（Pod 反亲和性）
自定义插件（如 binpack 优化利用率）

六、启动顺序

严格按顺序启动：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 1. etcd
systemctl start etcd
etcdctl endpoint health --cluster # 验证

# 2. kube-apiserver
systemctl start kube-apiserver
curl -k https://localhost:6443/healthz # 验证

# 3. controller-manager 和 scheduler（可并行）
systemctl start kube-controller-manager
systemctl start kube-scheduler

为什么这个顺序？ apiserver 依赖 etcd；controller-manager 和 scheduler 都通过 apiserver 工作。

七、验证

1
2
3
4
5
6
7
8


# 在 master1 验证
kubectl get componentstatuses
# 或
kubectl get cs
# NAME STATUS MESSAGE ERROR
# controller-manager Healthy ok
# scheduler Healthy ok
# etcd-0 Healthy {"health":"true"}

详细验证：

1
2
3
4
5
6
7
8


# 看 apiserver 性能指标（需 prometheus 或 kubectl proxy）
kubectl get --raw=/metrics | grep apiserver_request_total

# 看 scheduler 调度队列
kubectl get --raw=https://localhost:10251/metrics

# 看 controller-manager 状态
kubectl get --raw=https://localhost:10252/metrics

八、HA 场景下的 leader 选举

3 master 高可用时，scheduler 和 controller-manager 都有 leader 选举机制（apiserver 不用选举，所有 apiserver 都对外服务）：

启动时通过 --leader-elect=true 抢占分布式锁
当前 leader 挂了，其他节点 5~15 秒后接管
kube-scheduler-leader 和 kube-controller-manager-leader 是两个 ConfigMap，存当前 leader 名

查看当前 leader：

1
2


kubectl get cm -n kube-system kube-scheduler-leader -o yaml
kubectl get cm -n kube-system kube-controller-manager-leader -o yaml

九、常见坑

apiserver 启动报 “x509: certificate is not valid for 10.96.0.1”：apiserver 证书的 hostname 列表漏配 10.96.0.1（Service cluster IP）或其他 IP，重新签发
apiserver 启动报 “etcd cluster is unavailable”：先 etcdctl endpoint health 验证 etcd，常见是证书路径错（/etc/etcd/ssl/ vs /etc/kubernetes/pki/etcd/）
controller-manager 启动后 Pod 创建不出 Pod：检查 cluster-signing-cert-file 路径；或 RBAC 权限不足（controller-manager 自己的 SA kubeconfig）
scheduler 日志 “leader election lost”：网络抖动，多 master 情况下短暂无影响
修改配置后不生效：必须 systemctl daemon-reload && systemctl restart kube-apiserver，不是 reload

十、前置知识 / 下一步

前置：

etcd 集群部署（参考 2020-09-15《etcd 集群部署》）
证书签发（参考 2020-03-15《K8s 二进制部署》）

下一步：

API Server 高可用（2021-03-15）—— Nginx 四层 + Keepalived VIP
K8s 集群插件（2021-09-15）—— CNI / CoreDNS / Metrics / Dashboard
K8s 集群管理（2021-12-15）—— 升级、节点隔离

参考资料

K8s 集群流量入口：Ingress-nginx 七层与 TCP/UDP 四层代理实战

Tue, 15 Dec 2020 00:00:00 +0800

K8s 集群流量入口：Ingress-nginx 七层与 TCP/UDP 四层代理实战

TL;DR：在 K8s 里 Pod IP / ClusterIP 只能在集群内访问。要把服务暴露到集群外，常见链路是 ingress-nginx（七层 HTTP）→ Service（ClusterIP）→ Pod；非 HTTP 的 TCP/UDP 流量（数据库、MQTT、WebSocket、SSH）走 ingress-nginx 的 四层 stream-snippet / ConfigMap 或 hostNetwork + DaemonSet 模式。本文是一份基于生产二进制集群踩坑的实战笔记。

一、为什么需要 Ingress（When to use）

K8s 提供了 4 种把集群内服务暴露到外部的方式：

方式	适用场景	优点	缺点
`NodePort`	开发测试、单端口临时调试	简单，配置最少	端口范围受限（30000-32767），要逐个开防火墙
`LoadBalancer`	云厂商环境	自动化分配公网 IP	依赖云厂商 LB，每个 Service 一个 LB 贵
`Ingress`	HTTP/HTTPS 七层路由，多域名多路径	一台 LB 服务多套系统，支持 TLS 终止、灰度	只能代理 HTTP/HTTPS
`hostNetwork`	四层流量 + 极致性能	走宿主机网络，无 kube-proxy 转发损耗	一个 Node 只能跑一个 Pod，要配 `nodeSelector`

核心架构：

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


外网 (Client)
 │
 ▼
[ NodePort / LoadBalancer / hostNetwork ]
 │
 ▼
[ ingress-nginx-controller ] ← 七层：解析 Host / Path
 │
 ▼
[ Service (ClusterIP) ] ← 集群内虚拟 IP
 │
 ▼
[ Pod (业务容器) ]

原则：ingress 代理 service，service 代理 pod。Ingress 本身不直接连 Pod，一定要过 Service 这一层（service mesh 也是同理）。

API 版本注意：本文示例全部使用 apiVersion: networking.k8s.io/v1（K8s 1.19 GA，1.22 起 extensions/v1beta1 被彻底移除）。kubernetes.io/ingress.class 注解在 1.18 后也已被 spec.ingressClassName 取代，请直接使用新写法。

二、安装 ingress-nginx

2.1 部署清单来源

官方仓库：https://github.com/kubernetes/ingress-nginx
云厂商部署清单：https://github.com/kubernetes/ingress-nginx/blob/main/deploy/static/provider/cloud/deploy.yaml

⚠️ 版本匹配：K8s 1.19+ 务必使用 ingress-nginx v0.46+（首个 networking.k8s.io/v1 稳定支持的 controller），2020 年下半年该分支已 GA。

2.2 应用与查看

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


# 部署
kubectl apply -f /etc/k8s/ingress-nginx/deploy.yaml

# 删除
kubectl delete -f /etc/k8s/ingress-nginx/deploy.yaml

# 部署后产生的核心资源
namespace/ingress-nginx created
serviceaccount/ingress-nginx created
serviceaccount/ingress-nginx-admission created
role.rbac.authorization.k8s.io/ingress-nginx created
clusterrole.rbac.authorization.k8s.io/ingress-nginx created
configmap/ingress-nginx-controller created
service/ingress-nginx-controller created
deployment.apps/ingress-nginx-controller created
job.batch/ingress-nginx-admission-create created
job.batch/ingress-nginx-admission-patch created
ingressclass.networking.k8s.io/nginx created
validatingwebhookconfiguration.admissionregistration.k8s.io/ingress-nginx-admission created

2.3 资源清单

1

kubectl get all -n ingress-nginx

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


NAME READY STATUS RESTARTS AGE
pod/ingress-nginx-admission-create-cf9w5 0/1 Completed 0 7m36s
pod/ingress-nginx-admission-patch-zm7m5 0/1 Completed 0 7m36s
pod/ingress-nginx-controller-766bcbf897-fhvrb 1/1 Running 0 7m36s

NAME TYPE CLUSTER-IP PORT(S)
service/ingress-nginx-controller NodePort 10.x.x.x 80:30080/TCP,443:30443/TCP
service/ingress-nginx-controller-admission ClusterIP 10.x.x.x 443/TCP

NAME READY UP-TO-DATE AVAILABLE
deployment.apps/ingress-nginx-controller 1/1 1 1

这里的 ingressclass.networking.k8s.io/nginx 是 v1 引入的 IngressClass 对象，下游 Ingress 资源靠 spec.ingressClassName: nginx 引用它。

三、最简七层反代测试

3.1 测试 Deployment / Service / Ingress

 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


# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 namespace: test
spec:
 replicas: 3
 selector:
 matchLabels:
 app: nginx
 template:
 metadata:
 labels:
 app: nginx
 spec:
 containers:
 - name: nginx
 image: nginx:1.25
---
# service.yaml
apiVersion: v1
kind: Service
metadata:
 name: nginx-service
 namespace: test
spec:
 selector:
 app: nginx
 ports:
 - port: 80
 targetPort: 80

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


# ingress.yaml（networking.k8s.io/v1）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: test-ingress
 namespace: test
spec:
 ingressClassName: nginx
 rules:
 - host: nginx.example.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: nginx-service
 port:
 number: 80

1
2
3


kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
kubectl apply -f ingress.yaml

3.2 查看 Ingress 解析结果

1

kubectl describe ingress test-ingress -n test

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


Name: test-ingress
Namespace: test
Address: 10.x.x.x
Ingress Class: nginx
Default backend: <default>
Rules:
 Host Path Backends
 ---- ---- --------
 nginx.example.com
 / nginx-service:80 (10.244.1.10:80, 10.244.2.71:80, 10.244.3.8:80)
Events:
 Type Reason Age From Message
 ---- ------ ---- ---- -------
 Normal Sync 110s (x2 over 2m22s) nginx-ingress-controller Scheduled for sync

3.3 本地 hosts + curl 测试

1
2
3
4
5
6
7
8


# /etc/hosts（开发机）
# 内网IP-A nginx.example.com tomcat.example.com

# 直接访问 NodePort
curl -H "Host: nginx.example.com" http://内网IP-A:30080/

# 或先 ping 测连通
ping 内网IP-A

v1 与 v1beta1 的关键差异（写错会 apply 失败）：

字段 extensions/v1beta1（已弃用） networking.k8s.io/v1（本文用）

apiVersion extensions/v1beta1 networking.k8s.io/v1

路径匹配 path: /foo（隐式 Prefix） path: /foo + pathType: Prefix | Exact | ImplementationSpecific（必填）

后端 backend.serviceName + servicePort backend.service.name + backend.service.port.number/name

Ingress 类注解 kubernetes.io/ingress.class: nginx spec.ingressClassName: nginx

四、关键注解（Annotations）速查

完整注解列表：https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md

4.1 不配置 host，用路径区分服务（Nacos 场景）

把 Nacos 控制台通过 /nacos 路径前缀反代出去，不绑定 host：

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


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: nacos-ingress
 namespace: example-corp
 annotations:
 nginx.ingress.kubernetes.io/use-regex: "true"
spec:
 ingressClassName: nginx
 rules:
 - http:
 paths:
 - pathType: Prefix
 path: /nacos
 backend:
 service:
 name: nacos-headless
 port:
 name: server

访问地址：http://内网IP-A/nacos

注意：当 host 字段省略，Ingress 会响应所有到达 controller 的请求，生产环境强烈建议绑定 host 防止冲突。如果一定要多服务复用 host，请用 pathType: Prefix 拆分路径。

4.2 app-root：访问根路径自动重定向

1
2
3


metadata:
 annotations:
 nginx.ingress.kubernetes.io/app-root: /corp

访问 https://example-corp.com/ 会 302 到 https://example-corp.com/corp，适合老门户的默认页迁移。

五、hostNetwork 模式：性能 + 四层必备

默认 ingress-nginx-controller 是 Deployment + Service(NodePort)，但生产环境有两类需求让它不够用：

直接监听 80/443 端口——不想用 30080/30443 这种高位端口
代理 TCP/UDP 四层流量——NodePort 不支持 stream

解决方案：hostNetwork: true + DaemonSet + nodeSelector，让 controller 在每个打了 ingress=true 标签的 Node 上独占监听宿主机网络。

5.1 修改清单的关键点

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


spec:
 # 1. 改成 DaemonSet：一个 Node 只能跑一个 controller
 kind: DaemonSet

 template:
 spec:
 # 2. 与宿主机共享网络栈
 hostNetwork: true

 # 3. 节点选择器
 nodeSelector:
 kubernetes.io/os: linux
 ingress: "true"

 # 4. hostNetwork 模式下要保留 K8s DNS
 dnsPolicy: ClusterFirstWithHostNet

删除 replicas、strategy.rollingUpdate 等 Deployment 专属字段。

5.2 给 Node 打标签

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


# 打标签
kubectl label node k8s-master-1 ingress=true
kubectl label node k8s-master-2 ingress=true
kubectl label node k8s-master-3 ingress=true

# 移除标签
kubectl label node k8s-master-3 ingress=true-

# 容忍 NoSchedule 污点（master 节点常有）
kubectl taint nodes k8s-master-1 node-role.kubernetes.io/control-plane:NoSchedule-

# 查看所有节点标签
kubectl get node --show-labels

5.3 部署与验证

1
2
3
4
5
6
7
8


# 先删旧 Deployment
kubectl delete -f /etc/k8s/ingress-nginx/deploy.yaml

# 部署新清单
kubectl apply -f /etc/k8s/ingress-nginx/hostNetwork.yaml

# 查看 controller 是否在每个 Node 跑一个
kubectl get pods -n ingress-nginx -o wide

1
2
3
4


NAME READY STATUS IP NODE
ingress-nginx-controller-cd58b 1/1 Running 内网IP-B k8s-master-2
ingress-nginx-controller-cgzk7 1/1 Running 内网IP-C k8s-master-1
ingress-nginx-controller-p2fdt 1/1 Running 内网IP-D k8s-master-3

5.4 验证四层与七层

1
2
3
4
5


# 七层：80 端口直接访问
curl http://nginx.example.com

# 四层：可以走 NodePort 也可以走宿主机 IP 直连
curl -H "Host: nginx.example.com" http://内网IP-A

六、四层代理：代理集群外的 TCP / WS / UDP

ingress-nginx 默认只代理 HTTP / HTTPS。要让 ingress-nginx 转发 TCP / UDP 流量（如 MySQL 3306、MQTT 1883、自定义 WebSocket），有三种方案：

6.1 方案对比

方案	适用场景	优点	缺点
① `stream-snippet` 注解	单个 Ingress 临时使用	配置最简单	不易复用
② `ConfigMap` 集中管理	多服务、需统一管理	一个 CM 管多个端口	要修改 DaemonSet args
③ `ExternalName` + Service	集群内 Pod 访问集群外	应用侧零配置	集群外无法反向访问

6.2 方案一：使用 Endpoints + Service + Ingress + stream-snippet

核心思路：用 Endpoints 直接指向集群外的 IP:PORT，再通过 Ingress 的 stream-snippet 注解把流量引过去。

⚠️ Endpoints.name 必须和 Service.name 完全一致——这是手写四层 Service 的铁律，写错 Service 永远 no endpoints available。

 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


# tcp-outside-3306.yaml
apiVersion: v1
kind: Endpoints
metadata:
 name: external-mysql
 namespace: example-corp
subsets:
 - addresses:
 - ip: 内网IP-E  # 集群外的 MySQL 真实地址
 ports:
 - port: 3306
 protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
 name: external-mysql
 namespace: example-corp
spec:
 clusterIP: None  # Headless Service，由 Endpoints 决定后端
 type: ClusterIP
 ports:
 - port: 7306 # 集群内访问用的端口
 protocol: TCP
 targetPort: 3306 # 转发到 Endpoints 里的 3306

 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


# tcp-outside-3306-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: external-mysql-ingress
 namespace: example-corp
 annotations:
 nginx.ingress.kubernetes.io/stream-snippet: |
 server {
 listen 8000;
 proxy_pass 内网IP-E:3306;
 }
spec:
 ingressClassName: nginx
 rules:
 - host: mysql.example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: external-mysql
 port:
 number: 7306

TCP 流量不要用 HTTP 测：四层流量没有 Host 头，curl http://内网IP-A:8000 会一直 400。正确姿势：nc -vz 内网IP-A 8000 或 telnet 内网IP-A 8000。

6.3 方案二：ConfigMap 集中管理（推荐生产用）

第一步：创建 ConfigMap 占位

1

kubectl -n ingress-nginx create configmap tcp-services

第二步：编辑 ConfigMap

1

kubectl edit -n ingress-nginx cm tcp-services

1
2
3
4
5
6
7
8
9


apiVersion: v1
kind: ConfigMap
metadata:
 name: tcp-services
 namespace: ingress-nginx
data:
 # 格式："<对外端口>": "<namespace>/<service>:<service-port>"
 "7306": "example-corp/external-mysql:7306"
 "1883": "example-corp/mqtt-service:1883"

第三步：让 controller 加载 ConfigMap

1

kubectl edit -n ingress-nginx DaemonSet/ingress-nginx-controller

1
2
3
4
5
6
7
8


spec:
 template:
 spec:
 containers:
 - args:
 - /nginx-ingress-controller
 - --tcp-services-configmap=$(POD_NAMESPACE)/tcp-services
 - --udp-services-configmap=$(POD_NAMESPACE)/udp-services

重要：$(POD_NAMESPACE) 是 controller 自带的 downward API 变量，会自动展开为 ingress-nginx，不要手写死。

第四步：补充 Service 端口暴露

1

kubectl edit -n ingress-nginx Service/ingress-nginx-controller

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


spec:
 ports:
 - name: http
 port: 80
 targetPort: 80
 - name: https
 port: 443
 targetPort: 443
 - name: external-mysql
 port: 7306
 targetPort: 7306
 protocol: TCP

第五步：调整 Service 类型与 externalIPs

1
2
3


# 类型改为 LoadBalancer（云厂商自动分配 IP）
kubectl patch svc ingress-nginx-controller -n ingress-nginx \
 -p '{"spec": {"type": "LoadBalancer", "externalIPs":["内网IP-A"]}}'

6.4 集群内测试连通

 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


# 用 busybox 测连通
kubectl exec -it busybox -- sh
ping external-mysql.example-corp.svc.cluster.local
telnet external-mysql.example-corp.svc.cluster.local 3306

# 用 ubuntu + mycli 工具测
cat << "EOF" > ubuntu.yml
apiVersion: v1
kind: Pod
metadata:
 name: diag-pod
spec:
 containers:
 - name: ubuntu
 image: ubuntu:22.04
 command: [ "/bin/bash", "-c", "--" ]
 args: [ "while true; do sleep 3600; done;" ]
EOF

kubectl apply -f ubuntu.yml
kubectl exec -it diag-pod -- bash
apt update && apt install -y python3-pip
pip3 install mycli

# 用 K8s Service DNS 名连接（注意改密码）
mycli -h external-mysql.example-corp.svc.cluster.local -uroot -p'<REDACTED-MYSQL-PWD>'

七、TLS 终端

7.1 创建 Secret

1
2
3
4
5
6
7
8


# 先建命名空间
kubectl create namespace example-corp

# 从证书文件创建 TLS Secret
kubectl create secret generic www-example-corp-secret \
 --from-file=tls.key=<CERT_ID>__example-corp.com.key \
 --from-file=tls.crt=<CERT_ID>__example-corp.com.pem \
 -n example-corp

7.2 开启 configuration-snippet

ingress-nginx v0.46+ 默认禁用 configuration-snippet（安全考量），要自定义 nginx 片段必须先开：

1

kubectl edit -n ingress-nginx configmap/ingress-nginx-controller

1
2


data:
 allow-snippet-annotations: "true" # 允许使用 configuration-snippet 注解

7.3 启用 TLS 的 Ingress

 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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


apiVersion: v1
kind: Endpoints
metadata:
 name: www-service
 namespace: example-corp
subsets:
 - addresses:
 - ip: 内网IP-F
 ports:
 - port: 81
 protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
 name: www-service
 namespace: example-corp
spec:
 ports:
 - port: 81
 targetPort: 81
 protocol: TCP
 type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: www-ingress
 namespace: example-corp
 annotations:
 nginx.ingress.kubernetes.io/app-root: /corp
 nginx.ingress.kubernetes.io/use-regex: "true"
 nginx.ingress.kubernetes.io/configuration-snippet: |
 access_log /var/log/nginx/www.example-corp.com.access.log upstreaminfo if=$loggable;
 error_log /var/log/nginx/www.example-corp.com.error.log;
spec:
 ingressClassName: nginx
 tls:
 - hosts:
 - example-corp.com
 - www.example-corp.com
 secretName: www-example-corp-secret
 rules:
 - host: www.example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: www-service
 port:
 number: 81
 - host: example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: www-service
 port:
 number: 81

1

kubectl apply -f /etc/k8s/ingress/www-ingress.yaml

访问：https://example-corp.com https://www.example-corp.com

八、WebSocket 代理

ingress-nginx 默认支持 WebSocket，但要在 location 里显式设置：

1
2
3
4
5
6
7
8
9


location / {
 proxy_pass http://backend;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_read_timeout 3600s; # 长连接超时
}

在 ingress-nginx 里用注解实现：

1
2
3
4
5


metadata:
 annotations:
 nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
 nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
 # WebSocket 自动识别 Connection: Upgrade

默认 60s 不发包就断，WebSocket / 长轮询场景必须把 read/send timeout 拉到 3600s 以上，否则客户端会频繁断连。

九、Nacos 反代实战

Nacos Headless Service（clusterIP: None）+ Ingress 是社区最常见的"在 K8s 外面访问 Nacos 控制台"姿势：

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


# 假设 Nacos 已经用 Helm 或 Operator 部署好
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: nacos-console
 namespace: nacos
 annotations:
 nginx.ingress.kubernetes.io/use-regex: "true"
 nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
spec:
 ingressClassName: nginx
 rules:
 - host: nacos.example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: nacos-headless
 port:
 name: server  # 8848，对应 service.port.name

同样适用 Apollo、Consul、Sentinel Dashboard 等"控制台类服务"。use-regex: "true" 是因为 Nacos 前端路由里有 /#/xxx 这种 hash 路径，不开 regex 会被当成物理路径处理。

十、常见 8 个坑

#	坑	现象	解决
1	用了 `extensions/v1beta1`	K8s 1.22+ 直接 `apply` 失败 `no matches for kind`	改用 `networking.k8s.io/v1`，`pathType` 必填
2	忘写 `pathType`	`networking.k8s.io/v1` apply 报 `pathType Required value`	路径下必须显式 `pathType: Prefix \| Exact \| ImplementationSpecific`
3	Windows 能 ping 通但浏览器打不开	hosts 配了域名，ping 通，浏览器 502	关代理、关防火墙；`netsh winsock reset` 重启
4	客户端开了代理工具后无法访问 Ingress	浏览器挂了科学上网工具，所有流量走代理，Ingress 不通	代理工具"Bypass Domain/IP"里加业务域名；或选"全球直连"
5	Endpoints.name 与 Service.name 不一致	Service 一直无 Endpoints，curl 报 no endpoints available	严格保持两个 name 一致；这是 K8s 老坑
6	hostNetwork 模式下 DNS 解析错乱	Pod 用宿主机 `/etc/resolv.conf`，找不到集群内服务	`dnsPolicy: ClusterFirstWithHostNet`
7	DaemonSet 配了 replicas 字段	apply 时报 validation error	删掉 `replicas` 和 `strategy.rollingUpdate`
8	`configuration-snippet` 不生效	自定义 nginx 片段被忽略	ConfigMap 里设 `allow-snippet-annotations: "true"`
9	TCP 走 8000 端口但用 HTTP 测	telnet 通，curl 失败	四层不能用 HTTP 探测；用 `nc -vz` 或 `telnet`

十一、核心 6 点速记

链路：外网 → NodePort/hostNetwork → ingress-nginx → Service → Pod
七层（HTTP）用 Ingress；四层（TCP/UDP）用 stream-snippet 或 ConfigMap + DaemonSet args
生产必开 hostNetwork：直连 80/443 + 支持四层；必须配 DaemonSet + nodeSelector + dnsPolicy: ClusterFirstWithHostNet
Endpoints.name == Service.name 是手写四层 Service 的铁律
TLS 终端走 Ingress tls.hosts + secretName；自定义 nginx 片段需先开 allow-snippet-annotations
Ingress 不直接连 Pod：中间一定要过 Service（service mesh 同样），不要图省事

十二、排错命令速查

 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


# 查看 controller 配置
kubectl exec -it <pod> -n ingress-nginx -- cat /etc/nginx/nginx.conf

# 实时日志
kubectl logs -f -n ingress-nginx <pod>

# 集群内连通性
kubectl exec -it busybox -- sh
ping <svc>.<ns>.svc.cluster.local

# Service 详情
kubectl describe svc <svc-name> -n <ns>
kubectl describe endpoints <svc-name> -n <ns>

# Ingress 状态
kubectl get ingress -A
kubectl describe ingress <name> -n <ns>

# IngressClass 引用关系
kubectl get ingressclass
kubectl get ingress -A -o jsonpath='{range .items[?(@.spec.ingressClassName)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'

# hostNetwork 模式查看端口监听
ss -tlnp | grep -E ":(80|443|3306|1883)"

# 检查 controller 加载的 TCP/UDP ConfigMap
kubectl logs -n ingress-nginx <pod> | grep -E "tcp-services|stream-snippet"

十三、参考资料

ingress-nginx 仓库：https://github.com/kubernetes/ingress-nginx
官方部署清单：https://github.com/kubernetes/ingress-nginx/blob/main/deploy/static/provider/cloud/deploy.yaml
Annotation 索引：https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md
Ingress API v1 文档：https://kubernetes.io/docs/concepts/services-networking/ingress/
K8s 1.20 Release Notes（v1 Ingress GA）：https://kubernetes.io/blog/2020/12/08/kubernetes-1-20-release-announcement/
nginx stream 模块：https://nginx.org/en/docs/stream/ngx_stream_core_module.html
Nacos 集群部署：https://nacos.io/zh-cn/docs/cluster-mode-quick-start.html

etcd 集群部署：3 节点高可用与 Raft 选举详解

Tue, 15 Sep 2020 00:00:00 +0800

写于 2020-09，背景：etcd v3.4 时代，K8s 1.19 仍以 3 节点 etcd 集群为生产推荐。本文聚焦 etcd 集群原理 + 实战部署。

一、etcd 是什么

etcd 是一个分布式键值数据库，天生为集群化设计：

数据模型：扁平 key-value，类比 redis 但走磁盘（强一致）
一致性算法：Raft（保证多节点数据强一致）
API：gRPC + HTTP/JSON，对 K8s 友好
应用场景：服务发现、配置中心、K8s/calico/Docker Swarm 后端存储

etcd 是 CNCF 毕业项目，与 K8s 同源（都来自 Borg 系统的设计哲学）。

二、Raft 算法与集群规模

Raft 在做决策时需要超半数节点投票，所以 etcd 集群推荐奇数节点（3/5/7）：

节点数	最大容忍故障	备注
1	0	单实例，无集群意义
2	0	双节点能启动，但挂一台就选不出主，不要用
3	1	生产最低推荐
4	1	跟 3 一样，浪费一台
5	2	中型集群推荐
6	2	跟 5 一样，浪费一台
7	3	大型集群（>100 节点）

为什么不能是偶数？ 4 节点和 3 节点都是容忍 1 台故障，但 4 节点多一台机器成本；6 节点和 5 节点同理。Raft 选举只看"过半"，不看你有几个备份。

三、集群规划

3 master 节点同时跑 etcd（etcd 与 apiserver 同节点部署是 K8s 官方推荐）：

主机名	IP	角色
master1	`192.168.139.133`	etcd-1 + apiserver
master2	`192.168.139.134`	etcd-2 + apiserver
master3	`192.168.139.135`	etcd-3 + apiserver

端口约定：

2379：客户端 API（kube-apiserver 调 etcd）
2380：节点间 peer 通信（Raft 选举 + 数据同步）

四、生成 etcd 证书

K8s 集群里 etcd 走双向 TLS，证书前置在 2020-03-15《K8s 二进制部署》已签发。关键步骤回顾：

 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


# ca-config.json
cat > ca-config.json << EOF
{
 "signing": {
 "default": { "expiry": "876000h" },
 "profiles": {
 "kubernetes": {
 "usages": ["signing", "key encipherment", "server auth", "client auth"],
 "expiry": "876000h"
 }
 }
 }
}
EOF

# etcd CA
cat > etcd-ca-csr.json << EOF
{
 "CN": "etcd",
 "key": { "algo": "rsa", "size": 2048 },
 "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "etcd", "OU": "Etcd Security" }],
 "ca": { "expiry": "876000h" }
}
EOF

cfssl gencert -initca etcd-ca-csr.json | cfssljson -bare /etc/etcd/ssl/etcd-ca

# etcd server 证书（注意 hostname + IP 全列）
cat > etcd-csr.json << EOF
{
 "CN": "etcd",
 "key": { "algo": "rsa", "size": 2048 },
 "names": [{ "C": "CN", "ST": "Beijing", "L": "Beijing", "O": "etcd", "OU": "Etcd Security" }]
}
EOF

cfssl gencert \
 -ca=/etc/etcd/ssl/etcd-ca.pem \
 -ca-key=/etc/etcd/ssl/etcd-ca-key.pem \
 -config=ca-config.json \
 -hostname=127.0.0.1,master1,master2,master3,192.168.139.133,192.168.139.134,192.168.139.135 \
 -profile=kubernetes \
 etcd-csr.json | cfssljson -bare /etc/etcd/ssl/etcd

五、安装 etcd 二进制

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


# 解压
wget https://github.com/etcd-io/etcd/releases/download/v3.5.11/etcd-v3.5.11-linux-amd64.tar.gz
tar -xf etcd-v3.5.11-linux-amd64.tar.gz
mv etcd-v3.5.11-linux-amd64/etcd /usr/local/bin/
mv etcd-v3.5.11-linux-amd64/etcdctl /usr/local/bin/
mv etcd-v3.5.11-linux-amd64/etcdutl /usr/local/bin/

# 验证
etcd --version
etcdctl version
# etcdctl version: 3.5.11
# API version: 3.5

六、etcd 配置文件

每个 master 节点单独写一份 /etc/etcd/etcd.config.yml，注意 name、listen URL、advertise URL 都不同。

6.1 master1 配置

 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


name: 'master1'
data-dir: /var/lib/etcd
wal-dir: /var/lib/etcd/wal
snapshot-count: 5000
heartbeat-interval: 100
election-timeout: 1000
quota-backend-bytes: 0
listen-peer-urls: 'https://192.168.139.133:2380'
listen-client-urls: 'https://192.168.139.133:2379,http://127.0.0.1:2379'
max-snapshots: 3
max-wals: 5
initial-advertise-peer-urls: 'https://192.168.139.133:2380'
advertise-client-urls: 'https://192.168.139.133:2379'
initial-cluster: 'master1=https://192.168.139.133:2380,master2=https://192.168.139.134:2380,master3=https://192.168.139.135:2380'
initial-cluster-token: 'etcd-k8s-cluster'
initial-cluster-state: 'new'
strict-reconfig-check: false
enable-v2: true
enable-pprof: true
proxy: 'off'
client-transport-security:
 cert-file: '/etc/kubernetes/pki/etcd/etcd.pem'
 key-file: '/etc/kubernetes/pki/etcd/etcd-key.pem'
 client-cert-auth: true
 trusted-ca-file: '/etc/kubernetes/pki/etcd/etcd-ca.pem'
 auto-tls: true
peer-transport-security:
 cert-file: '/etc/kubernetes/pki/etcd/etcd.pem'
 key-file: '/etc/kubernetes/pki/etcd/etcd-key.pem'
 peer-client-cert-auth: true
 trusted-ca-file: '/etc/kubernetes/pki/etcd/etcd-ca.pem'
 auto-tls: true
debug: false
log-outputs: [default]
force-new-cluster: false

6.2 master2 / master3 配置

只改 name 和 listen/advertise URL 的 IP，其他保持一致。

七、systemd 单元文件

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


[Unit]
Description=Etcd Service
Documentation=https://coreos.com/etcd/docs/latest/
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/etcd --config-file=/etc/etcd/etcd.config.yml
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
Alias=etcd3.service

K8s 默认从 /etc/kubernetes/pki/etcd/ 找 etcd 证书，加软链：

1
2


mkdir -p /etc/kubernetes/pki/etcd
ln -s /etc/etcd/ssl/* /etc/kubernetes/pki/etcd/

八、启动与验证

1
2
3
4


# 所有 master 节点
systemctl daemon-reload
systemctl enable --now etcd.service
systemctl status etcd.service

关键验证（master1 执行）：

1
2
3
4
5
6
7
8


# 注意 v2/v3 API 切换
export ETCDCTL_API=3

etcdctl --endpoints="https://192.168.139.133:2379,https://192.168.139.134:2379,https://192.168.139.135:2379" \
 --cacert=/etc/kubernetes/pki/etcd/etcd-ca.pem \
 --cert=/etc/kubernetes/pki/etcd/etcd.pem \
 --key=/etc/kubernetes/pki/etcd/etcd-key.pem \
 endpoint status --write-out=table

预期输出：

1
2
3
4
5
6
7


+----------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+
| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
+----------------------+------------------+---------+---------+-----------+------------+
| 192.168.139.133:2379 | 67214e12874d646b | 3.5.11 | 29 kB | false | 2 | 8 |
| 192.168.139.134:2379 | a6947d51f82bebc4 | 3.5.11 | 29 kB | false | 2 | 8 |
| 192.168.139.135:2379 | f0598e5ca7a8066f | 3.5.11 | 29 kB | true | 2 | 8 |
+----------------------+------------------+---------+---------+-----------+------------+

关键字段：

IS LEADER：true 表示该节点是当前 leader（Raft 选举结果）
RAFT TERM：选举轮次，term 越大说明发生过越多次选举
DB SIZE：etcd 数据库占磁盘大小

九、故障模拟

9.1 模拟 master1 宕机

1
2


# 在 master1 上
systemctl stop etcd

观察其他节点：

1
2


# 观察 5~10 秒
watch -n 1 "etcdctl endpoint status --cluster --write-out=table"

预期：master1 不可达，master3 仍为 leader（因为 3 节点允许挂 1 台）。

9.2 模拟 master2 也宕机

1
2


# master2
systemctl stop etcd

此时只剩 master1，集群不可用（写操作会失败），但 etcd 不会自动重启——必须人工恢复至少 2 节点。

9.3 恢复

1
2
3


# master2 / master3 启动
systemctl start etcd
# 集群自动重新选主（5~10 秒内）

9.4 灾难恢复：强制重建集群

如果 3 台都挂，etcd 数据还在，但需要 --force-new-cluster 强制单节点启动：

1
2
3
4
5
6


# 改配置
echo "initial-cluster-state: 'existing'" >> /etc/etcd/etcd.config.yml
# 注意 force-new-cluster=true 只能用于一台

# 重启
systemctl start etcd

十、etcdctl 常用命令

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


# 列成员
etcdctl member list

# 健康检查
etcdctl endpoint health --cluster

# 写读测试
etcdctl put /test/foo "hello"
etcdctl get /test/foo

# 备份
etcdctl snapshot save /tmp/etcd-backup.db
etcdctl snapshot status /tmp/etcd-backup.db --write-out=table

# 碎片整理（v3.4 之前需要）
etcdctl defrag

# 告警
etcdctl alarm list
etcdctl alarm disarm

十一、性能调优

参数	含义	默认	调优建议
`heartbeat-interval`	心跳间隔（ms）	100	高延迟网络调大到 200~500
`election-timeout`	选举超时（ms）	1000	至少 5 倍 heartbeat
`quota-backend-bytes`	后端存储限额	2GB	集群 > 8GB 数据调大
`snapshot-count`	触发快照的事务数	100000	写多场景调小到 10000
`max-snapshots`	保留快照数	5	视磁盘空间

关键监控指标：

etcd_disk_wal_fsync_duration_seconds（p99 < 10ms，否则 IO 瓶颈）
etcd_network_peer_round_trip_time_seconds（p99 < 50ms）
etcd_server_has_leader（必须 = 1）
etcd_server_proposals_committed_total / etcd_server_proposals_applied_total（差值 = pending，>5 要警惕）

十二、常见坑

证书 hostname/IP 漏配：peer 通信报 “x509: certificate is valid for …” 错误
firewalld 没关：节点间 2380 端口不通，选举失败
initial-cluster-state: 'new' 重复使用：第二次启动报 “member already exists”，改成 'existing'
etcd 与 apiserver 时钟不同步：证书验证失败，先 ntpdate time1.aliyun.com 对齐
snapshot 备份恢复后集群 ID 变了：用 etcdctl snapshot restore 时记得加 --initial-cluster 和 --initial-advertise-peer-urls

十三、前置知识 / 下一步

前置：

证书签发（cfssl，参考 2020-03-15《K8s 二进制部署》）
K8s 架构基础

下一步：

API Server 高可用（2021-03-15）—— Nginx 四层 + Keepalived VIP
K8s 集群管理（2021-12-15）—— 升级、节点隔离、备份恢复

参考资料

2024+ 视角

etcd 在 2024-2026 年依然是 K8s 数据底座，但生态发生了几个关键变化：

etcd v3.5 全面稳定：v3.5.x 引入的 etcdutl（替代旧 etcdctl 快照管理）、Raft ReadIndex 优化、Learner 节点都已 GA。生产推荐 v3.5.10+（修复了多个 Raft 性能回退问题）。
K8s 1.30+ 的 etcd 管理变更：自 K8s 1.30 起，kubeadm 默认 etcd 容器镜像从 k8s.gcr.io/etcd 切到 registry.k8s.io/etcd，并支持 etcd Learner 节点用于接入已有 etcd 集群（适合 etcd 单独运维团队）。
etcd 性能与碎片整理：v3.4 之前的 defrag 命令在 v3.5 已不再是必须的——v3.5 后端实现了在线碎片回收（QuotaBackendBytes + AutoCompactionMode=periodic）。但 DB Size 超过 quota-backend-bytes 仍会触发告警。
可观测性增强：社区推荐 etcd-dashboard（来自 RedHat）+ Prometheus 抓取 etcd_disk_wal_fsync_duration_seconds、etcd_server_has_leader 等 20+ 关键指标。K8s SIG-Instrumentation 提供官方 kube-etcd-monitor Helm Chart。
替代方案的边界：Kine（将 etcd API 翻译成 SQL）让 MySQL/PostgreSQL 可作为 K8s 后端，但生产级 etcd 仍不可替代——Raft 协议下的强一致 + 低延迟（p99 < 10ms）是 etcd 的护城河。
运维注意：2024 年起，多个 K8s 重大故障源于 etcd 时钟漂移（节点间 NTP 偏差 > 1s 触发 leader 选举）。建议在所有 master 节点部署 chrony 而非 ntpd，并监控 node_timex_offset_seconds。

总之，这篇 2020 年的 etcd 部署骨架至今仍可作为新集群起点，主要补全是：升级到 v3.5.x、用 etcdutl 管理快照、补 Prometheus 监控。

Containerd 实战：手动安装 / 镜像加速 / 客户端工具

Sun, 15 Dec 2019 00:00:00 +0800

写于 2019-12，背景：K8s 1.20 宣布弃用 dockershim（K8s 1.24 正式移除），社区全面转向 containerd / CRI-O。Containerd 成为 K8s 容器运行时的事实标准。

一、为什么选 Containerd

Docker 的架构是"客户端 docker + 守护进程 dockerd + 容器运行时 containerd"。K8s 实际只需要 containerd，于是社区开始鼓励直接用 containerd，跳过 dockerd：

维度	Docker	Containerd
体积	~1GB	~200MB
启动速度	较慢	更快
与 K8s 集成	需要 dockershim（已废弃）	原生 CRI 支持
镜像构建	内置 docker build	需要 buildkit / nerdctl
生态	完整	偏运行时，缺少 CLI

结论：跑 K8s，选 containerd；本机玩镜像构建，继续用 docker。

二、Containerd 安装

2.1 推荐：完整包（cri-containerd-cni）

cri-containerd-cni 一个 tar 包就包含 containerd + runc + CNI 插件 + systemd 配置文件：

1
2
3
4
5
6


# 下载（version 1.7.11）
curl -L -o cri-containerd-cni-1.7.11-linux-amd64.tar.gz \
 https://github.com/containerd/containerd/releases/download/v1.7.11/cri-containerd-cni-1.7.11-linux-amd64.tar.gz

# 解压到根目录（包含 etc/systemd、usr/local/bin、opt/cni 等）
tar Cxzvf / cri-containerd-cni-1.7.11-linux-amd64.tar.gz

解压后的目录结构：

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


/
├── etc
│ ├── cni/net.d/10-containerd-net.conflist
│ ├── crictl.yaml
│ └── systemd/system/containerd.service
├── opt
│ ├── cni/bin/ # CNI 插件（bridge/host-local/loopback 等 16 个）
│ └── containerd/cluster/ # GCE cloud-init 模板
└── usr/local
 ├── bin/containerd, containerd-shim, containerd-shim-runc-v1/v2,
 │ ctr, crictl, critest, ctd-decoder
 └── sbin/runc

2.2 单独装 runc

如果只用 containerd 不需要 runc 二进制，可以单独装：

1
2
3
4
5


wget https://github.com/opencontainers/runc/releases/download/v1.1.11/runc.amd64
mv runc.amd64 /usr/sbin/runc
chmod +x /usr/sbin/runc
runc -v
# runc version 1.1.11 ...

2.3 单独装 CNI 插件

1
2
3
4
5
6


# 下载
wget https://github.com/containernetworking/plugins/releases/download/v1.4.0/cni-plugins-linux-amd64-v1.4.0.tgz

# 解压到 /opt/cni/bin
mkdir -p /opt/cni/bin
tar Cxzvf /opt/cni/bin cni-plugins-linux-amd64-v1.4.0.tgz

CNI 插件（16 个）包括：bandwidth / bridge / dhcp / firewall / host-device / host-local / ipvlan / loopback / macvlan / portmap / ptp / sbr / static / tuning / vlan / vrf。

三、生成配置文件

Containerd 默认不带配置文件，需要手动生成：

1
2
3
4
5


# 创建配置目录
mkdir /etc/containerd

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

关键配置项

1. 镜像加速（国内必须）：

1
2


[plugins."io.containerd.grpc.v1.cri".registry]
 config_path = "/etc/containerd/certs.d"

2. sandbox_image（K8s 启动 Pod 用的 pause 镜像）：

1
2


[plugins."io.containerd.grpc.v1.cri"]
 sandbox_image = "registry.aliyuncs.com/google_containers/pause:3.9"

3. SystemdCgroup（K8s 推荐用 systemd cgroup driver）：

1
2


[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
 SystemdCgroup = true

启动服务

1
2
3


systemctl daemon-reload
systemctl enable --now containerd
systemctl status containerd

四、镜像加速配置

Containerd 的镜像加速基于 hosts.toml 机制，类似 nginx 的 upstream。/etc/containerd/certs.d/ 下的每个域名一个目录：

4.1 docker.io 加速

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


mkdir -p /etc/containerd/certs.d/docker.io
cat > /etc/containerd/certs.d/docker.io/hosts.toml << EOF
server = "https://docker.io"
[host."https://dockerproxy.com"]
 capabilities = ["pull", "resolve"]
[host."https://docker.m.daocloud.io"]
 capabilities = ["pull", "resolve"]
[host."https://reg-mirror.qiniu.com"]
 capabilities = ["pull", "resolve"]
[host."https://registry.docker-cn.com"]
 capabilities = ["pull", "resolve"]
[host."http://hub-mirror.c.163.com"]
 capabilities = ["pull", "resolve"]
EOF

4.2 K8s 官方镜像加速

registry.k8s.io 和 k8s.gcr.io 是 K8s 组件（apiserver、controller-manager、coredns、metrics-server）默认镜像源，国内必须加速：

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


# registry.k8s.io
mkdir -p /etc/containerd/certs.d/registry.k8s.io
cat > /etc/containerd/certs.d/registry.k8s.io/hosts.toml << EOF
server = "https://registry.k8s.io"
[host."https://k8s.m.daocloud.io"]
 capabilities = ["pull", "resolve", "push"]
EOF

# k8s.gcr.io（部分旧镜像）
mkdir -p /etc/containerd/certs.d/k8s.gcr.io
cat > /etc/containerd/certs.d/k8s.gcr.io/hosts.toml << EOF
server = "https://k8s.gcr.io"
[host."https://k8s-gcr.m.daocloud.io"]
 capabilities = ["pull", "resolve", "push"]
EOF

4.3 其他常用仓库加速

按需配置 docker.elastic.co（ES 镜像）、gcr.io（Google 容器）、ghcr.io（GitHub 容器）、quay.io（Red Hat 镜像）、nvcr.io（NVIDIA GPU 镜像）、mcr.microsoft.com（微软镜像）等等。模板都是一样的：

1
2
3
4
5
6
7


# 通用模板
mkdir -p /etc/containerd/certs.d/<REGISTRY>
cat > /etc/containerd/certs.d/<REGISTRY>/hosts.toml << EOF
server = "https://<REGISTRY>"
[host."https://<REGISTRY>.m.daocloud.io"]
 capabilities = ["pull", "resolve", "push"]
EOF

重启生效：systemctl restart containerd

五、客户端工具三件套

Containerd 自带 3 个客户端，各有分工：

5.1 ctr（containerd 自带）

Containerd 原生 CLI，功能最全但最不友好：

1
2
3
4
5
6
7
8


# 拉镜像
ctr -n k8s.io images pull docker.io/library/nginx:1.25

# 跑容器（无 namespace）
ctr run -d docker.io/library/redis:7 redis-server

# 列出镜像
ctr images ls

ctr 没有 docker CLI 的 run / ps / exec 那种"一体化"体验，调试不直观。

5.2 crictl（K8s 调试专用）

K8s 官方推荐的 CRI 客户端，专用于排查 K8s 节点问题：

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


# 配置 runtime endpoint
crictl config runtime-endpoint unix:///var/run/containerd/containerd.sock
# 生成的配置在 /etc/crictl.yaml

# 列出 Pod/容器/镜像
crictl pods -A
crictl ps -a
crictl images

# 拉镜像
crictl pull nginx:1.25

# 看容器日志
crictl logs <container-id>

# exec 进容器
crictl exec -it <container-id> sh

什么时候用 crictl？ 当你 SSH 进 K8s worker 节点，Pod 起不来，需要直接查 containerd 里的容器状态。

5.3 nerdctl（Docker 体验，containerd 后端）

nerdctl 是 containerd 官方的"Docker 兼容"客户端，命令几乎和 docker 一致：

1
2
3
4
5
6
7
8
9


# 安装
wget https://github.com/containerd/nerdctl/releases/download/v1.7.6/nerdctl-1.7.6-linux-amd64.tar.gz
tar xf nerdctl-1.7.6-linux-amd64.tar.gz -C /usr/local/bin

# 用法跟 docker 几乎一样
nerdctl run -d -p 80:80 nginx:alpine
nerdctl ps
nerdctl logs <container>
nerdctl exec -it <container> sh

nerdctl vs ctr：ctr 是给 containerd 开发者用的，nerdctl 是给应用运维用的，学习曲线 = docker 经验。

六、Containerd 在 K8s 中的角色

K8s 1.24+ 不再内置 dockershim，需要 containerd / CRI-O / Docker Engine (with cri-dockerd) 三选一：

1
2
3
4
5


kubelet (K8s 节点)
 ↓ CRI (gRPC)
containerd
 ↓ OCI
runc → 容器进程

kubelet 通过 CRI（Container Runtime Interface）调用 containerd，containerd 内部用 runc 启动容器。用户不需要再写 docker build——镜像可以用 buildah、buildkit、kaniko 在 CI 里构建。

七、常见坑

镜像加速不生效：hosts.toml 路径错了（应是 /etc/containerd/certs.d/<registry>/ 不是 /etc/docker/）
crictl 报 connection refused：runtime-endpoint 没配对，crictl 默认走 dockershim，现在要改成 unix:///var/run/containerd/containerd.sock
SystemdCgroup 没开：cgroup driver 不一致，kubelet 起不来，日志里能看到 “cgroup driver “cgroupfs” differs from kubelet”
pause 镜像拉不到：sandbox_image 默认是 k8s.gcr.io/pause:3.5，国内必须改成阿里云

八、前置知识 / 下一步

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

下一步：

K8s 二进制部署（2020-03-15）—— Containerd 作为容器运行时的完整部署
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、可视化运维这三层。

ProtoBuf & gRPC 实战：proto3 时代的跨语言 RPC 与数据建模

Sun, 15 Oct 2017 00:00:00 +0800

ProtoBuf & gRPC 实战：proto3 时代的跨语言 RPC 与数据建模

TL;DR：ProtoBuf 是一类语言无关、平台无关、可扩展的二进制结构化数据序列化方法，比 XML 小 3 ~ 10 倍、快 20 ~ 100 倍。2017 年是它真正"工业化"的一年——gRPC 1.0（2017-08 GA）、protoc-gen-validate（2017-08 开源）、Envoy 1.0（2017-09）先后落地，proto3 也从 2016-07 GA 后成为默认语法。本文用 5 个心智模型 + 一组完整示例，讲清 proto3 的数据建模、字段类型、嵌套、Map、service 与四种流模式。

一、为什么需要 ProtoBuf（When to use）

在微服务、跨端通信、持久化序列化场景中，传统 JSON / XML 是人类友好但机器低效的格式：

体积：JSON 里一个 int 字段最少 1~~11 字节，ProtoBuf 用变长编码通常 1~~5 字节
速度：XML 解析要遍历 DOM，ProtoBuf 直接按 schema 二进制切片
类型安全：JSON 拿到的是字符串，ProtoBuf 拿到的是强类型对象
演进能力：ProtoBuf 通过**字段编号（field number）**支持前向/后向兼容，新增字段不会破坏旧客户端

典型适用场景（2017 视角）：

微服务间 RPC——gRPC 1.0（2017-08）以 ProtoBuf 作为 IDL 和默认序列化器，跨语言、强类型、双向流
消息队列载荷——Kafka 早已支持 ProtoBuf，Pulsar（2016-09 在 Yahoo! 开源、2017 年逐步成熟）也提供 schema registry 与 ProtoBuf 集成
K8s 内部通信——Kubernetes 1.0（2015-07 GA）以来，所有 API 资源（Pod、Service、Deployment…）的 schema 都用 ProtoBuf 定义，apiserver 与 kubelet、scheduler、controller-manager 之间走 ProtoBuf over HTTP/2
Service Mesh 数据面——Envoy（2017-09 发布 v1.0）的 xDS（LDS/RDS/CDS/EDS）API 全部基于 ProtoBuf，Istio 等控制面通过 xDS 下发配置
跨语言 SDK 数据交换——前端、移动端、后端用同一份 .proto 各自生成代码
移动端与后端通信——节省流量、电量

不适用场景：

需要人类可读的配置（用 YAML / TOML）
Web 前端到后端的标准通信（JSON 更通用）
一次性、小数据量、无演进需求的传输

二、ProtoBuf 速览

一个数据交换的协议

protocol buffers（ProtoBuf）是一种语言无关、平台无关、可扩展的序列化结构数据的方法，可用于（数据）通信协议、数据存储等。

是一种灵活、高效、自动化机制的结构数据序列化方法——可类比 XML，但比 XML 更小（3 ~ 10 倍）、更快（20 ~ 100 倍）、更简单。

JSON / XML 都是基于文本格式，ProtoBuf 是二进制格式。

三、proto3 速览：与 proto2 的关键差异

2016-07 proto3 正式 GA，并成为 protoc 的默认语法。和 proto2 相比，proto3 的核心简化是：

维度	proto2	proto3
默认语法	需显式 `syntax = "proto2"`	2016-07 后默认为 proto3
字段是否存在	区分 `optional` / `required` / 默认	没有 `required`，字段默认"存在与否"用 `optional` 关键字显式标注（proto3 默认字段可以被设默认值以"不编码"）
默认值	0 / 空字符串	同上，但未设置字段不会被序列化（节省体积）
枚举	第一个值必须为 0	同上，但首成员必须为 0，且枚举值在 wire format 中是 varint
未知字段	解析时默认保留	解析时不保留未知字段（演进更严格）
`map` 支持	旧版本不支持	原生支持 `map<K, V>`
`Any` 类型	需 `google/protobuf/any.proto` 扩展	官方内置 `google.protobuf.Any`
时间戳	同上	同上，但官方推荐 `google.protobuf.Timestamp`
JSON 映射	需插件	官方 `proto3 <-> JSON` 映射规范

实战建议：新项目一律 syntax = "proto3"；维护老服务再保留 proto2。

四、第一个 .proto：消息定义

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


// 指定 proto3 语法（2016-07 后是默认，但显式声明更稳）
syntax = "proto3";

package foo.bar; // 包名避免同名 Message 冲突

// option 可用于 proto、message、enum、service 的 scope

// Message ≈ Java 的 class / C 的 struct
message Response {
 // 字段 = 类型 + 名字 + 序号（序号是 wire format 的"身份证"，绝不能改）
 string data = 1;
 int32 status = 2;
}

关键约定：

package：避免命名空间冲突
message：数据结构的最小单元
字段序号 = 1, = 2, ...：一旦发布就不可修改、不可复用——这是 ProtoBuf 演进能力的根基
syntax = "proto3"：2017 主流；不写时 2017 之后的 protoc 默认按 proto3 解析

五、编译器：.proto → 目标语言

官方编译器 protoc 仓库：https://github.com/protocolbuffers/protobuf/releases

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


# 安装 protoc 后，生成 Java 代码到当前目录
protoc --java_out=. response.proto

# 生成 Go 代码
protoc --go_out=. --go_opt=paths=source_relative response.proto

# 生成 Python 代码
protoc --python_out=. response.proto

# 生成 C++ 代码
protoc --cpp_out=. --proto_path=. response.proto

# 生成 gRPC 桩代码（protoc + 插件 grpc-plugin，gRPC 1.0 GA 后官方推荐）
protoc --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_cpp_plugin` response.proto

小贴士：生成的代码不要手动改——下次 protoc 会被覆盖。业务代码继承/组合生成的类即可。

六、数据类型映射表

proto 类型	说明	java 类型	golang 类型
`double`	双精度浮点	`double`	`float64`
`float`	单精度浮点	`float`	`float32`
`int32`	变长编码，对负值效率低，负值请用 `sint32`	`int`	`int32`
`uint32`	变长编码	`int`	`uint32`
`uint64`	变长编码	`long`	`uint64`
`sint32`	变长编码，负值比 int32 高效	`int`	`int32`
`sint64`	变长编码，有符号	`long`	`int64`
`fixed32`	固定 4 字节，值域常大于 2²⁸ 时比 `uint32` 高效	`int`	`uint32`
`fixed64`	固定 8 字节，值域常大于 2²⁵⁶ 时比 `uint64` 高效	`long`	`uint64`
`sfixed32`	固定 4 字节	`int`	`int32`
`sfixed64`	固定 8 字节	`long`	`int64`
`bool`	布尔	`boolean`	`bool`
`string`	必须 UTF-8 或 7-bit ASCII	`String`	`string`
`bytes`	任意二进制（文件、图片）	`ByteString`	`[]byte`

实战口诀：负数 → sint32/sint64；大正整数 → fixed32/fixed64；其余 → int32/uint32。

七、枚举、数组、嵌套、导入

7.1 枚举

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


syntax = "proto3";

enum PhoneType { // 枚举首成员必须为 0，且值唯一
 MOBILE = 0;
 HOME = 1;
 WORK = 2;
}

message PhoneNumber {
 string number = 1;
 PhoneType type = 2;
}

7.2 数组（repeated）

1
2
3
4
5


message Msg {
 repeated int32 arrays = 1; // 整数数组
 repeated string names = 2; // 字符串数组
 repeated PhoneNumber phones = 3;
}

7.3 嵌套消息 vs 跨文件导入

1
2
3
4
5
6
7
8
9


// 嵌套：把 Result 写进 SearchResponse 内部
message SearchResponse {
 message Result {
 string url = 1;
 string title = 2;
 repeated string snippets = 3;
 }
 repeated Result results = 1;
}

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


// 跨文件导入：把 Result 抽到 result.proto
// result.proto
syntax = "proto3";
package foo.bar;
message Result {
 string url = 1;
 string title = 2;
 repeated string snippets = 3;
}

// search_response.proto
syntax = "proto3";
package foo.bar;
import "result.proto";
message SearchResponse {
 repeated Result results = 1;
}

proto3 中不允许直接嵌套枚举（嵌套 enum 必须先 message 包一层），这是与 proto2 的小差异。

八、Map / 时间戳 / Any

8.1 Map 类型

1
2
3
4
5
6
7


syntax = "proto3";

message Product {
 string name = 1;
 // key 不能是浮点 / bytes / enum；value 不能是另一个 map
 map<string, string> attrs = 2; // 商品属性 K/V
}

Map 字段不能用 repeated 修饰；map 不能迭代顺序依赖。

8.2 时间戳

1
2
3
4
5
6
7


syntax = "proto3";

import "google/protobuf/timestamp.proto";

message MyMessage {
 google.protobuf.Timestamp my_field = 1;
}

简单场景可直接用 int64 时间戳（毫秒/秒），看团队约定。

8.3 Any 任意类型

1
2
3
4
5


// Any 可以承载 .proto 未定义的任意内置类型
message ErrorStatus {
 string message = 1;
 repeated google.protobuf.Any details = 2;
}

K8s API 的 runtime.RawExtension 字段底层就是 Any——apiserver 把不识别的对象原样塞进去。

九、定义服务

proto3 原生支持 service 定义，与 gRPC 1.0 配合即可生成跨语言 RPC 桩代码：

1
2
3


service SearchService {
 rpc Search (SearchRequest) returns (SearchResponse);
}

gRPC 1.0（2017-08）默认走 HTTP/2 + ProtoBuf，这是 ProtoBuf 在 RPC 领域最主流的落地形态。

十、stream 关键字：四种流模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 客户端推 → 服务端（client-side streaming）
rpc GetStream (StreamReqData) returns (stream StreamResData) {}

// 服务端推 → 客户端（server-side streaming）
rpc PutStream (stream StreamReqData) returns (StreamResData) {}

// 双向流（bidirectional streaming）
rpc AllStream (stream StreamReqData) returns (stream StreamResData) {}

// 单调用（非流式）
rpc Unary (UnaryReq) returns (UnaryRes);

典型场景：

客户端流：IoT 设备上报（go2rtc 这类轻量级流媒体代理 / RTSP-over-WebRTC 设备采集后的元数据上报就属于这一类）
服务端流：股票行情、消息推送、K8s watch API
双向流：聊天、协同编辑、Envoy xDS（控制面 ↔ 数据面长连接推送配置）
单调用：普通 RPC

Envoy 1.0 的 xDS（LDS/RDS/CDS/EDS）正是 gRPC 双向流的典型案例——控制面（Istio Pilot 等）通过 gRPC stream 主动推送配置变更给数据面（Envoy）。

十一、数据校验：protoc-gen-validate（2017-08）

ProtoBuf 本身不包含字段值校验（最小值、最大值、长度、枚举合法性等）。2017-08 开源的 protoc-gen-validate（Envoy 项目出品）补齐了这一点：

仓库：https://github.com/envoyproxy/protoc-gen-validate

 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


syntax = "proto3";

package foo.bar;

import "validate/validate.proto";

message CreateUserRequest {
 // 用户名：3~32 字符，正则限制
 string username = 1 [
 (validate.rules).string = {
 min_len: 3
 max_len: 32
 pattern: "^[a-zA-Z0-9_]+$"
 }
 ];

 // 年龄：0~150
 int32 age = 2 [(validate.rules).int32 = {gte: 0, lte: 150}];

 // 邮箱：必须是 email 格式
 string email = 3 [(validate.rules).string = {email: true}];

 // 列表元素非空、长度限制
 repeated string tags = 4 [
 (validate.rules).repeated = {
 min_items: 1
 max_items: 10
 items: {string: {min_len: 1, max_len: 32}}
 }
 ];
}

1
2
3
4
5
6
7


# 安装 protoc-gen-validate 后，protoc 会生成带校验逻辑的桩代码
protoc \
 -I . \
 -I /path/to/protoc-gen-validate \
 --go_out=. \
 --validate_out=lang=go,paths=source_relative:. \
 create_user.proto

相比 JSR 303 Bean Validation（Java 生态），protoc-gen-validate 的优势是校验规则写在 .proto 里、跨语言、跨 RPC 框架一致——这正是 2017 年 gRPC + Envoy 生态推崇的"单一来源"做法。

十二、现代基础设施里的 ProtoBuf

2017 年这个时间点，ProtoBuf 已经不只是"序列化格式"，而是分布式系统的事实 IDL。

12.1 Kubernetes：所有 API 资源都是 ProtoBuf

Kubernetes 1.0（2015-07 GA）以来，所有 API 资源（Pod、Service、Deployment…）的 schema 都定义在 k8s.io/api 仓库的 .proto 文件中：

apiserver ↔ kubelet / scheduler / controller-manager：通过 HTTP/2 + ProtoBuf 通信
CRD / Operator：用户自定义资源也走 .proto（或 OpenAPI 自动生成）
kubectl：本地构造 ProtoBuf 对象 → 走 apiserver 序列化

典型 .proto 片段（简化版）：

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


// k8s.io/api/core/v1/generated.proto
syntax = "proto3";
package k8s.io.api.core.v1;

import "k8s.io/apimachinery/pkg/runtime/generated.proto";

message Pod {
 map<string, string> labels = 1;
 map<string, string> annotations = 2;
 PodSpec spec = 3;
 PodStatus status = 4;
}

12.2 gRPC：ProtoBuf 跨语言 RPC 的事实标准

gRPC 1.0（2017-08 GA）由 Google 开源（2015 年从内部 Stubby 演进，移到 GitHub），以 ProtoBuf 作为 IDL 和默认序列化：

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


// user.proto
syntax = "proto3";

package user;

service UserService {
 // 单调用
 rpc GetUser (GetUserRequest) returns (User);
 // 服务端流
 rpc ListUsers (ListUsersRequest) returns (stream User);
 // 客户端流
 rpc CreateUsers (stream User) returns (CreateUsersResponse);
 // 双向流
 rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

message User { string id = 1; string name = 2; }

gRPC 关键特性：

HTTP/2 多路复用
ProtoBuf 二进制序列化
双向流、四种流模式
自动生成 10+ 语言桩代码（Java/Go/C++/Python/Ruby/Node/PHP/C#/Dart/Android-Java）
截止时间（deadline）、取消、metadata 等通用拦截语义

12.3 Pulsar：消息总线里的 ProtoBuf

Apache Pulsar（2016-09 在 Yahoo! 开源、2017 年逐步孵化成 Apache 顶级项目）原生支持 ProtoBuf schema：

内置 Schema.PROTOBUF，producer / consumer 用 .proto 自动反序列化
与 SchemaRegistry 配合做 schema 演进
消息载荷紧凑、跨语言、多租户隔离

12.4 Envoy / xDS：Service Mesh 的数据面 API

Envoy（Lyft 开源，2017-09 发布 v1.0）的 xDS 协议族是 gRPC + ProtoBuf 的工业级范本：

LDS（Listener Discovery Service）：下发监听器配置
RDS（Route Discovery Service）：下发路由配置
CDS（Cluster Discovery Service）：下发集群配置
EDS（Endpoint Discovery Service）：下发端点配置

控制面（Istio Pilot 等）通过 gRPC 双向流把 ProtoBuf 消息增量推送给数据面（Envoy），实现配置热更新。

这套 xDS 协议后来成为 Istio（2017-05 由 Google/IBM/Lyft 联合开源）的核心数据面 API。

12.5 IoT / 视频流场景

ProtoBuf 在 IoT 与视频流领域的应用同样广泛——比如轻量级流媒体代理在设备元数据、控制信令、配置同步上都会用 .proto 定义设备能力集，避免重复造轮子。go2rtc 这类工具虽然面世更晚，但同样遵循"ProtoBuf 作为控制面信令、媒体流走 RTSP/WebRTC"的分层思路。

十三、协议升级的视角：IPv4→IPv6 给我们的启示

2017 年前后正值 IPv6 规模部署讨论。把网络协议和序列化协议放一起看，能发现共通的设计哲学：

协议升级对现有程序的影响（参考 IPv4→IPv6）

地址格式的硬编码问题——视频监控、配置文件、程序中字面量硬编码
网络 API / 库的协议版本依赖——Java 库要使用更通用的 InetAddress；Go 视频播放客户端优先 net.LookupIP 同时解析 A 与 AAAA
地址解析与 DNS 交互逻辑——程序需支持"双 DNS 查询"（同时请求 A 和 AAAA 记录）
操作系统层面支持
运行时 / 容器——Java 需确保 java.net.preferIPv6Addresses=true；libc 解析器需开启 getaddrinfo 的 AI_ADDRCONFIG；Docker / K8s 需配置 IPv6 网络模式（--ipv6 flag、CNI 插件）
防火墙规则——IPv4 规则需重新配置 IPv6 专属规则

升级建议路径：

阶段	目标
第一阶段	支持双栈兼容（IPv4/IPv6 并存）
第二阶段	修复IPv6 专属问题（DNS、MTU、链路本地地址）
第三阶段	全量 IPv6，下线 IPv4

类比到 ProtoBuf：

第一阶段（双栈）：旧字段保留 + 新字段加 optional 标注
第二阶段（修复兼容问题）：使用 reserved 关键字冻结废弃字段编号（防止误用）

1
2
3
4
5
6
7


message User {
 reserved 5, 7, 9 to 11; // 保留字段编号，未来也不能用
 reserved "old_name", "old_email"; // 保留字段名

 string name = 1;
 string email = 2;
}

第三阶段（全量）：灰度下架旧字段、提供 schema 校验工具

十四、常见 5 个坑

#	坑	现象	对策
1	修改已发布字段的序号	旧客户端解码新数据字段错位、值乱跳	一旦发布，序号就是合约；只能加新字段 + 用 `reserved` 废弃旧的
2	误用 `int32` 存负数	负数被编码为 10 字节超大无符号数	负数统一用 `sint32` / `sint64`
3	`string` 字段塞非 UTF-8	反序列化报错、跨语言崩溃	文本类字段用 `string`；二进制用 `bytes`
4	`repeated` 字段不设上限	大消息体 OOM、带宽爆炸	在 `Service` 入口拦截层加 `Collection.size()` 校验；或用 `protoc-gen-validate` 的 `repeated.min_items` / `max_items` 限制
5	proto2 / proto3 混用	wire format 行为不同，反序列化失败	团队统一 `syntax = "proto3"`；proto2 仅在维护老服务时保留

十五、核心 6 点速记

字段编号 = 合约：一旦发布就不可改；用 reserved 冻结废弃编号
负数用 sint：变长编码对负值有专门优化
stream 关键字：四种流模式决定 ProtoBuf 自带 RPC 通信方向——gRPC 1.0 把它变成跨语言标准
校验靠 protoc-gen-validate：2017-08 开源，跨语言、.proto 单一来源，比 JSR 303 更适合 gRPC 时代
现代基础设施统一用 .proto 作为 IDL：K8s API、Pulsar schema、Envoy xDS、gRPC、CRD
演进式升级：双栈 → 修复 → 全量，与 IPv4→IPv6 的协议升级哲学一致

十六、参考资料

ProtoBuf 官方仓库：https://github.com/protocolbuffers/protobuf
protoc 发布页：https://github.com/protocolbuffers/protobuf/releases
gRPC 1.0 公告：https://grpc.io/blog/grpc-1-0-goes-ga/
gRPC 仓库：https://github.com/grpc/grpc
protoc-gen-validate：https://github.com/envoyproxy/protoc-gen-validate
Envoy 仓库：https://github.com/envoyproxy/envoy
xDS 协议：https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/xds_api
Kubernetes API 源码：https://github.com/kubernetes/api
Apache Pulsar：https://pulsar.apache.org/
Any 类型：https://developers.google.com/protocol-buffers/docs/proto#any

Kubernetes 入门：何时需要 K8s 与集群架构总览

Thu, 15 Jun 2017 00:00:00 +0800

写于 2017-06，背景：Kubernetes 1.7 刚 GA、Docker Swarm 还在与 K8s 掰手腕，etcd v3.2、Helm v2 已经成熟。本文聚焦"为什么需要 K8s"与"集群由哪些组件组成"，帮你建立全局视图。

一、为什么需要 Kubernetes

应用在不同规模下，对"运行环境"的需求完全不同：

规模	解决方案	痛点
1 台机器	docker + docker-compose	一台机器上启动 N 个容器，简单直接
3~5 台	每台单独配置 + 负载均衡器	应用升级、机器扩容、版本回滚需要手工操作
十几到几十台	重复性脚本 + Ansible	加机器 1 小时、版本回滚半小时、灰度发布？祈祷吧
上百到上千台	Kubernetes	一个 `kubectl scale` 完成扩容、`kubectl rollout undo` 完成回滚

Kubernetes（k8s） 是 Google 在 2014 年开源的容器编排系统（2015-07 v1.0 GA），前身是 Borg 系统。它的目标很简单：让你像操作一台机器一样操作上千台机器组成的集群。

“谈笑间，樯橹灰飞烟灭”——加机器、版本升级、灰度发布，都只是一个 YAML + 一个命令的事。

二、集群架构总览

K8s 集群分两类节点：

master（主节点）：控制平面，不跑业务负载，通常 1 个或 3 个（高可用）
worker（工作节点）：跑 Pod，可以是虚拟机或物理机，可以不断加

2.1 核心组件

组件	角色
`kube-apiserver`	API 服务器，对外暴露 Kubernetes HTTP API，是整个集群的"门卫"
`etcd`	分布式键值数据库，保存集群所有状态（Pod、Service、ConfigMap 等）
`kube-scheduler`	调度器，决定 Pod 调度到哪个 worker 节点
`kube-controller-manager`	控制器集合（Deployment/Node/Endpoint 等 30+ 控制器）
`cloud-controller-manager`	与云服务商集成（负载均衡、存储卷、节点生命周期）
`kubelet`	worker 节点上的"代理"，负责 Pod 生命周期
`kube-proxy`	worker 节点上的网络代理，维护 iptables/IPVS 规则
`container runtime`	容器运行时（containerd / CRI-O / Docker），真正运行容器

2.2 Pod 是什么

Pod 是 K8s 调度和管理的最小单位，不是容器。

一个 Pod 可以包含 1 个或多个容器
同一个 Pod 里的容器共享网络（同一个 IP）、存储卷、生命周期
Pod 有自己的虚拟 IP（ClusterIP）
主节点根据资源、亲和性、污点等策略，把 Pod 调度到合适的 worker

把 Pod 想象成"一个逻辑主机"，里面的容器就像同一台机器上的进程——它们共享网络、可以本地通信。

三、kubectl 速查

kubectl 是 K8s 的命令行工具，几乎所有操作都通过它完成。

3.1 查看基本信息

1
2
3
4
5
6
7
8


# 客户端 + 服务端版本
kubectl version

# 可用 API 版本
kubectl api-versions

# 某个资源类型的字段说明
kubectl explain deployment.apiVersion

3.2 命名空间

1
2
3
4
5
6
7
8


# 查所有命名空间下的资源
kubectl get all -o wide -A

# 查某个命名空间
kubectl get all -o wide -n test

# 删除命名空间（会删除里面所有资源）
kubectl delete ns dev

3.3 Pod 操作

1
2
3
4
5
6
7
8


# 强制删除卡在 Terminating 的 Pod
kubectl delete pods nacos-846d6cd5f7-t7h2x -n dev --grace-period=0 --force

# 查看 Pod 日志
kubectl logs -f pod-name -n namespace

# 进入 Pod 终端
kubectl exec -it pod-name -n namespace -- sh

3.4 资源缩写

资源	缩写
pods	po
services	svc
deployments	deploy
namespaces	ns
nodes	no
configmaps	cm
persistentvolumes	pv

四、版本节奏

K8s 一年发布 3 个版本（1.x 时代），从 1.28 起改为每年 4 个版本：

大版本	GA 时间	维护状态
1.28	2023-08-16	支持到 2024-10-28
1.27	2023-06-14	支持到 2024-06-28
1.26	2022-12-08	支持到 2024-02-28
1.25	2022-08-23	已 EOL

版本约定：x.y.z，x 是大版本，y 是次要版本，z 是补丁版本。例如 1.28.5 是 1.28 的第 5 个补丁。

升级建议：生产集群不要追新，每年升 1~2 个次要版本即可。大版本升级前必须看 CHANGELOG 里 kubelet 参数、API 废弃、依赖变化。

五、何时不该上 K8s

不是所有场景都适合 K8s：

单机应用：直接 docker-compose，引入 K8s 反而增加复杂度
状态强一致的服务（如传统 MySQL 主从）：运维复杂度高，不如托管 RDS
小团队（< 5 人）：学习曲线陡峭，K8s 本身的运维成本可能高于业务价值
没有 DevOps 文化：K8s 是工具，本质还是要 CI/CD + GitOps + 监控告警体系

决策树：

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


应用规模 → 单机？
 ↓ yes
 docker-compose
 ↓ no
应用规模 → 3~10 台？
 ↓ yes
 docker swarm 或 k3s（轻量）
 ↓ no
业务高可用要求？
 ↓ 高
 Kubernetes（生产集群 + 高可用 + GitOps）
 ↓ 低
 k3s / kubeadm 单 master

六、前置知识 / 下一步

前置：

熟练使用 Docker（构建镜像、容器操作、网络模式）
理解 Linux 网络（iptables、IPVS、网桥）
掌握至少一种证书签发工具（cfssl / openssl）

下一步：

K8s 工具链速装（2018-12-15）—— kubectl / kubeadm / minikube / helm 一文搞定
二进制部署完整路径（2020-03-15）—— 理解集群组件如何协作
Kubeadm 一键部署（2022-06-15）—— 生产环境最常见的部署方式

参考资料

2024+ 视角

2017 年的 K8s 1.7 时代组件到 2024-2026 年的 1.30-1.32 时代，主要变化如下：

版本节奏从 1.28 起改为每年 4 个 minor 版本（之前 3 个），EOL 窗口从 9 个月延长到 14 个月。生产规划可按"每年升 2 个 minor"来排。
sidecar 容器 GA（1.28-1.29）：原生 sidecarContainers 字段替代了"边车 hack"（同 Pod 多个 initContainer），Lifecycle Hook 触发更可靠，影响了 Istio/Envoy 链路代理的部署方式。
Gateway API 1.0 GA（2024）：Ingress 资源正式进入"维护模式"，新部署推荐 Gateway + HTTPRoute。Cilium、Istio、Contour、Traefik 都已全面支持。
容器运行时全面 containerd：Docker Shim 在 1.24 已移除，1.30+ 集群几乎全部使用 containerd / CRI-O。nerdctl 替代 docker CLI。
Pod Scheduling 进化：K8s 1.30 GA 的 DRA（Dynamic Resource Allocation） 让 GPU/NPU 等异构资源调度更精细；noderelabeling 与 Scheduling Framework 扩展点稳定，Karpenter / Kueue 等调度器大规模落地。
可观测性标配：OpenTelemetry 取代 OpenTracing/Jaeger 客户端，K8s 1.30+ 的 APIServerTracing 默认开启 OTLP 导出，配合 Pixie / eBPF 实现无侵入链路追踪。
生产默认配置变化：PodSecurityPolicy 1.25 移除，全面改用 PSA（Pod Security Admission） + pod-security.kubernetes.io/enforce=restricted；--feature-gates=RemoveSelfLink=false 之类的旧开关已被清理。

结论：2017 年这篇文章的"集群组件图"和"kubectl 速查"基本功没有过时，但落地工具链（Ingress→Gateway、Docker→containerd、PSP→PSA）需要 2024 视角的更新。

字段	`extensions/v1beta1`（已弃用）	`networking.k8s.io/v1`（本文用）
apiVersion	`extensions/v1beta1`	`networking.k8s.io/v1`
路径匹配	`path: /foo`（隐式 Prefix）	`path: /foo` + `pathType: Prefix \| Exact \| ImplementationSpecific`（必填）
后端	`backend.serviceName` + `servicePort`	`backend.service.name` + `backend.service.port.number/name`
Ingress 类	注解 `kubernetes.io/ingress.class: nginx`	`spec.ingressClassName: nginx`