> **本文是「架构实战·第二季」第 46 篇**，也是云原生进阶系列的收官篇。云厂商托管 K8s 升个版本点一下就行，但**自建 K8s 集群**从 1.27 升到 1.31，要跨 4 个版本、跨 12 个月、跨 4 个 K8s API 弃用周期——这篇文章把"平滑演进"的完整方法论讲清楚。

---

## 引子：那次升 1.28 翻车事件

2024 年 3 月，我们接到集团"全集群升 1.28"的指令。当时觉得："不就升个小版本吗，kubeadm 跑一下不就行了？"

结果：

- **第 1 个集群**：顺利升完，业务无感；
- **第 2 个集群**：升完后，某个有状态应用的 Pod 起不来了，错误是 `FailedMount: mount failed: operation not supported`；
- **第 3 个集群**：控制面升级到 1.28 后，应用还是 1.27 的 kubelet，连不上 API Server。

排查发现：

1. 1.28 改了 mount 行为，老的 CSI driver 不兼容；
2. 集群是"控制面 1.28 + 数据面 1.27" 状态，kubelet 和 API Server 版本差超过 3 个小版本，API 协商失败。

那次复盘后，我们定下了**严格的"控制面/数据面错开升级"流程**，再没出过事。

---

## 一、K8s 版本升级的两个维度

### 1.1 控制面升级（API Server / etcd / Controller Manager）

控制面是"集群大脑"，升级时**整个集群 API 行为可能变化**。

```
API Server 1.27 → 1.28 → 1.29 → 1.30 → 1.31
  ↓
  Pod 调度、Service 路由、CRD 校验、资源限制……
```

### 1.2 数据面升级（kubelet / kube-proxy / 容器运行时）

数据面是"集群肌肉"，升级影响**单个节点**：

```
kubelet 1.27 → 1.28
  ↓
Pod 启动/停止行为、容器运行时、卷挂载……
```

**核心原则**：

- **控制面先升，数据面后升**；
- **每个组件之间的版本差 ≤ 3 个 minor 版本**；
- **一次只升一个 minor 版本**（不要从 1.27 直接升 1.31）。

### 1.3 升级路线图

```
1.27 → 1.28 → 1.29 → 1.30 → 1.31
        ↓
    每步间隔 2 周（生产）
    每步间隔 1 周（预发布）
```

K8s 官方支持每个版本 14 个月（含 3 个月升级窗口）。**1.27 已经 EOL，必须升**。

---

## 二、升级前的"考古"工作

### 2.1 查 API 弃用清单

```bash
# 安装 kubectl-plugins
kubectl krew install deprecations

# 检查当前集群的 API 弃用情况
kubectl deprecations
```

输出类似：

```
WARNING: PodSecurityPolicy is deprecated in v1.25 and will be removed in v1.28
WARNING: extensions/v1beta1 Ingress is removed in v1.22
WARNING: rbac.authorization.k8s.io/v1beta1 is removed in v1.22
```

**重点关注**：

| API | 弃用版本 | 移除版本 |
|-----|---------|---------|
| PodSecurityPolicy | 1.21 | **1.25** |
| Ingress `extensions/v1beta1` | 1.14 | 1.22 |
| CronJob `batch/v1beta1` | 1.21 | 1.25 |
| PodDisruptionBudget `policy/v1beta1` | 1.21 | 1.25 |
| HorizontalPodAutoscaler `autoscaling/v2beta2` | 1.23 | 1.26 |
| NetworkPolicy `extensions/v1beta1` | 1.14 | 1.22 |
| PodSecurityPolicy | 1.25 | **1.27** |

### 2.2 查集群内实际使用的 API

```bash
# 用 kube-no-trouble 扫描
docker run -it --rm -v ~/.kube:/config gianluz/kube-no-trouble:latest \
  --target-version 1.31.0
```

它会扫描所有 namespace，告诉你哪些资源用了弃用 API。

**示例输出**：

```
[FAIL] PodSecurityPolicy found in namespace: kube-system
       pod-psp is using policy/v1beta1
       Action: Migrate to Pod Security Admission or policy/v1
```

### 2.3 查 Operator 兼容性

