本地 IDEA 直连 Kubernetes 集群(Calico 网络)调试方案 · 通用分享版

适用对象:采用「微服务 + 服务注册中心」架构的开发与调试人员
操作系统:Windows(本地 IDEA 开发环境)
集群:Kubernetes 集群(本文以 Rancher 管理的 RKE2 集群为例),CNI 为 Calico,Pod 网段 10.42.0.0/16(可按实际环境替换)
配套脚本:sync-calico-routes.bat(同步 Calico BlockAffinity 静态路由)
效率提升:单次调试迭代从打包上线的 3到15 分钟压缩到本地直连的 5到30 秒,提速约 10到60 倍(典型 20 倍);每天约省 1.5 小时、每周约 4到8 小时(详见 1.4 效率提升量化)。

说明:本文为通用技术分享版本,已去除具体项目名、内部网络名、个人用户名等敏感信息,相关位置以通用占位符表示(如 <你的用户名>、注册中心)。技术方案本身适用于任何使用 Calico CNI 的 Kubernetes 集群。


目录


一、背景与目标

1.1 现状痛点

在典型的微服务架构中,各服务之间通过服务注册中心(如 Nacos、Eureka 等)注册的服务 IP相互调用。在集群内,这些 IP 是 Pod IP(如 10.42.x.x 网段),仅在集群网络内部可达。由此带来两个问题:

  • 联调成本高:本地改一行代码想验证,必须走「打包 → 推镜像 → 更新 deployment → 等待滚动」的完整上线流程,一次迭代动辄几分钟到十几分钟。
  • 跨环境割裂:本地 IDE 启动的服务与集群里的服务不在同一网络平面,无法直接按注册中心里注册的 IP 互相发现、调用。

1.2 方案目标

打通本地开发机(192.168.x.x 办公网)到集群 Pod 网段(10.42.0.0/16)的路由,实现:

  • 本地 IDE 只启动一个待调试服务,其余数十个依赖服务直接用集群里跑着的实例;
  • 本地服务通过注册中心拿到的 Pod IP,可以像在集群内一样直接调用集群服务;
  • 集群服务注册到注册中心的地址,本地也能反向访问(视具体服务注册行为);
  • 无需为每个改动打包上线部署,大幅缩短调试反馈环。

1.3 方案价值

对比项 传统方式 本方案
单次调试迭代 打包+推镜像+部署+等待 本地 IDE 改完即测
依赖服务准备 本地逐一启动数十个服务 复用集群已有实例
网络一致性 本地与集群网络隔离 Pod IP 层面互通
对集群的侵入 需要反复发布 零发布,仅读取集群元数据

1.4 效率提升量化(核心收益)

本方案最大的价值在于**把一次调试迭代的反馈周期从”分钟级”压缩到”秒级”**。以下按典型开发场景估算(实际数值因项目构建速度、镜像仓库、集群调度而异,可代入自己的数据套用):

单次迭代耗时对比

环节 传统方式(打包上线) 本方案(本地直连)
代码编译 / 打包 1~3 分钟 0(IDE 热部署/增量编译,几秒)
构建并推送镜像 1~3 分钟 0
更新 Deployment / 等待滚动 1~5 分钟 0
服务启动并可测 30 秒~2 分钟 5~30 秒(本地重启)
单次迭代合计 约 3~15 分钟(典型 5~8 分钟) 约 5~30 秒

提速约 10~60 倍(按典型值 5 分钟 vs 15 秒估算,约 20 倍)。

按工作量的累积收益

以每天调试迭代次数、每次节省时间估算(取保守典型值):

场景 传统方式 本方案 每日节省
每天 10 次迭代 × 每次 5 分钟 vs 15 秒 约 50 分钟 约 2.5 分钟 约 47 分钟/天
每天 20 次迭代 × 每次 5 分钟 vs 15 秒 约 100 分钟 约 5 分钟 约 95 分钟/天(≈1.5 小时)
按每周 5 个工作日 — — 约 4~8 小时/周

换算下来,相当于每周多出约 1 个工作日的有效开发时间,且调试节奏从”改完等几分钟”变成”改完立刻看结果”,思路不被打断,隐性收益远大于纯时间数字。

依赖服务准备成本

项目 传统方式 本方案
需本地启动的依赖服务数 数十个 仅 1 个(待调试服务)
一次性环境搭建 每个服务都要配 一次配置 kubectl+路由即可
依赖服务版本一致性 需手动对齐 直接用集群现网实例,天然一致

