跳到主要内容
08:44:02
🔅🔆

混合版本代理

特性状态： Kubernetes v1.36 起 Beta（默认启用）

官方文档参考​

项目链接
混合版本代理（官方中文文档）https://kubernetes.io/zh-cn/docs/concepts/architecture/mixed-version-proxy/

解决什么问题？​

Kubernetes 允许 kube-apiserver 之间在滚动升级期间存在版本偏差（skew）：HA 集群中的多台 API 服务器被逐台升级时，集群会短暂处于"新旧版本并存"的混合状态。这时会出现一个典型问题：

  • 新版本引入（或移除）的 API 组/版本/资源，只在部分 API 服务器上可用；
  • 客户端的请求经过负载均衡随机落到某一台 API 服务器，落到"不认识该 API"的旧服务器上时，会得到意外的 404 Not Found 错误；
  • 这类错误发生在升级窗口期内，对用户表现为"时好时坏"，极难排查。

Kubernetes 1.37 包含了一个特性，可以让 API 服务器 代理指向其他对等（peer）API 服务器的资源请求，并允许客户端通过发现功能全面了解整个集群提供的资源。当一个集群中运行着多个 API 服务器、且各服务器的 Kubernetes 版本不同时（例如上线 Kubernetes 新版本的时间跨度较长时），这一特性非常有用。

这使得集群管理员能够配置高可用性集群，并能更安全地进行升级，具体方式是：将升级期间发起的资源请求导向正确的 kube-apiserver。这种代理防止用户看到由升级过程导致的意外的 404 未找到错误。此机制被称为混合版本代理（Mixed Version Proxy，MVP）。

工作原理总览​

启用混合版本代理时，聚合层会加载一个特殊的过滤器，完成以下操作：当资源请求到达一个无法提供该 API 的 API 服务器时（可能的原因是服务器版本早于该 API 的正式引入日期，或该 API 在此服务器上被关闭），API 服务器会尝试将请求发送到能够提供所请求 API 的对等 API 服务器。API 服务器通过发现本地服务器无法识别的 API 组/版本/资源来实现这一点，并尝试将这些请求代理到能够处理这些请求的对等 API 服务器。

一张图看懂请求的转发路径：

混合版本代理工作原理

内部工作原理​

当 API 服务器收到一个资源请求时，它首先利用非对等聚合发现文档检查哪些 API 服务器可以提供所请求的资源，然后按下面的决策链处理：

序号场景处理方式最终响应
1请求的资源出现在本机检索到的非对等聚合发现文档中（例如 GET /api/v1/pods/some-pod）本地处理正常响应
2请求的资源未在本机发现文档中找到（例如 GET /apis/resource.k8s.io/v1beta1/resourceclaims，而该 API 在较新版本才引入）本地服务器检查所有对等 API 服务器的非对等聚合发现文档，找到能提供该 API 组/版本/资源的对等方，将请求代理过去由匹配的对等 kube-apiserver 响应
3没有任何对等方认识所请求的 API 组/版本/资源处理请求的 API 服务器将请求传递给自己的处理程序链404 Not Found
4已选中某个对等 API 服务器，但该对等方无法响应（如网络连接问题，或请求与向控制平面注册对等信息的控制器之间存在数据竞争）源 API 服务器直接返回错误503 Service Unavailable
理解"非对等聚合发现文档"

对等聚合发现（peer-aggregated discovery）会把集群中所有 API 服务器提供的资源合并成一份总发现文档；而"非对等"版本只反映本机能提供的资源。MVP 正是靠对比"非对等发现文档"来判断某个 API 是否该转发给对等方的。

对等聚合发现​

当你启用该特性时，默认情况下，发现请求会自动提供一个全面的发现文档——列出集群中任何 API 服务器提供的所有资源。客户端只需访问任意一台 API 服务器，即可看到全集群能力视图，不再受"连到哪台就看到哪个版本"的困扰。

如果你想要请求一个非对等聚合的发现文档，可以在发现请求中添加以下 Accept 标头：

application/json;g=apidiscovery.k8s.io;v=v2;as=APIGroupDiscoveryList;profile=nopeer
仅支持聚合发现端点

对等聚合发现仅支持向 /apis 端点发出的聚合发现请求，而不支持未聚合（旧版）发现请求。

如何启用​

背景知识：该特性对应 kube-apiserver 的 UnknownVersionInteroperabilityProxy 特性门控（KEP-5920，Mixed Version Proxy / 混合版本集群互操作）。以下为官方给出的启动配置。

当你启动 API 服务器时，确保启用了 UnknownVersionInteroperabilityProxy 特性门控，并配置对等互连所需的证书与地址参数：