```bash
# 查看集群里所有 Operator 的兼容性
kubectl get csv -A   # OLM 管理的 Operator
# 或者
for op in $(kubectl get deploy -A -l app.kubernetes.io/name=operator -o name); do
  echo "=== $op ==="
  kubectl get $op -o jsonpath='{.spec.template.spec.containers[0].image}'
done
```

去 Operator 官网查对应版本对 K8s 1.31 的兼容性。

### 2.4 查 CRD 兼容性

```bash
# 列出所有 CRD 和它们的 storedVersions
kubectl get crd -o custom-columns=NAME:.metadata.name,VERSIONS:.spec.versions[*].name,STORED:.status.storedVersions[*]

# 检查有没有 deprecated 的 storedVersions
```

CRD 的 `storedVersions` 里有旧版本的对象数据，**升级前要确保所有 CR 都有新版本**。

---

## 三、控制面升级：kubeadm 路线

### 3.1 升级前检查

```bash
# 1. 查看当前版本
kubectl version
# 2. 查可升级版本
kubeadm upgrade plan

# 输出类似：
# Components that must be upgraded manually after you have upgraded the control-plane:
#   kubelet                                  1.27.x → 1.27.y
#   kube-proxy                               1.27.x → 1.27.y
#
# Upgrade to the latest version in the v1.28 series:
#   COMPONENT   CURRENT   TARGET
#   api-server  v1.27.5   v1.28.0
#   controller-manager  v1.27.5   v1.28.0
#   scheduler   v1.27.5   v1.28.0
#   etcd        3.5.7     3.5.13
```

### 3.2 升级第一个 master 节点

```bash
# 1. 升级 kubeadm
yum install -y kubeadm-1.28.0-0
# 或者 apt-get

# 2. 排出该节点（避免升级时业务受影响）
kubectl drain <master-node-name> --ignore-daemonsets

# 3. 升级控制面
kubeadm upgrade apply v1.28.0

# 4. 升级 kubelet 和 kubectl
yum install -y kubelet-1.28.0-0 kubectl-1.28.0-0
systemctl daemon-reload
systemctl restart kubelet

# 5. 恢复节点
kubectl uncordon <master-node-name>
```

### 3.3 升级其他 master 节点

```bash
# 在其他 master 节点
yum install -y kubeadm-1.28.0-0
kubeadm upgrade node
yum install -y kubelet-1.28.0-0 kubectl-1.28.0-0
systemctl daemon-reload
systemctl restart kubelet
```

### 3.4 升级 etcd

```bash
# etcd 单独升级
yum install -y etcd-3.5.13-0
systemctl restart etcd

# 验证
etcdctl endpoint health
```

---

## 四、数据面升级：节点轮换策略

### 4.1 方案 A：原地升级（适合非生产）

```bash
# 在每个 worker 节点
kubectl drain <node-name> --ignore-daemonsets

yum install -y kubelet-1.28.0-0
systemctl daemon-reload
systemctl restart kubelet

kubectl uncordon <node-name>
```

**问题**：逐个升级耗时长，节点逐个重启。

### 4.2 方案 B：新建节点替换（推荐生产）

```yaml
# 1. 创建新节点池（已经是 1.28 的 kubelet）
# 云厂商：直接选 1.28 镜像创建实例
# 自建：用 kubeadm 1.28 加入集群

# 2. 旧节点上的 Pod 驱逐到新节点
kubectl drain <old-node-1> --ignore-daemonsets --delete-emptydir-data

# 3. 验证 Pod 跑起来了
kubectl get pods -o wide | grep <old-node-1>   # 应该没有了

# 4. 删除旧节点
kubectl delete node <old-node-1>
```

**优点**：新节点提前验证，灰度可控。

### 4.3 方案 C：节点蓝绿（最稳）

```yaml
# 1. 在新节点池部署相同 workload（双倍资源）
# 2. 旧节点上 Pod 排空
# 3. 旧节点下线
# 4. 回收资源
```

适合**大集群（>100 节点）** 的滚动升级。

---

## 五、API 弃用迁移实战

### 5.1 PodSecurityPolicy → Pod Security Admission

```yaml
# 1.27 及以前
apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
  name: restrictive
spec:
  privileged: false
  allowPrivilegeEscalation: false
  requiredDropCapabilities:
    - ALL
  runAsNonRoot: true
  seccompProfile:
    type: RuntimeDefault
```