省去本地启动并维护数十个依赖服务的全部成本(安装、配置、端口冲突排查、版本同步等)。

效率公式(代入自己的数据)

1
2
3
4
5
6
7
单次节省 = 传统迭代耗时 − 本地迭代耗时
每日节省 = 单次节省 × 每日迭代次数
提速倍数 = 传统迭代耗时 ÷ 本地迭代耗时

示例:传统 5 分钟(300s) − 本地 15s = 285s/次
300s ÷ 15s = 20 倍
285s × 20 次/天 = 5700s ≈ 95 分钟/天

二、方案原理

2.1 整体网络拓扑

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
                      ┌──────────────────────────────────────┐
│ K8s 集群(如 Rancher 管理) │
│ │
本地 IDE 服务 │ Node1(192.168.x.11) Node2(192.168.x.12) ...
(192.168.x.100) │ │ │
│ │ ┌──┴──┐ ┌──┴──┐
访问注册中心中注册的 │ │Pod块│ │Pod块│
Pod IP 10.42.a.b ─────┼──▶│10.42│ │10.42│
│ │ │.x.0 │ │.y.0 │
│ 静态路由: │ │/26 │ │/26 │
│ 逐块:10.42.a.0/26 ─▶ │ └─────┘ └─────┘
│ 网关=节点IP │ Calico IPAM 把 /26 块分配给各节点
▼ │ BlockAffinity 记录「块 → 节点」关系
本机路由表 └──────────────────────────────────────┘
(route -4 -p add)

2.2 为什么需要”逐块”静态路由

使用 Calico 作为 CNI 的集群,Pod IP 从 10.42.0.0/16 中分配(以本文环境为例,实际以集群配置为准)。Calico 的 IPAM 会把整个大网段切成多个 /26 小块(每块 64 个地址),再把每个块整体分配给某一个节点。这个「块 → 节点」的归属关系就是 BlockAffinity。

概念辨析:10.42.0.0/16 与 /26 块不冲突。 前者是 Calico IPAM 的分配池(全集,即整个 Pod 网段 10.42.0.0~`10.42.255.255);后者是从中切出的**子集**,每个 /26块都完整落在/16 之内。二者是"整体 → 局部"的包含关系,掩码长度不同(/16 短、/26` 长),互不矛盾。

注意:本文中的 10.42.x.0/26 只是泛指写法,并不表示块一定以 .0 结尾。/26 的块边界固定在第三段或第四段的 64 地址边界上,实际可能是 10.42.3.0/26、10.42.7.64/26、10.42.200.128/26 等任意形态,一切以集群里 BlockAffinity 的实际 .spec.cidr 为准。

关键点:

  • Pod IP 本身不在二层网络上直接可见,外部机器无法直接用 ARP 找到 Pod;
  • 但节点 IP是办公网可达的(节点网卡在 192.168.x.x),可以作为网关;
  • 因此只要告诉本机:「去某个 /26 块(如 10.42.7.64/26)的流量,交给负责该块的节点 IP 转发」,流量就能进入集群,再由节点上的 Calico/felix + BIRD 转发到具体 Pod。

这就是脚本要做的事:读取集群里的 BlockAffinity + 节点 InternalIP,在本机生成一条条 目标块 → 节点 IP 的持久静态路由。

2.3 为什么用”持久静态路由”

  • Windows route -4 -p add 中的 -p(persistent)表示持久路由,写入注册表
    HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\PersistentRoutes,重启后依然生效;
  • 路由命令本身不支持给路由打注释,所以脚本通过”目标网段 + 掩码”精确识别自己管理的路由(目标在 10.42.* 且掩码为 /16 即 255.255.0.0、或 /26 即 255.255.255.192),避免误删其他路由;
  • 每次运行脚本先清理旧路由、再按最新集群状态重建,保证路由表与集群 IPAM 分配保持一致。

2.4 数据流小结

  1. kubectl get blockaffinity.crd.projectcalico.org → 拿到所有 /26 块及其归属节点名;
  2. kubectl get nodes → 拿到每个节点的 InternalIP;
  3. 两者按”节点名”关联,得到 块 CIDR → 节点 IP 映射;
  4. route -4 -p add <块网段> mask 255.255.255.192 <节点IP> 逐条写入本机;
  5. 本机访问 10.42.x.x 时,按最长前缀匹配命中对应 /26 路由,经节点 IP 进入集群。

三、前置条件清单

在跑脚本之前,请逐项确认:

# 条件 检查方式
1 本机与集群节点网络互通 ping <节点InternalIP> 能通(见第五节获取节点 IP)
2 已安装 kubectl 并加入 PATH 命令行执行 kubectl version --client
3 已配置可用的 kubeconfig kubectl get nodes 能列出节点
4 当前 context 指向目标集群 kubectl config current-context
5 账号有读取 BlockAffinity 与 Node 的权限 kubectl get blockaffinity.crd.projectcalico.org 不报 Forbidden
6 以管理员身份运行脚本 脚本会自行检查,非管理员直接报错退出
7 办公网到 Pod 网无中间 ACL 拦截 见第七节连通性验证

说明:脚本第 38 行会检查 kubectl 是否在 PATH 中,第 32 行会检查管理员权限,任一不满足都会写日志并退出。所以第 2、3、6 项是硬性前置。


四、安装 kubectl(Windows)

kubectl 是操作 Kubernetes 集群的命令行工具,脚本依赖它读取集群元数据。以下任选一种方式安装。

4.1 方式一:直接下载官方 exe(推荐,最通用)

  1. 新建目录,例如 C:\bin(也可放到任意目录,只要加入 PATH):

    1
    mkdir C:\bin
  2. 下载 kubectl.exe。先确认最新稳定版本号:

    1
    curl.exe -L https://dl.k8s.io/release/stable.txt

    假设返回 v1.34.0,则下载对应 Windows 二进制:

    1
    curl.exe -LO "https://dl.k8s.io/release/v1.34.0/bin/windows/amd64/kubectl.exe" -o C:\bin\kubectl.exe

    也可用浏览器直接打开 https://dl.k8s.io/release/v1.34.0/bin/windows/amd64/kubectl.exe 下载后重命名为 kubectl.exe,放进 C:\bin。

  3. 将 C:\bin 加入系统 PATH:

    • 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」;
    • 在「系统变量」或「用户变量」中找到 Path →「编辑」→「新建」→ 填入 C:\bin → 确定;
    • 重新打开一个命令行窗口使配置生效。
  4. 验证:

    1
    kubectl version --client

    能输出客户端版本即安装成功。

4.2 方式二:PowerShell 一键下载(自动取最新版)

在 PowerShell 中执行:

1
2
3
4
$dir = "C:\bin"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
$ver = (Invoke-WebRequest -Uri "https://dl.k8s.io/release/stable.txt" -UseBasicParsing).Content.Trim()
Invoke-WebRequest -Uri "https://dl.k8s.io/release/$ver/bin/windows/amd64/kubectl.exe" -OutFile "$dir\kubectl.exe" -UseBasicParsing

然后把 C:\bin 加入 PATH(步骤同 4.1 第 3 步),再执行 kubectl version --client 验证。

4.3 方式三:包管理器(可选)

若本机已安装 Chocolatey 或 Scoop:

1
2
3
4
5
# Chocolatey
choco install kubernetes-cli

# Scoop
scoop install kubectl

包管理器会自动配置 PATH。

4.4 版本选择建议

  • kubectl 与集群的版本差建议在 ±1 个小版本以内(如集群 1.33,kubectl 用 1.32~1.34);
  • 集群版本可在集群管理面板概览页查看,或用 kubectl version 在连上集群后查看 Server 版本;
  • 若不确定,用 stable.txt 的最新版通常可用。

官方安装文档:Install and Set Up kubectl on Windows


五、获取并配置 kubeconfig(Rancher)

kubeconfig 是 kubectl 连接集群的”钥匙”,里面包含 API Server 地址、证书/令牌、context 等信息。集群由 Rancher 管理时,kubeconfig 需从 Rancher 下载。

5.1 从 Rancher 下载 kubeconfig

  1. 用浏览器登录 Rancher UI;
  2. 进入目标集群(左上角或首页选择对应集群);
  3. 在集群概览页右上角找到 「Download KubeConfig」(下载 kubeconfig)按钮并点击;
  4. 浏览器会下载一个 YAML 文件,通常命名为 <集群名>.yaml 或 kubeconfig-xxx.yaml。

若右上角没有该按钮,可在集群页面进入「更多 / ⋮」菜单查找,或在 Rancher 用户头像 →「下载 KubeConfig」处获取。不同 Rancher 版本入口略有差异。

5.2 放置 kubeconfig 文件

