KnoAI 技术站

主题

RKE2 集群节点添加操作手册 ​

适用范围 ​

  • RKE2 版本：v1.35.6+rke2r1
  • 操作系统：Rocky Linux 9 / RHEL 9 系列
  • CNI：Calico
  • 角色：control-plane / etcd / worker

一、添加前注意事项 ​

1.1 必须统一的关键配置 ​

RKE2 集群中所有节点（尤其是 control-plane / etcd 节点）的以下配置必须完全一致：

配置项说明默认值
cluster-cidrPod 网络 CIDR10.42.0.0/16
service-cidrService 网络 CIDR10.43.0.0/16
cluster-dnsDNS 服务 IP，由 service-cidr 派生10.43.0.10
cniCNI 插件类型canal

⚠️ 如果第一台 master 初始化时显式修改了 cluster-cidr / service-cidr，后续所有节点必须使用完全相同的值，否则会出现 critical configuration value mismatch between servers 错误。

1.2 确认现有集群状态健康 ​

在现有 control-plane 节点上执行：

bash
export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
/var/lib/rancher/rke2/bin/kubectl get nodes -o wide
/var/lib/rancher/rke2/bin/kubectl get cs
/var/lib/rancher/rke2/bin/kubectl get pods -A

确认：

  • 所有现有节点 STATUS 为 Ready
  • controller-manager、scheduler、etcd 均为 Healthy
  • 无异常 CrashLoopBackOff 或 Pending Pod

1.3 确认目标节点信息 ​

记录以下信息：

  • 新节点 IP、主机名
  • 要添加的角色（control-plane / etcd / worker）
  • 注册命令来源（Rancher UI 生成的命令 / 手动配置 /etc/rancher/rke2/config.yaml）
  • 镜像仓库地址及认证信息（如果是离线/私有仓库）

二、添加前检查清单 ​

2.1 网络连通性检查 ​

从新节点测试到现有 control-plane 的连通性：

bash
# ICMP 连通性
ping -c 3 <现有master-ip>

# RKE2 关键端口
timeout 3 bash -c "</dev/tcp/<现有master-ip>/9345" && echo "9345 OK" || echo "9345 FAIL"
timeout 3 bash -c "</dev/tcp/<现有master-ip>/6443" && echo "6443 OK" || echo "6443 FAIL"
timeout 3 bash -c "</dev/tcp/<现有master-ip>/2379" && echo "2379 OK" || echo "2379 FAIL"
timeout 3 bash -c "</dev/tcp/<现有master-ip>/2380" && echo "2380 OK" || echo "2380 FAIL"

如果任何端口 FAIL，必须先排查防火墙。

2.2 防火墙检查 ​

在两台节点上都执行：

bash
iptables -L INPUT -n -v --line-numbers

检查是否存在末尾全拒绝规则：

text
REJECT     all  --  *      *       0.0.0.0/0            0.0.0.0/0            reject-with icmp-host-prohibited

如果存在且没有放行 RKE2 端口的 ACCEPT 规则，需要参考《RKE2 新增 master 节点失败：iptables 防火墙拦截 RKE2/Calico 端口》进行修复。

2.3 端口清单 ​

control-plane / etcd 节点需要开放的端口 ​

端口协议用途
9345TCPRKE2 supervisor，节点注册
6443TCPKubernetes API Server
2379TCPetcd client
2380TCPetcd peer
10250TCPkubelet
10257TCPkube-controller-manager
10259TCPkube-scheduler
5473TCPCalico Typha
9099TCPCalico Felix health
4789UDPVXLAN overlay
8472UDPVXLAN / Flannel

worker 节点需要开放的端口 ​

端口协议用途
6443TCPKubernetes API（需要访问 control-plane）
10250TCPkubelet
5473TCPCalico Typha
4789UDPVXLAN overlay
8472UDPVXLAN / Flannel
30000-32767TCPNodePort Services

2.4 配置文件检查 ​

在现有 control-plane 上查看配置：

