混合版本代理

特性状态： Kubernetes v1.28 [alpha]

Kubernetes 1.29 包含了一个 Alpha 特性，可以让 API 服务器代理指向其他对等 API 服务器的资源请求。当一个集群中运行着多个 API 服务器，且各服务器的 Kubernetes 版本不同时 （例如在上线 Kubernetes 新版本的时间跨度较长时），这一特性非常有用。

此特性通过将（升级过程中所发起的）资源请求引导到正确的 kube-apiserver 使得集群管理员能够配置高可用的、升级动作更安全的集群。 该代理机制可以防止用户在升级过程中看到意外的 404 Not Found 错误。

这个机制称为 Mixed Version Proxy（混合版本代理）。

启用混合版本代理

当你启动 API 服务器时， 确保启用了 UnknownVersionInteroperabilityProxy 特性门控：

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

API 服务器之间的代理传输和身份验证

  • 源 kube-apiserver 重用现有的 API 服务器客户端身份验证标志 --proxy-client-cert-file 和 --proxy-client-key-file 来表明其身份，供对等（目标 kube-apiserver）验证。 目标 API 服务器根据你使用 --requestheader-client-ca-file 命令行参数指定的配置来验证对等连接。

  • 要对目标服务器所用的证书进行身份验证，必须通过指定 --peer-ca-file 命令行参数来为源 API 服务器配置一个证书机构包。

对等 API 服务器连接的配置

要设置 kube-apiserver 的网络位置以供对等方来代理请求， 使用为 kube-apiserver 设置的 --peer-advertise-ip 和 --peer-advertise-port 命令行参数， 或在 API 服务器配置文件中指定这些字段。如果未指定这些参数，对等方将使用 --advertise-address 或 --bind-address 命令行参数的值。如果这些也未设置，则使用主机的默认接口。

混合版本代理

启用混合版本代理时， 聚合层会加载一个特殊的过滤器， 完成以下操作：

  • 当资源请求到达无法提供该 API 的 API 服务器时 （可能的原因是服务器早于该 API 的正式引入日期或该 API 在 API 服务器上被关闭）， API 服务器会尝试将请求发送到能够提供所请求 API 的对等 API 服务器。 API 服务器通过发现本地服务器无法识别的 API 组/版本/资源来实现这一点， 并尝试将这些请求代理到能够处理这些请求的对等 API 服务器。
  • 如果对等 API 服务器无法响应，则源 API 服务器将以 503（”Service Unavailable”）错误进行响应。

内部工作原理

当 API 服务器收到一个资源请求时，它首先检查哪些 API 服务器可以提供所请求的资源。 这个检查是使用内部的 StorageVersion API 进行的。

  • 如果资源被收到请求（例如 GET /api/v1/pods/some-pod）的 API 服务器所了解，则请求会在本地处理。

  • 如果没有找到适合所请求资源（例如 GET /my-api/v1/my-resource）的内部 StorageVersion 对象， 并且所配置的 APIService 设置了指向扩展 API 服务器的代理，那么代理操作将按照扩展 API 的常规流程进行。

  • 如果找到了对应所请求资源（例如 GET /batch/v1/jobs）的合法的内部 StorageVersion 对象， 并且正在处理请求的 API 服务器（处理中的 API 服务器）禁用了 batch API， 则正处理的 API 服务器使用已获取的 StorageVersion 对象中的信息， 获取提供相关 API 组/版本/资源（在此情况下为 api/v1/batch）的对等 API 服务器。 处理中的 API 服务器随后将请求代理到能够理解所请求资源且匹配的对等 kube-apiserver 之一。

    • 如果没有对等方了解所给的 API 组/版本/资源，则处理请求的 API 服务器将请求传递给自己的处理程序链， 最终应返回 404（”Not Found”）响应。

    • 如果处理请求的 API 服务器已经识别并选择了一个对等 API 服务器，但该对等方无法响应 （原因可能是网络连接问题或正接收的请求与向控制平面注册对等信息的控制器之间存在数据竞争等）， 则处理请求的 API 服务器会以 503（”Service Unavailable”）错误进行响应。