kubectl 默认从 %USERPROFILE%\.kube\config 读取配置。

  1. 创建目录(若不存在):

    1
    mkdir "$env:USERPROFILE\.kube"
  2. 把下载的文件复制/重命名为 config:

    1
    copy "<下载的kubeconfig文件路径>" "$env:USERPROFILE\.kube\config"

    例如下载到了桌面:

    1
    copy "C:\Users\<你的用户名>\Desktop\kubeconfig-demo.yaml" "$env:USERPROFILE\.kube\config"

5.3 方式二:用 KUBECONFIG 环境变量(多配置文件时推荐)

如果不想覆盖默认的 config,或需要管理多套集群配置,可以把多个 kubeconfig 用分号连接赋给 KUBECONFIG:

1
$env:KUBECONFIG = "C:\path\to\kubeconfig-a.yaml;C:\path\to\kubeconfig-b.yaml"

永久生效可在「环境变量」里新增用户变量 KUBECONFIG。

注意:Windows 下多个文件路径用**分号 ;**分隔(Linux/macOS 用冒号 :)。

5.4 验证 kubeconfig 可用

1
2
3
4
5
6
7
8
9
10
11
# 查看当前 context
kubectl config current-context

# 列出节点(能列出即配置正确、网络可达、权限正常)
kubectl get nodes

# 查看所有 context(多集群时切换用)
kubectl config get-contexts

# 切换 context
kubectl config use-context <context名称>

若 kubectl get nodes 能正常返回节点列表(含 NAME、STATUS、ROLES、AGE、VERSION),说明 kubeconfig 配置成功。

5.5 多集群 context 管理(可选)

若同时连接多个集群(开发/测试/生产),kubeconfig 中会有多个 context 与 cluster:

  • 保持默认 context 指向本次要打通的集群,因为脚本不带 --context 参数,直接使用当前 context;
  • 运行脚本前先用 kubectl config current-context 确认;
  • 需要切换时用 kubectl config use-context <名字>。

5.6 常见问题:令牌过期

Rancher 生成的 kubeconfig 中通常带有有效期(如 token 过期时间为若干小时/天)。过期后 kubectl 会报 Unauthorized 或证书过期错误。解决办法:回到 Rancher UI 重新下载 kubeconfig 并替换本地文件。


六、同步路由脚本使用说明

6.1 脚本做的事(回顾)

sync-calico-routes.bat 完整流程:

  1. 管理员权限检查 —— 非管理员直接报错退出;
  2. 拉取 BlockAffinity —— 获取所有块网段(.spec.cidr)及归属节点(.spec.node);
  3. 拉取节点 InternalIP —— kubectl get nodes 取每个节点的 .status.addresses[0].address;
  4. 清理旧路由 —— 删除本机上目标在 10.42.* 且掩码为 /16 或 /26 的持久路由(仅限本脚本管理的范围);
  5. 添加新路由 —— 为每个有效 /26 块添加持久静态路由:route -4 -p add <块网段> mask 255.255.255.192 <节点IP>;
  6. 写日志 —— 在脚本同目录生成 route-sync.log,记录每一步与最终路由表。

6.2 运行步骤

  1. 确认第三、四、五节的前置条件均满足(kubectl 可用、kubeconfig 可用、kubectl get nodes 正常);

  2. 把 sync-calico-routes.bat 放在任意目录(建议固定位置,日志会生成在同目录);

  3. 右键该脚本 →「以管理员身份运行」(UAC 弹窗点”是”);

  4. 脚本执行完会显示:

    1
    2
    同步完成:成功 N 条,失败 M 条。
    日志:C:\...\route-sync.log
  5. 按任意键关闭窗口。

6.3 检查运行结果

  • 控制台输出:关注 成功 X 条,失败 Y 条。全部成功时 失败=0;
  • 日志文件:打开同目录 route-sync.log,可看到:
    • 当前 BlockAffinity 原始输出(块 → 节点);
    • 当前节点 IP 映射(节点 → IP);
    • 删除的旧路由、添加的新路由明细;
    • 最终 route -4 print 中匹配 10.42.* 的条目。

6.4 何时需要重新运行

  • 集群新增/移除节点后;
  • Calico IPAM 新增/回收了 /26 块(如扩容 Pod 网段、大量 Pod 调度导致分配变化);
  • 节点 InternalIP 发生变化;
  • 本机重装系统、清过路由表,或换了开发机;
  • 发现访问某些 10.42.x.x 不通时。

建议:把脚本加入日常检查清单,集群网络结构变更后主动重跑一次。

