Kubernetes 默认服务 CIDR 重配置

特性状态： Kubernetes v1.33 [stable] （默认启用：true）

本文档介绍了如何重新配置分配给集群的默认服务 IP 范围。

准备工作

你需要有一个 Kubernetes 集群，并且 kubectl 命令行工具已配置为与你的集群通信。建议在至少有两个不充当控制平面主机的节点的集群上运行本教程。如果你还没有集群，可以使用 minikube 创建，或者使用这些 Kubernetes 游乐场之一

你的 Kubernetes 服务器版本必须是 v1.33 或更高版本。

要检查版本，请输入 kubectl version。

Kubernetes 默认服务 CIDR 重配置

本文档解释了如何在 Kubernetes 集群中管理服务 IP 地址范围，这也会影响集群服务支持的 IP 族。

服务 ClusterIP 可用的 IP 族由 kube-apiserver 的 `--service-cluster-ip-range` 标志决定。为了更好地理解服务 IP 地址分配，请参阅 服务 IP 地址分配跟踪 文档。

自 Kubernetes 1.33 起，为集群配置的服务 IP 族由名为 `kubernetes` 的 `ServiceCIDR` 对象反映。`kubernetes` `ServiceCIDR` 对象由第一个启动的 kube-apiserver 实例根据其配置的 `--service-cluster-ip-range` 标志创建。为了确保一致的集群行为，所有 kube-apiserver 实例都必须配置相同的 `--service-cluster-ip-range` 值，并且这些值必须与默认的 kubernetes ServiceCIDR 对象匹配。

Kubernetes 服务 CIDR 重新配置类别

我们可以将服务 CIDR 重新配置分为以下几种场景：

  • 扩展现有服务 CIDR：这可以通过添加新的 ServiceCIDR 对象动态完成，无需重新配置 kube-apiserver。请参阅关于 扩展服务 IP 范围 的专门文档。

  • 单栈到双栈转换并保留主服务 CIDR：这涉及引入辅助 IP 族（将 IPv6 引入仅支持 IPv4 的集群，或将 IPv4 引入仅支持 IPv6 的集群），同时保留原始 IP 族作为主 IP 族。这需要更新 kube-apiserver 配置以及对需要处理此附加 IP 族的各种集群组件进行相应修改。这些组件包括但不限于 kube-proxy、CNI 或网络插件、服务网格实现和 DNS 服务。

  • 双栈到单栈转换并保留主服务 CIDR：这涉及从双栈集群中移除辅助 IP 族，恢复为单 IP 族，同时保留原始主 IP 族。除了重新配置组件以匹配新的 IP 族外，你可能还需要处理明确配置为使用已移除 IP 族的服务。

  • 任何导致主服务 CIDR 更改的操作：完全替换默认 ServiceCIDR 是一项复杂的操作。如果新的 ServiceCIDR 与现有 ServiceCIDR 不重叠，它将需要重新编号所有现有服务并更改 `kubernetes.default` 服务。如果主 IP 族也发生变化，情况会更加复杂，可能需要更改多个集群组件（kubelet、网络插件等）以匹配新的主 IP 族。

替换默认服务 CIDR 的手动操作

重新配置默认服务 CIDR 需要集群操作员、管理员或管理集群生命周期的软件执行手动步骤。这些步骤通常包括：

  1. 更新 kube-apiserver 配置：使用新的 IP 范围修改 `—service-cluster-ip-range` 标志。
  2. 重新配置网络组件：这是一个关键步骤，具体过程取决于所使用的不同网络组件。它可能涉及更新配置文件、重启代理 Pod，或更新组件以管理新的 Service CIDR 和 Pod 所需的 IP 族配置。典型的组件可以是 Kubernetes 服务的实现，例如 kube-proxy 和配置的网络插件，以及可能存在的其他网络组件，如服务网格控制器和 DNS 服务器，以确保它们能够正确处理流量并使用新的 IP 族配置执行服务发现。
  3. 管理现有服务：如果来自旧 CIDR 的 IP 不在新配置的范围内，则需要处理这些服务。选项包括重新创建（导致停机和新的 IP 分配）或可能更复杂的重新配置策略。
  4. 重新创建内部 Kubernetes 服务：如果主 IP 族更改或被其他网络替换，则必须删除并重新创建 `kubernetes.default` 服务，以从新的服务 CIDR 获取 IP 地址。

重新配置示例步骤

以下步骤描述了控制下重新配置，重点是完全替换默认 Service CIDR 和重新创建 `kubernetes.default` Service。

  1. 使用初始的 `—service-cluster-ip-range` 启动 kube-apiserver。
  2. 创建从该范围获取 IP 的初始服务。
  3. 引入一个新的 Service CIDR 作为重新配置的临时目标。
  4. 将 `kubernetes` 默认 Service CIDR 标记为删除（由于现有 IP 和 finalizers，它将保持待定状态）。这可以防止从旧范围进行新的分配。
  5. 重新创建现有服务。它们现在应该从新的临时 Service CIDR 中分配 IP。
  6. 使用新的 Service CIDR 配置并关闭旧实例后，重新启动 kube-apiserver。
  7. 删除 `kubernetes.default` 服务。新的 kube-apiserver 将在新的 Service CIDR 中重新创建它。

下一步

最后修改时间：2025 年 7 月 8 日，太平洋标准时间上午 12:58：修复超链接 (f57c7d58a4)