迁移到：

```yaml
# 1.25+
apiVersion: v1
kind: Namespace
metadata:
  name: prod-api
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/warn: restricted
```

**优势**：

- 内置，无需 PSP admission webhook；
- 三档：privileged / baseline / restricted；
- 按 namespace 粒度控制。

### 5.2 CronJob `batch/v1beta1` → `batch/v1`

```bash
# 自动转换
kubectl get cronjob -A -o yaml | sed 's|apiVersion: batch/v1beta1|apiVersion: batch/v1|' | kubectl apply -f -
```

### 5.3 Ingress `networking.k8s.io/v1`

```yaml
# 1.19+
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
spec:
  ingressClassName: nginx     # 新字段，替代 annotation
  rules:
    - host: api.company.com
      http:
        paths:
          - path: /
            pathType: Prefix     # 新字段，替代 annotation
            backend:
              service:
                name: api-service
                port:
                  number: 80
```

### 5.4 用 conversion webhook 处理 CRD

有些 CRD 不能直接改 API 版本（如 cert-manager、istio），需要 conversion webhook。

```yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: certificates.cert-manager.io
spec:
  conversion:
    strategy: Webhook
    webhook:
      clientConfig:
        service:
          name: cert-manager-webhook
          namespace: cert-manager
          path: /convert
      conversionReviewVersions: ["v1", "v1beta1"]
```

---

## 六、升级后的验证

### 6.1 集群级验证

```bash
# 1. 节点状态
kubectl get nodes
# 确保所有节点都是 Ready + 1.28

# 2. 核心组件
kubectl -n kube-system get pods
# 确保 kube-apiserver、etcd、kube-controller-manager、kube-scheduler 都正常

# 3. 关键功能冒烟测试
kubectl run nginx --image=nginx:1.25 --rm -it -- bash
```

### 6.2 应用级验证

```bash
# 1. 检查所有 workload 状态
kubectl get deploy,sts,ds -A | grep -v Running

# 2. 检查 PVC/PV 绑定
kubectl get pvc -A | grep -v Bound

# 3. 检查 Service 路由
kubectl get endpoints -A | grep "<none>"

# 4. 检查 HPA/VPA 工作
kubectl get hpa -A
```

### 6.3 监控大盘验证

- **API Server 延迟**：是不是升级后 P99 升高？
- **etcd 写延迟**：是不是磁盘 IO 升高？
- **调度延迟**：Pod 启动时间是不是变长？
- **kubelet 心跳**：是不是节点 NotReady 频次增加？

---

## 七、踩坑提示

### 7.1 不要跨太多版本

K8s 官方要求**kubelet 和 API Server 之间版本差 ≤ 3 个 minor**。从 1.27 直接升 1.31 中间没过渡，**API Server 会拒绝 kubelet 注册**。

**正确路径**：

```
1.27 → 1.28 → 1.29 → 1.30 → 1.31
```

### 7.2 etcd 升级要小心

etcd 3.5.x 之间升级是兼容的，但从 3.4 升 3.5 要**先做数据快照**——3.5 用了新的存储格式，**不能直接降级**。

```bash
# 升级前必须备份
ETCDCTL_API=3 etcdctl snapshot save /backup/etcd-pre-upgrade.db
```

### 7.3 容器运行时也要升级

K8s 1.24+ 移除了 dockershim，如果还在用 Docker，要先迁到 containerd 或 CRI-O。

```bash
# 检查运行时
kubectl get nodes -o wide
# CONTAINER-RUNTIME 列
# 应该是 containerd://x.x.x 或 cri-o://x.x.x
```

### 7.4 API Server 配置变化

1.28 改了 `--service-account-issuer`、`--api-audiences` 等参数的校验逻辑，**从 1.27 升 1.28 时如果 kube-apiserver 启动失败，多半是配置问题**。

```bash
# 查看 API Server 日志
journalctl -u kube-apiserver -n 100
```

### 7.5 升级后性能回归

很多团队升完版本发现：

- **etcd 性能下降**——因为新版本默认值变了（如 `--quota-backend-bytes`）；
- **调度延迟增加**——新版的默认调度策略更严格；
- **kube-proxy iptables 规则变多**——iptables 模式被 nftables 取代。