6.5 权限与安全说明

  • 脚本需要管理员权限是为了调用 route 命令修改系统路由表;
  • 脚本只删除目标在 10.42.* 且掩码为 /16 或 /26 的持久路由,不影响其他网段、其他掩码的路由;
  • 脚本读取集群信息使用当前 context 的凭据,不会修改集群任何资源(全程只读)。

七、验证连通性

路由添加完成后,按以下顺序验证。

7.1 查看本机路由表

1
route -4 print | findstr /r /c:"10\.42\."

应能看到多条目标为某个 /26 块网段(如 10.42.7.64、10.42.200.128,以集群实际分配为准)、掩码 255.255.255.192、网关为某节点 IP 的条目。

7.2 确认网关可达

路由能生效的前提是网关(节点 IP)本身可达:

1
ping <节点InternalIP>

若节点 IP 都 ping 不通,说明办公网到集群节点网络未打通,需先解决底层网络(这是本方案的前置网络条件)。

7.3 测试 Pod IP 连通性

从日志或集群中挑一个正在运行的 Pod IP:

1
2
3
4
5
6
7
8
9
# 在集群里找一个 Pod IP
kubectl get pod -A -o wide | findstr Running

# 本机 ping 测试(部分 Pod 镜像禁 ping,ping 不通不代表路由失败)
ping 10.42.x.x

# 更可靠:telnet 或 curl 测 Pod 实际监听端口
curl http://<PodIP>:<端口>/actuator/health
telnet <PodIP> <端口>

7.4 端到端验证

在本地 IDE 启动一个服务,确认:

  • 本地服务能从注册中心发现集群里的其他服务(拿到 Pod IP);
  • 本地服务按 Pod IP 调用集群服务能返回正确结果;
  • 抓包/日志确认流量走的是 10.42.x.x 目标地址。

八、日常调试工作流

打通网络后,典型的高效调试流程:

  1. 一次性准备(每个开发环境做一次):
    • 安装 kubectl(第四节);
    • 配置 kubeconfig(第五节);
    • 以管理员运行路由脚本(第六节);
  2. 日常调试(每次迭代):
    • 在 IDE 里只启动你要改的那个服务;
    • 该服务通过注册中心使用集群里现成的数十个依赖服务;
    • 改代码 → 本地热部署/重启 → 立即验证,无需打包上线;
  3. 集群变更时:
    • 集群节点或 IPAM 变更后,重跑一次路由脚本保持路由表最新。

核心收益(重申):把”本地开发”与”集群联调”合并到同一网络平面,单次调试迭代从传统打包上线的 3~15 分钟压缩到本地直连的 5~30 秒,提速约 10~60 倍(典型 20 倍);每天按 20 次迭代估算可节省约 1.5 小时,每周累积约 4~8 小时(≈ 每周多出 1 个工作日的有效开发时间)。详见 1.4 效率提升量化。


九、维护与更新

场景 操作
新增/移除集群节点 重跑 sync-calico-routes.bat
Calico 块分配变化 重跑脚本
kubeconfig 令牌过期 重新下载 kubeconfig 替换 %USERPROFILE%\.kube\config
kubectl 版本过旧 重新下载新版 kubectl.exe 覆盖
本机路由异常/混乱 重跑脚本(会先清理本脚本管理的旧路由再重建)
换开发机 按第三→四→五→六节完整走一遍

日志 route-sync.log 每次运行会被覆盖重写(脚本第 28 行 echo. > "%LOG%"),如需留档请在重跑前自行备份。


十、常见问题排查(FAQ)

Q1:脚本提示”未找到 kubectl”

  • 确认 kubectl.exe 已下载并放在某目录;
  • 确认该目录已加入 PATH,并重新打开命令行窗口;
  • 命令行执行 where kubectl 能定位到 exe 即正常。

Q2:脚本提示”请以管理员身份运行”

  • 关闭窗口,右键脚本 →「以管理员身份运行」;
  • 确认 UAC 弹窗点了”是”。

Q3:kubectl get blockaffinity 失败 / 输出为空

  • 执行 kubectl get blockaffinity.crd.projectcalico.org 手动查看是否报错;
  • 若报 Forbidden,说明当前账号权限不足,需找集群管理员授权(至少对该 CRD 和 nodes 有 get/list 权限);
  • 若返回空,确认集群 CNI 是否为 Calico、Pod 网段是否为 10.42.0.0/16(按本文示例,若自定义过需相应调整脚本里的网段判断);
  • 确认当前 context 指向正确的集群。

