Kubernetes Python 客户端模型详解:V1WeightedPodAffinityTerm 加权 Pod 亲和性调度
Kubernetes Python 客户端模型详解:V1WeightedPodAffinityTerm 加权 Pod 亲和性调度
V1WeightedPodAffinityTerm 是 Kubernetes 官方 Python 客户端(kubernetes.aio.client.models 异步客户端模型)中用于表达软性(preferred)Pod 亲和/反亲和规则的核心数据模型。它把一个 podAffinityTerm 亲和性术语与一个 1–100 的整数权重绑定起来,供调度器在 preferredDuringSchedulingIgnoredDuringExecution 字段中按节点累计权重、挑选最优节点。读完本文,你将掌握该模型的全部字段、底层 OpenAPI 定义、与 V1PodAffinity / V1PodAntiAffinity 的调用关系,以及如何在 Python 中构造、序列化与反序列化它。
模型定位:软性亲和规则的"带权单元"
在 Kubernetes 调度中,Pod 亲和性分为两类:
- 硬性(required)规则:调度时若不满足则 Pod 不会被调度到该节点;
- 软性(preferred)规则:调度器"倾向于"把 Pod 放到满足条件的节点,但不强制,即使不满足也会被调度。
V1WeightedPodAffinityTerm 正是软性规则的基本组成单元。它的类注释明确说明了设计意图:
"The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s)"(所有匹配的 WeightedPodAffinityTerm 权重按节点累加,用于找出最受偏好的节点)
也就是说,每个软性亲和条目 = 一条 podAffinityTerm(描述"与哪些 Pod 靠拢/远离")+ 一个 weight(描述这条规则的优先程度)。当多个软性规则同时命中某个节点时,调度器把它们的权重相加,权重和最高的节点最优先。
字段详解与类型约束
该模型只有两个字段,且根据 OpenAPI 定义(见 kubernetes/swagger.json.unprocessed)二者均为必填(required):
| 字段 | Python 类型 | JSON 名称 | 必填 | 说明 |
|---|---|---|---|---|
pod_affinity_term |
V1PodAffinityTerm |
podAffinityTerm |
是 | 一条 Pod 亲和性术语,定义了需要匹配的 Pod 集合及拓扑键 |
weight |
StrictInt |
weight |
是 | 与该 podAffinityTerm 匹配时累加的权重,取值范围 1–100 |
源码实现位于 kubernetes/aio/client/models/v1_weighted_pod_affinity_term.py:
class V1WeightedPodAffinityTerm(BaseModel):
pod_affinity_term: V1PodAffinityTerm = Field(
validation_alias=AliasChoices("podAffinityTerm", "pod_affinity_term"),
serialization_alias="podAffinityTerm"
)
weight: StrictInt = Field(
description="weight associated with matching the corresponding podAffinityTerm, in the range 1-100."
)
从源码可以看到几个重要细节:
weight使用 pydantic 的StrictInt,严格整数校验,传入非整数类型(如字符串"10")会校验失败;- 字段同时支持下划线命名(
pod_affinity_term)和 JSON 别名命名(podAffinityTerm)两种输入方式,AliasChoices使构造与反序列化更灵活; - 模型的
model_config设置了extra="forbid"(见同文件 ConfigDict 配置),传入未声明的多余字段会被拒绝,保证与 Kubernetes OpenAPI schema 严格对齐。
对应的 OpenAPI 原始定义
在客户端库所依据的 Kubernetes OpenAPI 文档(release-1.37)中,该类型的定义如下(摘录自 kubernetes/swagger.json.unprocessed):
"io.k8s.api.core.v1.WeightedPodAffinityTerm": {
"description": "The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s)",
"properties": {
"podAffinityTerm": {
"$ref": "#/definitions/io.k8s.api.core.v1.PodAffinityTerm",
"description": "Required. A pod affinity term, associated with the corresponding weight."
},
"weight": {
"description": "weight associated with matching the corresponding podAffinityTerm, in the range 1-100.",
"format": "int32",
"type": "integer"
}
},
"required": ["weight", "podAffinityTerm"],
"type": "object"
}
weight 在 OpenAPI 中为 int32 格式的整数,与 Python 端的 StrictInt 完全对应;podAffinityTerm 明确标注为 "Required"(必填)。
内嵌结构 V1PodAffinityTerm:描述"与谁亲和"
pod_affinity_term 字段的类型是 V1PodAffinityTerm,它本身是一个信息量更大的模型,定义了"哪些 Pod 参与匹配"以及"在什么拓扑维度上判定共置"。其源码见 kubernetes/aio/client/models/v1_pod_affinity_term.py,字段如下:
| 字段 | 类型 | 说明 |
|---|---|---|
label_selector |
Optional[V1LabelSelector] |
选择器,选中"要与之共置(亲和)或隔离(反亲和)"的目标 Pod 集合 |
match_label_keys |
Optional[List[str]] |
从待调度 Pod 自身的标签中提取键值,以 key in (value) 形式合并进 labelSelector;键不存在则忽略;不能与 labelSelector 中出现相同的键,且必须在设置了 labelSelector 时才能使用 |
mismatch_label_keys |
Optional[List[str]] |
与 matchLabelKeys 相反,以 key notin (value) 形式合并;约束同上 |
namespace_selector |
Optional[V1LabelSelector] |
按标签选择参与匹配的命名空间集合 |
namespaces |
Optional[List[str]] |
静态命名空间名称列表,与 namespaceSelector 的结果取并集;两者都为空时表示"当前 Pod 所在的命名空间" |
topology_key |
str(必填) |
拓扑键,例如 kubernetes.io/hostname、topology.kubernetes.io/zone;判定共置的标准是"运行目标 Pod 的节点上该标签的值与当前节点相同",不允许为空 |
构造一个 V1WeightedPodAffinityTerm 的典型 Python 写法:
from kubernetes.aio.client.models.v1_weighted_pod_affinity_term import V1WeightedPodAffinityTerm
from kubernetes.aio.client.models.v1_pod_affinity_term import V1PodAffinityTerm
from kubernetes.aio.client.models.v1_label_selector import V1LabelSelector
term = V1WeightedPodAffinityTerm(
weight=50,
pod_affinity_term=V1PodAffinityTerm(
label_selector=V1LabelSelector(
match_labels={"app": "cache"}
),
topology_key="kubernetes.io/hostname",
),
)
这段代码表达的意思是:调度器偏好(权重 50)将本 Pod 调度到"已经运行着标签为 app=cache 的 Pod、且位于同一主机(hostname 拓扑)"的节点上。
在 V1PodAffinity / V1PodAntiAffinity 中的调度机制
V1WeightedPodAffinityTerm 不会单独出现,它总是以列表形式挂在 V1PodAffinity 或 V1PodAntiAffinity 的 preferred_during_scheduling_ignored_during_execution 字段下。
亲和场景(V1PodAffinity):权重相加
源码见 kubernetes/aio/client/models/v1_pod_affinity.py,其字段注释给出了精确的计分算法:
对每个满足全部调度要求(资源请求、required 亲和表达式等)的节点,遍历本字段的所有元素:若节点上有 Pod 命中对应的
podAffinityTerm,就把该条目的weight加到总和上;总和最高的节点最受偏好。
from kubernetes.aio.client.models.v1_pod_affinity import V1PodAffinity
affinity = V1PodAffinity(
preferred_during_scheduling_ignored_during_execution=[
V1WeightedPodAffinityTerm(weight=50, pod_affinity_term=...),
V1WeightedPodAffinityTerm(weight=30, pod_affinity_term=...),
]
)
反亲和场景(V1PodAntiAffinity):权重相减
在 kubernetes/aio/client/models/v1_pod_anti_affinity.py 中,机制完全对称但方向相反:
对每个满足条件的节点,若节点上有 Pod 命中对应的
podAffinityTerm,就把该条目的weight从总和中减去;结果最高者最受偏好。
因此,通过给亲和条目与反亲和条目分别设置不同的权重,可以精细控制"尽量共置"与"尽量分散"两种诉求的优先级,这正是 preferred(软性)规则区别于 required(硬性)规则的灵活性所在——前者只影响节点的"偏好打分",后者才是一票否决式的硬约束。
序列化与反序列化 API
与仓库中其他 OpenAPI 生成的模型一致,V1WeightedPodAffinityTerm 提供了一套完整的转换方法(见 kubernetes/aio/client/models/v1_weighted_pod_affinity_term.py):
# 从 JSON 字符串创建实例
obj = V1WeightedPodAffinityTerm.from_json(json_str)
# 从 dict 创建实例(同时接受 {"podAffinityTerm": ...} 与 {"pod_affinity_term": ...})
obj = V1WeightedPodAffinityTerm.from_dict({
"podAffinityTerm": {
"labelSelector": {"matchLabels": {"app": "cache"}},
"topologyKey": "kubernetes.io/hostname",
},
"weight": 50,
})
# 序列化回 dict(默认使用下划线命名的公开字段)
d = obj.to_dict()
# 序列化回 dict(serialize=True 时使用 JSON 线格式字段名 podAffinityTerm)
d_wire = obj.to_dict(serialize=True)
# 输出 JSON 字符串(使用 JSON 别名 podAffinityTerm)
print(obj.to_json())
# 人性化可读字符串
print(obj.to_str())
关键实现细节:
- 别名双向兼容:
from_dict内部通过__preprocess_input_names(源码实现)把下划线形式pod_affinity_term归一化为 JSON 别名podAffinityTerm,因此无论你手头的 dict 是来自kubectl输出的 JSON 还是手写 Python 字典,都能正确解析; - 嵌套模型递归转换:
pod_affinity_term是嵌套模型,其 dict 转换会递归调用V1PodAffinityTerm.from_dict(见 from_dict 实现),确保深层结构完整; - 相等性判定:模型重写了
__eq__,基于to_dict()结果比较,便于测试断言。
同步与异步客户端的对应实现
本文关联文档对应的是异步客户端 kubernetes.aio.client.models 命名空间,但同步客户端 kubernetes.client.models 中也有完全同构的实现(kubernetes/client/models/v1_weighted_pod_affinity_term.py),字段、方法与异步版本一致。二者均由 OpenAPI Generator 基于同一份 release-1.37 的 OpenAPI 文档生成,区别仅在于所属包路径与异步生态的配合方式。仓库中两个版本的模型文档分别位于 kubernetes/aio/docs/V1WeightedPodAffinityTerm.md 与 kubernetes/docs/V1WeightedPodAffinityTerm.md。
使用建议与注意事项
- 权重范围务必在 1–100 之间:超出范围的数值虽可能通过 Python 层的
StrictInt类型校验,但会被 API Server 拒绝,因为 OpenAPI 定义明确限定该范围; pod_affinity_term不可省略:它是必填字段,且在V1PodAffinityTerm内部topology_key同样必填且不能为空字符串;- 区分软硬规则:把加权条目放进
preferred_during_scheduling_ignored_during_execution得到的是"偏好"语义;若需要硬性约束,应使用V1PodAffinityTerm(不带权重)放入required_during_scheduling_ignored_during_execution; - 多条目打分:同一节点命中多条软性规则时权重累加(亲和)或累减(反亲和),因此设计多组加权规则时要注意各权重之间的相对大小关系,它们共同决定节点的最终优先级排序。
结合以上模型定义、OpenAPI 原始 schema 与调度语义,你可以在 Python 中精准构建 Kubernetes 的软性 Pod 亲和/反亲和配置,并通过 to_dict / to_json 无缝接入 V1PodSpec 的 affinity 字段完成 Deployment、StatefulSet 等资源的创建与更新。