bash
cat /etc/rancher/rke2/config.yaml
cat /etc/rancher/rke2/config.yaml.d/*.yaml

新节点的 /etc/rancher/rke2/config.yaml 或 /etc/rancher/rke2/config.yaml.d/50-rancher.yaml 必须包含：

yaml
server: https://<现有master-ip>:9345
token: <server-token>
# 如果是 agent 节点使用 agent-token，control-plane 节点使用 token

以及和现有集群一致的：

yaml
cluster-cidr: <和现有集群一致>
service-cidr: <和现有集群一致>
cni: <和现有集群一致>

2.5 主机名与 DNS 检查 ​

bash
hostname
hostname -f
cat /etc/hosts

确保：

  • 主机名唯一，不与现有节点重复
  • /etc/hosts 中本机解析正确
  • 所有节点之间可以通过主机名或 IP 互相解析

2.6 系统资源检查 ​

bash
free -h
df -h
nproc

建议最低配置：

  • control-plane / etcd：2C4G 起步，生产环境 4C8G+
  • worker：根据业务负载决定

2.7 SELinux / 内核模块检查 ​

bash
getenforce
lsmod | grep -E "br_netfilter|overlay"

RKE2 会自动加载 br_netfilter 和 overlay，但如果系统模块缺失会导致启动失败。

三、添加 control-plane / etcd 节点 ​

3.1 通过 Rancher UI 生成注册命令 ​

  1. 登录 Rancher UI
  2. 进入目标集群 → Edit Config / Manage → Registration
  3. 勾选 etcd、Control Plane、Worker
  4. 复制生成的命令，在新节点执行

Rancher 会自动写入 /etc/rancher/rke2/config.yaml.d/50-rancher.yaml。

3.2 手动配置方式 ​

在新节点上创建 /etc/rancher/rke2/config.yaml：

yaml
server: https://<现有master-ip>:9345
token: <server-token>
node-name: <新节点IP或主机名>
cluster-cidr: <和现有集群一致>
service-cidr: <和现有集群一致>
cni: calico

如果是私有镜像仓库，添加：

yaml
system-default-registry: <registry-ip>:<port>
private-registry: /etc/rancher/rke2/registries.yaml

3.3 启动 rke2-server ​

bash
systemctl enable --now rke2-server

3.4 观察启动日志 ​

bash
journalctl -u rke2-server -f

正常日志应包含：

text
msg="Managed etcd cluster not yet initialized"
msg="Connection to etcd is ready"
msg="ETCD server is now running"
msg="Running kubelet ..."

四、添加 worker 节点 ​

4.1 配置方式 ​

创建 /etc/rancher/rke2/config.yaml：

yaml
server: https://<现有master-ip>:9345
token: <agent-token>
node-name: <新节点IP或主机名>

4.2 启动 rke2-agent ​

bash
systemctl enable --now rke2-agent

4.3 观察日志 ​

bash
journalctl -u rke2-agent -f

五、添加后验证 ​

5.1 节点状态 ​

在现有 control-plane 上：

bash
export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
/var/lib/rancher/rke2/bin/kubectl get nodes -o wide

预期所有节点 STATUS 为 Ready。

5.2 组件状态 ​

bash
/var/lib/rancher/rke2/bin/kubectl get cs

5.3 新节点 Pod 状态 ​

bash
/var/lib/rancher/rke2/bin/kubectl get pods -A --field-selector spec.nodeName=<新节点主机名>

5.4 网络连通性验证 ​

在新节点上创建一个测试 Pod：

bash
/var/lib/rancher/rke2/bin/kubectl run test --image=<registry>/busybox --restart=Never -- sleep 3600

进入 Pod 测试：

bash
/var/lib/rancher/rke2/bin/kubectl exec -it test -- ping -c 3 <其他Pod-IP>

六、常见问题排查 ​

6.1 no route to host on 9345 ​

根因：防火墙拦截。

排查：

bash
iptables -L INPUT -n -v --line-numbers
ss -tlnp | grep 9345

修复：参考《RKE2 新增 master 节点失败：iptables 防火墙拦截 RKE2/Calico 端口》。

6.2 critical configuration value mismatch between servers ​

根因：cluster-cidr / service-cidr 与现有集群不一致。

修复：

  1. 停止新节点 rke2-server
  2. 修改 /etc/rancher/rke2/config.yaml，补充与现有集群一致的 CIDR
  3. 清理残留数据：
bash
systemctl stop rke2-server
rm -rf /var/lib/rancher/rke2/server/
rm -rf /var/lib/rancher/rke2/agent/etc/*
  1. 重新启动

注意：仅清理新节点，不要清理现有 master。

6.3 failed to bootstrap cluster data: not authorized ​

根因：token 不正确或已过期。

修复：

  • 从现有 control-plane 获取正确 token：
bash
cat /var/lib/rancher/rke2/server/token
  • 或在 Rancher UI 重新生成注册命令。

6.4 etcd 加入后一直 authentication handshake failed ​

根因：etcd peer 端口 2380 被防火墙拦截。

修复：在相关节点上放行 2380/tcp。

6.5 Calico 节点 0/1 Running，报 no route to host to Typha ​

根因：Typha 端口 5473 被防火墙拦截。

修复：在运行 Typha 的节点上放行 5473/tcp。

6.6 节点长时间 NotReady ​

可能原因：

  • 离线环境镜像导入慢（参考《RKE2 新增 master 节点显示 NotReady：镜像导入耗时与无效配置项》）
  • CNI 未就绪
  • kubelet 启动失败

排查：

bash
journalctl -u rke2-server -f
/var/lib/rancher/rke2/bin/crictl --runtime-endpoint /run/k3s/containerd/containerd.sock ps -a

七、最佳实践 ​

7.1 配置统一管理 ​

使用 Ansible / Terraform / cloud-init 统一生成所有节点的 /etc/rancher/rke2/config.yaml，避免手动配置错误。

7.2 防火墙策略 ​

  • 生产环境：使用 firewalld 或 nftables 管理，仅放行必要端口
  • 测试环境：可以关闭 iptables.service，但需评估安全风险

7.3 节点命名规范 ​

建议使用固定命名规则，如 rancher-ctrl-vm<N> / rancher-worker-vm<N>，避免重复。

7.4 添加前端口扫描 ​

在批量添加节点前，先扫描目标网段确认 RKE2 supervisor 端口可达：

bash
for i in $(seq 1 254); do
  ip="192.168.122.$i"
  timeout 1 bash -c "</dev/tcp/$ip/9345" >/dev/null 2>&1 && echo "$ip:9345 OPEN" &
done
wait

7.5 离线环境提前准备镜像 ​

离线/半离线环境建议提前：

  • 将 RKE2 镜像包 rke2-images.linux-amd64.tar.zst 放到 /var/lib/rancher/rke2/agent/images/
  • 在私有仓库配置 docker.io 的 mirror

7.6 添加顺序 ​

建议按以下顺序：

  1. 先确保第一台 control-plane 健康
  2. 逐个添加其他 control-plane / etcd 节点
  3. 每加入一个节点验证通过后再加下一个
  4. 最后添加 worker 节点

八、相关文档 ​

当前目录下相关故障记录：

  • rke2-master-join-fails-critical-configuration-mismatch.md
  • rke2-master-join-fails-iptables-firewall-blocking.md
  • rke2-master-join-notready-image-import-delay.md
  • rke2-disaster-recovery-control-plane-quorum-loss.md

九、紧急回退 ​

如果新节点加入失败且导致集群异常，可以：

  1. 停止新节点 rke2-server / rke2-agent
  2. 从现有 control-plane 删除该节点：
bash
/var/lib/rancher/rke2/bin/kubectl delete node <新节点主机名>
  1. 清理新节点数据：
bash
systemctl stop rke2-server rke2-agent
rm -rf /var/lib/rancher/rke2/server/
rm -rf /var/lib/rancher/rke2/agent/
  1. 修复问题后重新加入

记录时间：2026-07-16
涉及版本：RKE2 v1.35.6+rke2r1, Rocky Linux 9.8