重新配置 Kubernetes 默认的 ServiceCIDR

特性状态： Kubernetes v1.33 (GA)
More information about this feature

This is a stable feature in Kubernetes, and has been since version 1.33. It was first available in the v1.27 release.

本文介绍如何重新配置集群中分配的默认 Service IP 范围。

准备开始

你必须拥有一个 Kubernetes 的集群，且必须配置 kubectl 命令行工具让其与你的集群通信。 建议运行本教程的集群至少有两个节点，且这两个节点不能作为控制平面主机。 如果你还没有集群，你可以通过 Minikube 构建一个你自己的集群，或者你可以使用下面的 Kubernetes 练习环境之一：

你的 Kubernetes 服务器版本必须不低于版本 v1.33.

要获知版本信息，请输入 kubectl version.

重新配置 Kubernetes 默认 ServiceCIDR

本文解释了如何管理 Kubernetes 集群中的 Service IP 地址范围，这也会影响集群针对不同 Service 所支持的 IP 协议族。

可用于 Service ClusterIP 的 IP 协议族由传递给 kube-apiserver 的 --service-cluster-ip-range 参数决定。要更好地了解 Service IP 地址分配，请参考 Service IP 地址分配追踪文档。

自 Kubernetes 1.33 起，为集群所配置的 Service IP 协议族会通过名为 kubernetes 的 ServiceCIDR 对象反映。 Kubernetes 的 ServiceCIDR 由第一个启动的 kube-apiserver 实例根据其 --service-cluster-ip-range 参数配置创建。为了确保集群行为一致，所有 kube-apiserver 实例必须使用相同的 --service-cluster-ip-range 配置，其取值需与默认的 kubernetes ServiceCIDR 对象保持一致。

Kubernetes ServiceCIDR 重新配置类别

我们可以将 ServiceCIDR 的重新配置分为以下几种情形：

  • 扩展现有的 ServiceCIDR： 这可以通过添加新的 ServiceCIDR 对象动态完成，无需重新配置 kube-apiserver。 请参考扩展 Service IP 范围的专门文档。
  • 保留主 ServiceCIDR 的单栈到双栈转换： 这意味着引入次要 IP 协议族（IPv6 到仅 IPv4 集群，或 IPv4 到仅 IPv6 集群）， 同时保留原 IP 协议族作为主协议族。 这需要更新 kube-apiserver 配置，并相应修改需要处理这个附加 IP 协议族的各个集群组件。 这些组件包括但不限于 kube-proxy、CNI 或网络插件、服务网格实现和 DNS 服务。
  • 保留主 ServiceCIDR 的双栈到单栈转换： 这意味着从双栈集群中移除次要 IP 协议族，恢复为单一 IP 协议族，同时保留原主 IP 协议族。 除了重新配置这些组件以匹配新的 IP 协议族外，你还可能需要处理那些显式使用被移除 IP 协议族的 Service。

替换默认 ServiceCIDR 的手动操作

重新配置默认 ServiceCIDR 需要集群运维人员、管理员或管理集群生命周期的软件执行一系列手动步骤。 这些通常包括：

  1. 更新 kube-apiserver 配置： 使用新的 IP 范围修改 --service-cluster-ip-range 参数。
  1. 重新配置网络组件：这一步至关重要，具体步骤取决于正在使用的联网组件。 这可能包括更新配置文件、重启代理 Pod，或更新组件以处理新的 ServiceCIDR 和期望的 Pod IP 协议族配置。 典型组件可以是 Kubernetes Service（例如 kube-proxy）的实现、 所配置的网络插件以及服务网格控制器和 DNS 服务器等潜在的其他联网组件， 以确保它们能够正确处理流量并使用新的 IP 协议族配置来执行服务发现。
  1. 管理现有 Service： 如果某些 Service 所使用的 IP 不在新配置的范围内，则需处理这些服务。 你可以选择重新创建（会造成停机并重新分配 IP），或者采取更复杂的重新配置策略。
  2. 重新创建 Kubernetes 内部服务： 如果主 IP 协议族发生变化，或者被替换为另一个不同的网络， 则必须删除并重新创建 kubernetes.default Service，以便从新的 Service CIDR 获取 IP 地址。

示例重新配置步骤

以下步骤描述了受控的重新配置过程，重点是完全替换默认 ServiceCIDR 并重新创建 kubernetes.default Service：

  1. 使用初始的 --service-cluster-ip-range 启动 kube-apiserver。
  2. 创建初始 Service，使其从该范围获取 IP。
  3. 引入新的 ServiceCIDR，作为重新配置的临时目标。
  4. 将默认的 kubernetes ServiceCIDR 标记为删除（由于存在 IP 和 Finalizer，会处于 Pending 状态）。 这将阻止从旧的范围分配新的 IP。
  1. 重新创建现有 Service。这些 Service 应从新的临时 ServiceCIDR 分配 IP。
  2. 使用配置的新 ServiceCIDR 重新启动 kube-apiserver，并关闭旧实例。
  3. 删除 kubernetes.default Service。新的 kube-apiserver 将在新的 ServiceCIDR 范围内重新创建此 Service。

接下来


最后修改 October 26, 2025 at 12:35 PM PST: [zh-cn]sync reconfigure-default-service-ip-ranges (d7d70c850e)