集群 Pod 子网拓扑分布（容器网络 v2）
更新时间：2026-03-11
概述
VPC-ENI 容器网络模式支持指定子网为 Pod 分配 IP，用户可以使用这个能力为不同业务应用 Pod 规划不同子网的 IP 地址。本文档介绍了对 psts 的扩展能力，即集群级子网拓扑分布策略（cpsts）。
说明：使用该功能需要联系百度智能云客服开启白名单。
需求场景
psts 提供了 3 种分配 IP 的策略，可用于解决动态 IP 地址分配、手动 IP 地址分配和固定 IP 场景问题。但一个 psts 仅在一个 namespace 中生效；若不同业务应用需要相同的 IP 地址分配策略，则需要创建多个 psts，重用较复杂。cpsts 提供了集群级子网拓扑分布策略，只需创建一个 cpsts 对象，即可在多个 namespace 下生效，解决多 namespace 的 IP 地址分配策略问题。
方案概述
如下 CRD 数据结构所示，CCE 提供了自定义 CRD 来指定 Pod 子网拓扑分布策略，用于在 CCE 集群中实施指定子网分配 IP 功能。
关键数据结构介绍
集群 Pod 子网拓扑分布 ClusterPodSubnetTopologySpread
集群子网拓扑分布对象（cpsts）在工作时会根据 namespaceSelector 在符合条件的 namespace 下创建 Pod 子网拓扑分布（psts）对象，并依赖 psts 影响 Pod 的 IP 地址分配。数据结构定义如下：
YAML
1apiVersion: cce.baidubce.com/v2alpha1
2kind: ClusterPodSubnetTopologySpread
3metadata:
4 name: <cpsts-name>
5spec:
6 name: <cpsts-name>
7 namespaceSelector:
8 matchLabels:
9 <key>: <value>
10 selector:
11 matchLabels:
12 app: <workload-label>
13 subnets:
14 # 不指定子网内 IP 范围时，格式为 sbn-xxxxxxxx: []
15 sbn-xxxxxxxx:
16 - family: "4"
17 range:
18 - start: <start-ipv4>
19 end: <end-ipv4>
20 strategy:
21 releaseStrategy: TTL
22 ttl: 168h0m0s
23 type: Elastic
24 enableReuseIPAddress: true
25 whenUnsatisfiable: DoNotSchedule该对象的核心字段如下：
| 参数 | 数据类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name |
string |
否 | 拓扑分布对象名。 | |
priority |
int32 |
否 | 0 |
多个子网拓扑约束之间的优先级，数字越大优先级越高。 |
namespaceSelector |
object |
否 | 使用该条件对 namespace 做标签匹配，符合条件的 namespace 中将会创建 psts 子对象。如果不填写该选项， cpsts 默认在所有 namespace 下都创建一个名为 {namespace}-{cpstsName} 的 psts 对象。 |
|
selector |
object |
否 | 使用该条件对 Pod 做标签匹配，符合条件的 Pod 在分配 IP 地址时使用该规则。若 selector 为空，则同 namespace 下所有 Pod 都匹配该规则。 |
|
subnets |
object |
是 | 策略使用的子网，CCE 会从这些子网中为 Pod 分配 IP 地址。 注意： 不指定下方字段时，这里内容应写成 sbn-xxxxxxxx: []；指定下方字段时应写成 sbn-xxxxxxxx:。若使用多个 subnet，类型必须一致，不允许混用专属子网和普通子网。 |
|
subnets.[].family |
string |
否 | IP 地址协议族，取值 "4" 或 "6"。注意： family、range、range[].start、range[].end 四个字段需同时填写或同时不填。 |
|
subnets.[].range |
array |
否 | IP 地址范围。 注意： family、range、range[].start、range[].end 四个字段需同时填写或同时不填。 |
|
subnets.[].range[].start |
string |
否 | 起始 IP 地址。 注意： family、range、range[].start、range[].end 四个字段需同时填写或同时不填。 |
|
subnets.[].range[].end |
string |
否 | 结束 IP 地址。 注意： family、range、range[].start、range[].end 四个字段需同时填写或同时不填。 |
|
strategy |
object |
是 | IP 地址使用和回收策略。 | |
strategy.type |
string |
是 | Elastic |
Elastic：动态分配 IP 地址，可用于任意工作负载；Fixed：永久固定 IP 地址，仅搭配 sts 工作负载；PrimaryENI：独占 ENI 专用 IP 地址。 |
strategy.releaseStrategy |
string |
是 | TTL |
IP 地址释放策略。TTL：Pod 删除后，IP 地址按时间过期；动态 IP 模式下，Pod 删除后 IP 立刻回收；开启 enableReuseIPAddress 时默认 7 天回收。Never：仅搭配 strategy.type: Fixed 使用，代表永不回收。 |
strategy.enableReuseIPAddress |
bool |
否 | false |
是否在 strategy.type: Elastic 场景下开启 IP 重用。开启后在 IP 过期前若同名 Pod 重建，将尽力复用 IP，以达到类似固定 IP 的效果。注意： 若指定了 range 字段，该字段需设为 true。 |
strategy.ttl |
string |
否 | 168h0m0s |
开启 IP 地址重用时，Pod 删除后保留 IP 的时间。默认值为 7 天（168h0m0s）。 |
使用限制
- 该功能需使用 VPC 的 ENI 跨子网分配 IP 功能，请提交工单申请开通。
kube-system命名空间中的 Pod 无法使用指定子网分配 IP 功能。- 使用
ipRange能力时，IP 范围内不要包含特殊 IP 地址（如 IPv4 网络地址、网关地址、广播地址、多播地址），否则可能导致 IP 分配失败。 - 指定子网的 Pod 只能调度到子网所在可用区的节点，请确认该可用区存在 Ready 状态节点。
- 固定 IP 和 IP 重用场景下只能使用专属子网（指定子网仅供单个 CCE 集群使用），专属子网不支持变更为普通子网，也不支持从集群内删除。
- 该功能仅适用于容器网络 v2 版本的集群。
专属子网： 当用户需要为 Pod 分配指定子网下的部分 IP 时，IP 所属子网将自动被标记为手动分配 IP 模式。手动分配 IP 模式下子网有以下特征：
- 专属子网应为当前 CCE 集群专属，CCE 会自动为子网增加专属标签，其他 CCE 集群拒绝使用该子网（用户仍可在百度智能云其他产品中使用该子网）。
- 专属子网仅支持手动分配 IP，不会自动分配 IP，需要用户自行规划并管理 IP 地址。
- 专属子网下 IP 与 Pod 的关系可采用优先分配或固定绑定两种策略。固定绑定策略使用 Pod 名作为绑定标识，同名 Pod 的 IP 地址相同。
- 集群 Pod 的默认子网不能是专属子网，否则可能导致集群中其他 Pod 无法正常分配 IP。
- 专属子网不支持变更为普通子网，也不支持从集群内删除。
配置步骤
环境准备
创建私有子网
导航路径：控制台首页->网络->私有网络 VPC->子网。
- 进入 百度智能云 VPC 控制台->子网选项卡，点击 【创建子网】。
- 在创建页面按集群网络规划填写参数：
| 参数 | 必填 | 说明 |
|---|---|---|
| 所在网络 | 是 | 选择目标 CCE 集群所在的 VPC。 |
| 子网名称 | 是 | 填写可识别的业务子网名称。 |
| 可用区 | 是 | 与目标 CCE 集群节点可用区保持一致，避免调度失败。 |
| IPv4 CIDR | 是 | 按网络规划填写子网网段。 |
| 描述 | 否 | 填写便于识别的用途说明。 |
- 点击 【确定】 完成创建，并在子网列表记录子网 ID（
sbn-xxx）。
说明： 如需使用 ENI 跨子网分配 IP 功能，请提交 工单 申请。
在 CCE 上操作指定子网分配 IP
场景 1：全集群多应用固定 IP
从与 Pod 匹配的子网拓扑约束策略关联子网中动态为 Pod 分配 IP。匹配子网拓扑约束策略（cpsts）的所有 Pod，仅从策略包含的子网分配 IP 地址。
适用场景：
- 以子网维度进行流量统计。
- 以子网维度实施安全策略（如 ACL 规则控制）。
- 通过 NAT 网关为特定子网开启互联网访问。
导航路径：控制台首页->容器服务 CCE->集群列表->目标集群->工作负载->自定义资源。
1. 创建 cpsts
在目标集群的自定义资源页面，选择 cce.baidubce.com/v2alpha1 与 ClusterPodSubnetTopologySpread，点击 【创建资源】，核心配置如下：
YAML
1apiVersion: cce.baidubce.com/v2alpha1
2kind: ClusterPodSubnetTopologySpread
3metadata:
4 name: <cpsts-name>
5spec:
6 name: <cpsts-name>
7 namespaceSelector:
8 matchLabels:
9 <key>: <value>
10 selector:
11 matchLabels:
12 app: <workload-label>
13 subnets:
14 sbn-xxxxxxxx:
15 - family: "4"
16 range:
17 - start: <start-ipv4>
18 end: <end-ipv4>
19 strategy:
20 releaseStrategy: TTL
21 ttl: 168h0m0s
22 type: Elastic
23 enableReuseIPAddress: true
24 whenUnsatisfiable: DoNotSchedule2. 创建工作负载
YAML
1apiVersion: apps/v1
2kind: StatefulSet
3metadata:
4 name: <workload-name>
5 namespace: <namespace>
6spec:
7 replicas: 1
8 selector:
9 matchLabels:
10 app: <workload-label>
11 serviceName: <service-name>
12 template:
13 metadata:
14 labels:
15 workloadType: sts
16 fixedIP: "true"
17 app: <workload-label>
18 spec:
19 containers:
20 - image: nginx
21 name: nginx3. 验证 IP 分配结果
执行 kubectl get pod <pod-name> -o yaml，确认 Pod 注解与调度约束生效，示例如下：
YAML
1apiVersion: v1
2kind: Pod
3metadata:
4 annotations:
5 cce.baidubce.com/PodSubnetTopologySpread: <psts-name>
6 labels:
7 app: <workload-label>
8 name: <pod-name>
9 namespace: <namespace>
10spec:
11 affinity:
12 nodeAffinity:
13 requiredDuringSchedulingIgnoredDuringExecution:
14 nodeSelectorTerms:
15 - matchExpressions:
16 - key: topology.kubernetes.io/zone
17 operator: In
18 values:
19 - <zone>
20 containers:
21 - image: nginx
22 imagePullPolicy: IfNotPresent
23 name: nginx
24 resources:
25 limits:
26 cce.baidubce.com/ip: "1"
27 requests:
28 cce.baidubce.com/ip: "1"