**必须做**：升级后跑一遍性能基线测试，对比升级前后的关键指标。

---

## 八、长期维护策略

### 8.1 跟版本日历

K8s 每年发 4 个版本（3 月、6 月、9 月、12 月），**每个版本支持 14 个月**。

建议：

- **N 版本**为生产版本（刚升上来的）
- **N-1 版本**为备版本（降级备用）
- **N+1 版本**在预发布验证

```
1.30 ← 生产（升上来 3 个月）
1.29 ← 备版本（要降级随时能降）
1.31 ← 预发布验证（CI/CD 跑过）
```

### 8.2 自动化升级

```yaml
# ArgoCD ApplicationSet 管理集群升级
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-upgrade
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            k8s-version: "1.27"   # 选要升级的集群
  template:
    metadata:
      name: upgrade-{{name}}
    spec:
      source:
        repoURL: https://git.company.com/k8s-upgrade.git
        path: manifests/1.28
      destination:
        name: '{{name}}'
        server: '{{server}}'
      syncPolicy:
        automated:
          selfHeal: true
```

**注意**：集群升级比应用升级复杂得多，**不要用 GitOps 自动升级生产集群**。还是脚本 + 人工确认更稳。

### 8.3 升级 Runbook 模板

```yaml
# /runbooks/k8s-upgrade-1.27-to-1.28.md
## 升级前
- [ ] 备份 etcd
- [ ] 备份 Velero
- [ ] 通知所有业务方（升级窗口）
- [ ] 准备回滚方案

## 升级中
- [ ] 升级 master-1
- [ ] 验证 master-1 控制面
- [ ] 升级其他 master
- [ ] 升级 worker 节点（按 20% 批次）
- [ ] 每个 worker 升级后验证 Pod 状态

## 升级后
- [ ] 全集群冒烟测试
- [ ] 监控大盘基线对比
- [ ] 通知业务方"已恢复"
- [ ] 写升级复盘文档
```

---

## 本篇要点回顾

1. K8s 升级分**控制面**和**数据面**，必须错开（控制面先升）
2. **不能跨 3 个 minor 版本**——必须 1.27 → 1.28 → 1.29 → 1.30 → 1.31
3. 升级前必做**API 考古**：用 `kubectl deprecations` + `kube-no-trouble` 扫描
4. 数据面升级推荐**新建节点替换**（比原地升级稳）
5. PSP、CronJob、Ingress 等弃用 API 要**提前迁移**
6. 升级后必做**性能基线对比**——etcd 延迟、调度延迟、API Server P99
7. 生产集群升级**不要全自动化**，保留人工确认环节

---

## 云原生进阶系列（23-46）完结

到这一篇，第二季的**云原生进阶系列 24 篇**全部完成。覆盖了：

- **K8s 深入**（23-28）：架构、Operator、调度、网络、存储
- **容器与镜像**（29-33）：优化、安全、PSA、Distroless、Wasm
- **Service Mesh 深入**（34-39）：Istio、Envoy Filter、可观测性、eBPF、选型
- **多集群与平台**（40-46）：联邦、HPA/VPA、成本、GitOps、灾备、升级

下一系列（47 起）是**混沌工程与韧性**，敬请期待。

本文是「架构实战·第二季」第 46 篇，也是云原生进阶系列的收官篇。云厂商托管 K8s 升个版本点一下就行，但自建 K8s 集群从 1.27 升到 1.31，要跨 4 个版本、跨 12 个月、跨 4 个 K8s API 弃用周期——这篇文章把"平滑演进"的完整方法论讲清楚。

【架构实战】K8s 升级策略：从 1.27 到 1.31 的平滑演进

研发部经理

架构设计

云计算

运维

自建K8s从1.27升1.31需跨4版本，控制面与数据面错开升级，严格限制版本差≤3，升级前用kubectl deprecations和kube-no-trouble扫描弃用API，优先新建节点替换，并迁移PSP等弃用资源，升级后必须做性能基线对比。

腾讯云双十一大促

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【架构实战】K8s 升级策略：从 1.27 到 1.31 的平滑演进-腾讯云开发者社区-腾讯云

【架构实战】K8s 升级策略：从 1.27 到 1.31 的平滑演进

【架构实战】K8s 升级策略：从 1.27 到 1.31 的平滑演进

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