Q4:添加路由失败(”网关不可达”)

  • 本质是节点 InternalIP 从本机不可达;先 ping <节点IP> 验证;
  • 检查办公网到集群节点的路由/防火墙/ACL 是否放行;
  • 这是网络层前置条件,需网络管理员配合打通。

Q5:路由加上了,但 Pod IP 还是 ping 不通

  • 部分 Pod 所在镜像/系统禁 ICMP,ping 不通属正常,改用 curl/telnet 测业务端口(见 7.3);
  • 确认目标 Pod IP 确实属于某条 /26 路由覆盖的网段;
  • 检查集群侧 Calico 是否开启 IPIP/BGP 等跨节点转发,节点能否转发目的为 Pod 的流量。

Q6:能访问部分 Pod IP,不能访问另一部分

  • 通常是脚本运行时某些节点 IP 没取到或某些块没加上路由;
  • 打开 route-sync.log,看是否有 [WARN] 找不到节点 ... 的 InternalIP 或”添加失败”;
  • 检查 kubectl get nodes 输出中节点的 .status.addresses[0].address 是否为空(若节点第一个 address 不是 InternalIP,脚本取 [0] 可能取错,需调整脚本取 .status.addresses 中 type=InternalIP 的地址)。

Q7:重启电脑后路由还在吗

  • 在。route -4 -p add 的 -p 是持久路由,写入注册表,重启后自动恢复;
  • 只有脚本登录用户相关的临时变化才需重跑,持久路由无需重启后手动处理。

Q8:脚本会不会误删我的其他路由

  • 不会。删除逻辑严格限定:目标匹配 ^10\.42\. 且掩码为 255.255.0.0(/16) 或 255.255.255.192(/26),其余路由一概不动。

附录 A:脚本逐段解析

脚本行 作用
第 1–4 行 关闭回显、启用延迟变量展开、切换 UTF-8 代码页、设置窗口标题
第 6–21 行 注释:说明脚本作用、用法、前置条件
第 23–26 行 定义变量:脚本目录、日志路径、临时文件前缀、持久路由注册表位置
第 28–29 行 清空并写日志头
第 31–37 行 管理员权限检查(net session)
第 38–43 行 检查 kubectl 是否在 PATH
第 45–58 行 kubectl get blockaffinity 拉取块网段与节点,校验输出非空
第 60–65 行 kubectl get nodes 拉取节点名与 InternalIP
第 67–70 行 把原始 BlockAffinity 与节点映射写入日志
第 72–92 行 遍历注册表持久路由,删除目标 10.42.* 且掩码 /16 或 /26 的旧路由
第 94–125 行 逐块关联节点 IP,调用 :cidr_to_mask 换算掩码,执行 route -4 -p add,统计成功/失败
第 127–130 行 写完成统计与最终 10.42.* 路由表
第 132–139 行 清理临时文件、输出结果、暂停退出
第 141–144 行 :fail 失败处理
第 146–163 行 :cidr_to_mask 工具:CIDR 前缀转点分十进制掩码(支持 /8~/32)
第 165–169 行 :log 工具:同时写日志文件和控制台

关键命令说明

1
2
3
4
5
6
7
8
:: 获取 Calico IPAM 块归属
kubectl get blockaffinity.crd.projectcalico.org -o custom-columns=CIDR:.spec.cidr,NODE:.spec.node --no-headers

:: 获取节点名与 InternalIP(取 addresses[0])
kubectl get nodes -o custom-columns=NODE:.metadata.name,IP:.status.addresses[0].address --no-headers

:: 添加持久静态路由(/26 → 掩码 255.255.255.192)
route -4 -p add <块网段> mask 255.255.255.192 <节点IP>

附录 B:命令速查表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# ---- kubectl 相关 ----
kubectl version --client # 查看客户端版本
kubectl config current-context # 查看当前 context
kubectl config get-contexts # 列出所有 context
kubectl config use-context <名字> # 切换 context
kubectl get nodes # 列出节点
kubectl get nodes -o wide # 列出节点(含 InternalIP)
kubectl get blockaffinity.crd.projectcalico.org # 查看 Calico 块归属

# ---- 路由相关(管理员)----
route -4 print | findstr "10.42" # 查看 10.42 路由
route -4 delete <网段> mask <掩码> # 删除单条路由
route -4 -p add <网段> mask <掩码> <网关> # 添加持久路由

# ---- 连通性验证 ----
ping <节点IP> # 验证网关可达
curl http://<PodIP>:<端口>/actuator/health # 验证 Pod 服务

