彻底解决 Kubernetes 集群 IP 变更后的崩溃问题：终极重装指南

摘要

本文针对 Kubernetes 集群因 Master 节点 IP 地址变更而导致证书失效、API Server 无法访问，最终整个集群崩溃的常见场景，提供了一套终极的、彻底的重装解决方案。与其他教程不同，本指南强调“完全清理”的重要性，通过一系列精确的步骤，确保所有旧的配置、证书和数据被彻底移除，从而避免重装过程中常见的 x509 证书错误或 auth 认证失败问题，实现一次性成功初始化新集群。

一、 问题根源：为何更换 IP 会导致集群崩溃？

Kubernetes 集群的正常运行高度依赖于其内部组件间的安全通信，而这种通信是通过 TLS 证书来保障的。在 kubeadm init 初始化集群时，会生成一系列证书，其中最核心的 API Server 证书会将 Master 节点的 IP 地址或主机名硬编码到其 Subject Alternative Name (SANs) 字段中。

当您更换了 Master 节点的 IP 地址后：

1. 证书失效：Kubelet、Controller Manager、Scheduler 等组件以及 kubectl 客户端尝试连接新的 IP 地址时，会发现该 IP 与 API Server 提供的证书中的 SANs 列表不匹配。
2. TLS 握手失败：出于安全考虑，客户端会拒绝与这个“身份不明”的服务建立连接，导致 x509: certificate is valid for old-ip, not new-ip 类的错误。
3. 集群状态失联：所有组件都无法与 API Server 通信，节点状态变为 NotReady，集群实质上已经完全崩溃。

虽然理论上可以通过复杂的手动证书轮换来修复，但这个过程极易出错。因此，在开发、测试环境或非关键业务场景下，最快、最可靠的恢复方式就是彻底重装。

二、 终极重装步骤

警告： 以下操作是毁灭性的，将彻底删除目标节点上所有 Kubernetes 数据和配置。在执行前，请确保已备份所有重要数据（如持久化存储 PV 中的数据），并已将此节点上的业务负载迁移。

第 1 步：停止相关服务并执行标准重置

首先，停止正在运行的 Kubernetes 核心服务，以释放文件占用，然后执行 kubeadm 自带的重置命令。

# 停止 kubelet 和 etcd 服务
systemctl stop kubelet
systemctl stop etcd

# 执行 kubeadm 的标准重置流程，-f 表示强制执行，无需交互确认
kubeadm reset -f

kubeadm reset 会尝试撤销 kubeadm init 或 kubeadm join 所做的更改，但这并不总是能清理干净所有内容。

第 2 步：深度清理 - 彻底删除所有残留文件

这是确保重装成功的关键步骤。许多重装失败的案例都是因为残留的旧配置文件或数据导致了冲突。

# 1. 删除用户目录下的 kubectl 配置文件
rm -rf ~/.kube/

# 2. 删除所有集群配置文件、证书和静态 Pod manifest
#    这是导致 x509 错误的核心残留
rm -rf /etc/kubernetes/

# 3. 删除 kubelet 的 systemd 服务配置
rm -rf /etc/systemd/system/kubelet.service.d
rm -rf /etc/systemd/system/kubelet.service

# 4. (可选但推荐) 删除旧的 kubelet, kubeadm, kubectl 二进制文件
#    下一步会重装，此步确保使用的是纯净版本
rm -rf /usr/bin/kube*

# 5. 删除 CNI 网络插件的配置和二进制文件
rm -rf /etc/cni
rm -rf /opt/cni

# 6. 彻底删除 etcd 的所有数据和配置目录
#    必须执行此步以清空旧的集群状态
rm -rf /var/lib/etcd
rm -rf /var/etcd

第 3 步：重新安装并初始化集群

完成彻底清理后，现在的节点就像一台全新的机器。接下来，我们重新安装核心组件，并使用新的 IP 地址初始化集群。

# 1. 使用 yum 重新安装指定版本的 k8s 组件
#    'reinstall' 能确保将组件恢复到初始状态
yum -y reinstall kubelet-1.21.5-0 kubeadm-1.21.5-0 kubectl-1.21.5-0

# 2. 启用 kubelet 服务，使其可以开机自启
systemctl enable kubelet

# 3. 使用新的 IP 地址初始化 Master 节点
#    请根据您的实际情况修改此命令
kubeadm init \
  --apiserver-advertise-address={你的新节点IP} \
  --image-repository registry.aliyuncs.com/google_containers \
  --kubernetes-version v1.21.5 \
  --service-cidr=10.96.0.0/12 \
  --pod-network-cidr=10.244.0.0/16 \
  --ignore-preflight-errors=all

kubeadm init 参数解析：

• --apiserver-advertise-address: 必须填写您节点当前的新 IP 地址。这是 API Server 向集群其他成员广播的地址。
• --image-repository: 指定国内的镜像仓库，避免从 k8s.gcr.io 拉取镜像失败。
• --kubernetes-version: 指定集群版本，应与安装的二进制文件版本一致。
• --service-cidr & --pod-network-cidr: 分别是 Service 和 Pod 的网络地址段，请确保它们与您的网络规划不冲突。
• --ignore-preflight-errors=all: 忽略预检错误，例如 Swap 分区未关闭等。在生产环境中应谨慎使用，逐一解决预检问题。

三、 后续步骤

kubeadm init 成功执行后，会输出下一步的指令：

1. 配置 kubectl：按照提示，执行 mkdir 和 cp 命令，将新的集群管理员配置文件 (admin.conf) 复制到用户目录下，以便 kubectl 可以正常访问集群。
2. 安装网络插件 (CNI)：一个全新的集群还没有安装网络插件，Pod 之间无法通信。您需要根据选择安装一个 CNI 插件，例如 Calico 或 Flannel。
3. 加入 Worker 节点：init 命令的输出中还会包含一条 kubeadm join 命令，包含了 token 和证书哈希。在其他需要加入集群的 Worker 节点上执行这条命令即可。

四、 总结

更换 Kubernetes Master 节点 IP 是一项高风险操作。与其陷入修复证书的泥潭，不如采用“推倒重建”的策略。本文提供的深度清理流程是成功的关键，它能确保在新的 kubeadm init 执行时，环境纯净无干扰，从而根本上杜绝因配置残留导致的 x509 或 auth 错误，实现快速、可靠的集群恢复。