kube-apiserver \
  --feature-gates=UnknownVersionInteroperabilityProxy=true \
  # 需要为此特性添加的命令行参数
  --peer-ca-file=<指向 kube-apiserver CA 证书的路径> \
  --proxy-client-cert-file=<指向聚合器代理证书的路径> \
  --proxy-client-key-file=<指向聚合器代理密钥的路径> \
  --requestheader-client-ca-file=<指向聚合器 CA 证书的路径> \
  # requestheader-allowed-names 可设置为空以允许所有 Common Name
  --requestheader-allowed-names=<验证代理客户端证书的合法 Common Name> \
  # 此特性的可选标志
  --peer-advertise-ip=<应由对等方用于代理请求的 kube-apiserver IP> \
  --peer-advertise-port=<应由对等方用于代理请求的 kube-apiserver 端口> \
  # ... 和其他常规标志

参数速查表：

参数作用是否必需
--feature-gates=UnknownVersionInteroperabilityProxy=true启用混合版本代理特性启用特性时必需
--peer-ca-file为源 API 服务器配置证书机构包，用于验证目标（对等）服务器的证书是
--proxy-client-cert-file / --proxy-client-key-file源 kube-apiserver 重用现有的 API 服务器客户端身份验证标志，向对等方表明身份是（复用聚合层既有证书）
--requestheader-client-ca-file目标 API 服务器据此验证对等连接是（复用聚合层既有证书）
--requestheader-allowed-names验证代理客户端证书的合法 Common Name，可置空以允许所有 CN可选
--peer-advertise-ip / --peer-advertise-port告知对等方本机的网络位置，用于反向代理请求可选（见下）

对等 API 服务器连接的配置​

  • 代理传输与身份验证：源 kube-apiserver 重用现有的 API 服务器客户端身份验证标志 --proxy-client-cert-file 和 --proxy-client-key-file 来表明其身份，供对等（目标 kube-apiserver）验证。目标 API 服务器根据 --requestheader-client-ca-file 指定的配置来验证对等连接。要对目标服务器所用的证书进行身份验证，必须通过 --peer-ca-file 为源 API 服务器配置一个证书机构包。
  • 对等网络位置：使用 --peer-advertise-ip 和 --peer-advertise-port 命令行参数（或在 API 服务器配置文件中指定这些字段）来设置 kube-apiserver 的网络位置，供对等方来代理请求。如果未指定这些参数，对等方将使用 --advertise-address 或 --bind-address 参数的值；如果这些也未设置，则使用主机的默认接口。

我的总结与避坑清单​

  1. MVP 只解决升级窗口期的 404：它的价值场景是"多台 API 服务器版本不同"的滚动升级期，平时单版本集群用不到转发逻辑；不要把它当成常驻的版本路由器。
  2. 默认 Beta、v1.36 起默认启用，但依赖 kube-apiserver 侧配置对等证书（--peer-ca-file 等）才能完整工作，升级 HA 集群前先检查控制面参数。
  3. 决策链记四步：本机能识别 → 本地处理；本机不认识但有对等方认识 → 代理转发；谁都不认识 → 404；对等方选定了但连不上 → 503。
  4. 503 不等于服务挂了：升级期间偶发 503 可能是 MVP 转发失败（网络问题或对等注册控制器的数据竞争），看到 503 先查对端 API 服务器状态和 --peer-advertise-ip/port 配置。
  5. 发现文档有两套：默认的对等聚合发现是"全集群视图"，加 profile=nopeer 的 Accept 标头才能拿到本机视图；客户端做 API 能力探测时要清楚自己读到的是哪一份。
  6. 只支持聚合发现：对等聚合发现仅覆盖 /apis 端点的聚合发现请求，仍依赖旧版非聚合发现的老客户端无法享受该能力。
  7. 复用聚合层证书但新增 peer CA：--proxy-client-cert-file、--requestheader-client-ca-file 等与聚合层（aggregation layer）共用，新增的是 --peer-ca-file；证书配置错误会表现为对等代理链路全部失败。
  8. --peer-advertise-ip/port 有兜底顺序：未设置时依次回退到 --advertise-address、--bind-address、主机默认接口；负载均衡器后面的 API 服务器建议显式指定，避免对等方代理到错误的地址。
  9. 升级策略配合：即使启用了 MVP，滚动升级仍应遵循官方版本偏差规则（kubelet 等组件与 API 服务器的版本差上限），MVP 只是抹平 API 请求层的偏差，不放宽其他组件的兼容性约束。
  10. 排障入口：升级期间出现"API 时有时无"时，优先确认各 API 服务器版本的 kubectl get --raw /apis 输出差异，再检查 MVP 的门控与证书参数，最后查对等连接的网络可达性。
🛡️本站已安全运行2334天23时18分58秒
Bottom GIF
Top GIF