Kubernetes Python 客户端模型详解:V1WeightedPodAffinityTerm 加权 Pod 亲和性调度

原创2026-10-11 11:33:551,621 阅读
文章标签:云原生容器编排集群管理后端

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. 权重范围务必在 1–100 之间:超出范围的数值虽可能通过 Python 层的 StrictInt 类型校验,但会被 API Server 拒绝,因为 OpenAPI 定义明确限定该范围;
  2. pod_affinity_term 不可省略:它是必填字段,且在 V1PodAffinityTerm 内部 topology_key 同样必填且不能为空字符串;
  3. 区分软硬规则:把加权条目放进 preferred_during_scheduling_ignored_during_execution 得到的是"偏好"语义;若需要硬性约束,应使用 V1PodAffinityTerm(不带权重)放入 required_during_scheduling_ignored_during_execution;
  4. 多条目打分:同一节点命中多条软性规则时权重累加(亲和)或累减(反亲和),因此设计多组加权规则时要注意各权重之间的相对大小关系,它们共同决定节点的最终优先级排序。

结合以上模型定义、OpenAPI 原始 schema 与调度语义,你可以在 Python 中精准构建 Kubernetes 的软性 Pod 亲和/反亲和配置,并通过 to_dict / to_json 无缝接入 V1PodSpec 的 affinity 字段完成 Deployment、StatefulSet 等资源的创建与更新。

登录后查看全文
python