文档维护:本文为通用技术分享版,配套 sync-calico-routes.bat 使用。若集群网络规划(Pod 网段、CNI 类型)或集群管理版本发生变化,请同步更新本文与脚本中的对应判断。

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
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
@echo off
setlocal EnableDelayedExpansion
chcp 65001 >nul
:: ============================================================
:: 【通用分享版】同步 Calico BlockAffinity 静态路由
:: ------------------------------------------------------------
:: 使用前只需确认下方 POD_NET 与你的集群 Pod 网段一致。
:: POD_NET 为 Pod 网段的前两段,例如 10.42 代表 10.42.0.0/16,
:: 10.244 代表 10.244.0.0/16(RKE2 / Calico 常见默认值)。
:: 脚本运行时动态从集群获取 BlockAffinity 与节点 InternalIP,
:: 不写死任何节点地址、账号、集群名或个人信息,可安全分享。
:: ============================================================
:: ---- 可配置项:修改为你自己集群的 Pod 网段前两段 ----
set "POD_NET=10.42"
set "POD_CIDR=%POD_NET%.0.0/16"
set "POD_REGEX=%POD_NET:.=\.%\."
title 同步 Calico BlockAffinity 静态路由 (%POD_CIDR%)
:: ============================================================
:: 作用:
:: 1. 自动获取 kubeconfig 上下文中所有 Calico BlockAffinity
:: (块网段 -> 所属节点名),并查节点的 InternalIP。
:: 2. 删除本机上"本脚本此前添加"的旧 Pod 网段持久静态路由
:: (仅识别并删除目标在 POD_CIDR 且掩码为 /16 或 /26 的
:: 持久路由;不动其它目标网段、其它掩码的条目)。
:: 3. 为当前每个有效的 /26 块添加持久静态路由:
:: 目标网段 -> 负责该块的节点 IP
:: 4. 生成日志到本目录下 route-sync.log,供事后核查。
::
:: 用法:右键"以管理员身份运行"。
:: 前置:kubectl 在 PATH 中、kubeconfig 可用、可连集群。
:: 说明:route 命令不支持给路由打注释,因此通过"目标网段 +
:: 掩码"精确识别本脚本管理的路由条目,避免误删无关路由。
:: ============================================================
set "SCRIPT_DIR=%~dp0"
set "LOG=%SCRIPT_DIR%route-sync.log"
set "TMP=%TEMP%\calico_route_sync_%RANDOM%"
set "REG=HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\PersistentRoutes"
echo. > "%LOG%"
call :log ==== %date% %time% 开始同步 Calico 路由 ====
:: ---- 1. 管理员权限检查 ----
net session >nul 2>&1
if errorlevel 1 (
call :log [ERROR] 请以管理员身份运行本脚本!
echo [ERROR] 请以管理员身份运行本脚本!
goto :fail
)
where kubectl >nul 2>&1
if errorlevel 1 (
call :log [ERROR] 未找到 kubectl,请确认已安装并加入 PATH。
echo [ERROR] 未找到 kubectl,请确认已加入 PATH。
goto :fail
)
:: ---- 2. 拉取 BlockAffinity (CIDR:.spec.cidr, NODE:.spec.node) ----
kubectl get blockaffinity.crd.projectcalico.org -o custom-columns=CIDR:.spec.cidr,NODE:.spec.node --no-headers > "%TMP%.ba" 2>"%TMP%.err"
if errorlevel 1 (
call :log [ERROR] kubectl get blockaffinity 失败:
type "%TMP%.err" >> "%LOG%"
echo [ERROR] kubectl get blockaffinity 失败,详见 %LOG%
goto :fail
)
findstr /r /c:"^[0-9]" "%TMP%.ba" >nul 2>&1
if errorlevel 1 (
call :log [ERROR] 未从 BlockAffinity 解析到有效 CIDR(输出为空或格式异常)。
echo [ERROR] 未解析到有效 BlockAffinity,详见 %LOG%
goto :fail
)
:: ---- 3. 拉取 节点 -> InternalIP 映射 ----
kubectl get nodes -o custom-columns=NODE:.metadata.name,IP:.status.addresses[0].address --no-headers > "%TMP%.nodes" 2>>"%TMP%.err"
if errorlevel 1 (
call :log [ERROR] kubectl get nodes 失败,详见日志。
goto :fail
)
call :log -- 当前 BlockAffinity 原始输出:
for /f "usebackq delims=" %%L in ("%TMP%.ba") do call :log %%L
call :log -- 当前节点 IP 映射:
for /f "usebackq delims=" %%L in ("%TMP%.nodes") do call :log %%L
:: ---- 4. 删除旧的 Pod 网段持久静态路由(目标网段 POD_NET.*,掩码 /16 或 /26) ----
call :log -- 清理旧 Pod 网段持久静态路由(%POD_NET%.*,仅 /16 与 /26)...
for /f "usebackq delims=" %%L in (`reg query "%REG%" 2^>nul`) do (
for /f "tokens=1,* delims= " %%X in ("%%L") do (
set "valname=%%X"
for /f "tokens=1,2,3 delims=," %%a in ("!valname!") do (
set "rnet=%%a"
set "rmask=%%b"
echo !rnet! | findstr /r /c:"^!POD_REGEX!" >nul 2>&1
if not errorlevel 1 (
if /i "!rmask!"=="255.255.0.0" (
call :log 删除旧持久路由: !rnet! !rmask! -> %%c
route -4 delete !rnet! mask !rmask! >nul 2>&1
) else if /i "!rmask!"=="255.255.255.192" (
call :log 删除旧持久路由: !rnet! !rmask! -> %%c
route -4 delete !rnet! mask !rmask! >nul 2>&1
)
)
)
)
)
:: ---- 5. 逐条生成并添加新路由 ----
call :log -- 添加新的 Pod 网段持久静态路由(%POD_NET%.*)...
set /a ok=0
set /a fail=0
for /f "usebackq tokens=1,2" %%A in ("%TMP%.ba") do (
set "cidr=%%A"
set "node=%%B"
set "ip="
for /f "usebackq tokens=1,2" %%M in ("%TMP%.nodes") do (
if /i "%%M"=="!node!" set "ip=%%N"
)
if not defined ip (
call :log [WARN] 找不到节点 !node! 的 InternalIP,跳过 !cidr!
set /a fail+=1
) else (
call :cidr_to_mask "!cidr!" mask
if not defined mask (
call :log [WARN] 无法解析 CIDR !cidr!,跳过。
set /a fail+=1
) else (
for /f "tokens=1,2 delims=/" %%i in ("!cidr!") do set "net=%%i"
call :log 添加 !net!/!mask! -> !ip! ^(!node!^)
route -4 -p add !net! mask !mask! !ip! >nul 2>&1
if errorlevel 1 (
call :log [WARN] 添加失败(网关不可达或路由已存在?)
set /a fail+=1
) else (
set /a ok+=1
)
)
)
)
call :log -- 完成:成功 !ok! 条,失败 !fail! 条。
call :log -- 当前路由表中 Pod 网段(%POD_NET%.*)条目:
for /f "usebackq delims=" %%L in (`route -4 print ^| findstr /r /c:"%POD_REGEX%"`) do call :log %%L
call :log ==== 结束 ====
del "%TMP%.ba" "%TMP%.nodes" "%TMP%.err" >nul 2>&1
echo.
echo 同步完成:成功 !ok! 条,失败 !fail! 条。
echo 日志:%LOG%
echo.
pause
exit /b 0
:fail
echo 同步失败,请查看日志:%LOG%
pause
exit /b 1
:: ---- 工具:CIDR 前缀 -> 点分十进制掩码(支持 /8 /16 /24 /25 /26 /27 /28 /29 /30 /31 /32) ----
:cidr_to_mask
setlocal EnableDelayedExpansion
for /f "tokens=1,2 delims=/" %%a in ("%~1") do set "prefix=%%b"
set "mask="
if "%prefix%"=="8" set "mask=255.0.0.0"
if "%prefix%"=="16" set "mask=255.255.0.0"
if "%prefix%"=="24" set "mask=255.255.255.0"
if "%prefix%"=="25" set "mask=255.255.255.128"
if "%prefix%"=="26" set "mask=255.255.255.192"
if "%prefix%"=="27" set "mask=255.255.255.224"
if "%prefix%"=="28" set "mask=255.255.255.240"
if "%prefix%"=="29" set "mask=255.255.255.248"
if "%prefix%"=="30" set "mask=255.255.255.252"
if "%prefix%"=="31" set "mask=255.255.255.254"
if "%prefix%"=="32" set "mask=255.255.255.255"
endlocal & set "%~2=%mask%"
goto :eof
:: ---- 工具:写日志 ----
:log
echo %* >> "%LOG%"
echo %*
goto :eof