后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载导读V2CrossVersionObjectReference是 Kubernetes Python 官方客户端同步版与 asyncio 版中用于跨 API 版本定位 Kubernetes 对象的核心模型在 HorizontalPodAutoscalerHPA自动伸缩控制器的scaleTargetRef与Object类型指标中扮演关键角色。本文以该模型的源码与 OpenAPI 定义为主体讲清它的字段语义、校验规则、序列化行为并给出基于 autoscaling/v2 的真实可运行的 HPA 配置与 asyncio 客户端实战方案。一、模型定位它解决什么问题在 Kubernetes 生态中许多资源需要在不绑定具体 API 版本的前提下引用另一个对象。例如 HPA 需要告诉控制器我要伸缩哪个 Deployment但 Deployment 的apiVersion可能随集群版本演进HPA 的Object类型指标需要描述我要观测哪个 Ingress 的每秒请求数同样不希望在配置里硬编码版本号。V2CrossVersionObjectReference正是这种跨版本对象引用的载体。官方文档对其定义一句话概括CrossVersionObjectReference contains enough information to let you identify the referred resource.即它提供足以唯一标识一个被引用资源的全部信息而无需关心该资源当前所处 API 组与版本。在 scripts/swagger.json 的 OpenAPI 定义中该模型被描述为v2.CrossVersionObjectReference属于autoscaling/v2指标组并在同步版 kubernetes/client/models/v2_cross_version_object_reference.py 与 asyncio 版 kubernetes/aio/client/models/v2_cross_version_object_reference.py 中各有一份等价实现两处源码除模块路径与导入前缀外完全一致。二、字段语义与类型定义2.1 三个字段的含义该模型只有三个字段全部为字符串类型字段OpenAPI 类型是否必填语义apiVersion属性名api_versionstr可选被引用对象的 API 版本例如apps/v1、autoscaling/v2kindstr必填被引用对象的资源种类例如Deployment、Ingressnamestr必填被引用对象的名称Kubernetes 命名规则如 DNS 子域名规范字段的权威语义来自模型源码中的Field描述见 v2_cross_version_object_reference.pyapi_versionapiVersion is the API version of the referentkindkind is the kind of the referent并链接到 Kubernetes 社区 API 约定文档中关于types-kinds的说明namename is the name of the referent链接到 Kubernetes 关于对象命名规范的官方文档。Swagger 定义scripts/swagger.json明确列出required: [kind, name]即kind与name必填apiVersion可选。这意味着即使不指定版本控制器也能通过kind name在集群内解析目标对象而显式给出apiVersion则能规避跨版本歧义尤其在集群中同时存在多个同名 API 组时。2.2 与 v1 版本模型的差异值得注意autoscaling/v1中同样存在V1CrossVersionObjectReference见 kubernetes/aio/client/models/v1_cross_version_object_reference.py其三个字段的名称、类型、别名与校验规则与 v2 版本完全一致。两者的区别体现在被组合进哪个上层模型autoscaling/v1的 HPA 只支持基于 CPU 的Resource指标引用对象仅作为伸缩目标autoscaling/v2引入Object/Pods/External/ContainerResource等多维指标体系V2CrossVersionObjectReference同时承担伸缩目标引用与指标观测对象引用双重职责。这一差异通过两个版本模型的组合关系清晰体现见下文第三节。三、模型在 autoscaling/v2 指标体系中的组合位置V2CrossVersionObjectReference被多个 v2 上层模型以嵌套形式引用这正是它在 HPA 中真正的用武之地。从源码可以确认三处引用3.1 伸缩目标V2HorizontalPodAutoscalerSpec.scaleTargetRef在 v2_horizontal_pod_autoscaler_spec.py 中scale_target_ref: V2CrossVersionObjectReference Field( validation_aliasAliasChoices(scaleTargetRef, scale_target_ref), serialization_aliasscaleTargetRef )scaleTargetRef是 HPA Spec 的必填字段声明该 HPA 控制哪个工作负载的副本数。from_dict中对应反序列化逻辑同文件第 271 行将其委托给V2CrossVersionObjectReference.from_dict()。3.2 指标观测对象V2ObjectMetricSource.describedObject在 v2_object_metric_source.py 中described_object: V2CrossVersionObjectReference Field( validation_aliasAliasChoices(describedObject, described_object), serialization_aliasdescribedObject )Object类型指标的语义是基于描述某个 Kubernetes 对象的指标来伸缩例如 Ingress 的每秒请求数hits-per-second。此时describedObject引用该 Ingress配合metric指标标识符与target目标值共同定义伸缩规则。3.3 状态回显V2ObjectMetricStatus.describedObject在 v2_object_metric_status.py 中describedObject以相同方式嵌套用于在 HPA 的status.metrics[]中回显当前生效的指标对象引用供运维侧核验。3.4 指标类型枚举V2MetricSpec.type字段见 v2_metric_spec.py规定类型只能是ContainerResource、External、Object、Pods、Resource五种之一其中只有Object分支会使用V2CrossVersionObjectReference定位具体的被观测对象。四、模型类的实现细节校验、别名与序列化4.1 基于 Pydantic 的严格校验模型继承pydantic.BaseModel并在model_configv2_cross_version_object_reference.py中启用了一套严格的校验策略model_config ConfigDict( validate_by_nameTrue, validate_by_aliasTrue, validate_assignmentTrue, extraforbid, protected_namespaces(), )逐项含义validate_by_name/validate_by_alias实例化时既接受 Python 风格下划线属性名api_version也接受 JSON 线缆风格驼峰别名apiVersionvalidate_assignment属性赋值时同样触发类型校验防止运行期写入非法值extraforbid拒绝任何未声明的额外字段传入未知键将直接抛错避免拼写错误被静默吞掉protected_namespaces()允许api_version这类以api_开头的属性名Pydantic 默认保护model_前缀命名空间此处显式放开。kind与name使用StrictStr类型意味着必须为真正的str实例传入整数等类型会被拒绝。4.2 字段别名的双向兼容api_version字段通过AliasChoices(apiVersion, api_version)声明双别名见 源码第 106 行__preprocess_input_names类方法第 122-134 行在from_dict入口处把api_version键规范化为apiVersion。这保证了从 API Server 返回的 JSON驼峰能直接解析用户手写 Python 字典时用下划线风格也不会出错。serialization_aliasapiVersion则确保输出时统一走线缆格式。4.3 序列化三件套to_dict / to_json / from_dict / from_json模型提供两组序列化 APIv2.to_dict() # 返回字段字典默认使用 public 名 api_version/kind/name v2.to_dict(serializeTrue) # 返回线缆格式字典apiVersion/kind/name v2.to_json() # 返回 JSON 字符串使用 alias即 apiVersion V2CrossVersionObjectReference.from_json(json_str) # 由 JSON 字符串构造实例 V2CrossVersionObjectReference.from_dict(obj) # 由字典构造实例其中to_dict()的实现源码第 180-186 行会显式遍历声明字段并递归调用嵌套模型from_dict()第 220-242 行先做输入名规范化再逐个字段调用model_validate。这与上游 OpenAPI Generator 的 python-legacy 模板行为保持一致源码注释中引用了对应模板实现。模型还实现了to_str()/__repr__()pprint 友好输出以及基于to_dict()相等性比较的__eq__/__ne__。五、实战用 V2CrossVersionObjectReference 构建并创建 HPA5.1 纯模型层的最小用法直接构造引用对象并完成 JSON 互转参照官方文档示例 V2CrossVersionObjectReference.md 并补全from kubernetes.aio.client.models.v2_cross_version_object_reference import ( V2CrossVersionObjectReference, ) ref V2CrossVersionObjectReference( api_versionapps/v1, kindDeployment, nameweb, ) # 输出线缆格式 JSON{apiVersion: apps/v1, kind: Deployment, name: web} print(ref.to_json()) # 字典转换往返验证 ref_dict ref.to_dict() ref_restored V2CrossVersionObjectReference.from_dict(ref_dict) assert ref ref_restored注意kind与name为必填缺一不可api_version可选。5.2 组装成完整的 HPA v2 对象将引用对象嵌入V2HorizontalPodAutoscalerSpec.scaleTargetRef再配合 Object 类型指标即可构造一个按 Ingress 每秒请求数伸缩的 HPAfrom kubernetes.aio.client.models.v2_cross_version_object_reference import ( V2CrossVersionObjectReference, ) from kubernetes.aio.client.models.v2_horizontal_pod_autoscaler import ( V2HorizontalPodAutoscaler, ) from kubernetes.aio.client.models.v2_horizontal_pod_autoscaler_spec import ( V2HorizontalPodAutoscalerSpec, ) from kubernetes.aio.client.models.v2_metric_spec import V2MetricSpec from kubernetes.aio.client.models.v2_object_metric_source import V2ObjectMetricSource from kubernetes.aio.client.models.v2_metric_identifier import V2MetricIdentifier from kubernetes.aio.client.models.v2_metric_target import V2MetricTarget hpa V2HorizontalPodAutoscaler( api_versionautoscaling/v2, kindHorizontalPodAutoscaler, metadata..., # 需 V2ObjectMeta可参照 V2HorizontalPodAutoscaler specV2HorizontalPodAutoscalerSpec( scale_target_refV2CrossVersionObjectReference( api_versionapps/v1, kindDeployment, nameweb, ), min_replicas1, max_replicas10, metrics[ V2MetricSpec( typeObject, objectV2ObjectMetricSource( described_objectV2CrossVersionObjectReference( api_versionnetworking.k8s.io/v1, kindIngress, nameweb-ingress, ), metricV2MetricIdentifier(namerequests-per-second), targetV2MetricTarget(typeValue, value100), ), ) ], ), )在上述结构中同一个模型类在两个位置出现语义不同scaleTargetRefHPA 控制伸缩的目标工作负载metrics[].object.describedObjectHPA 观察的指标来源对象。5.3 通过 autoscaling/v2 API 提交asyncio 版客户端提供与 API Serverautoscaling/v2对应的操作接口核心方法在 autoscaling_v2_api.py 中create_namespaced_horizontal_pod_autoscaler第 65 行起创建 HPA必填namespace与body: V2HorizontalPodAutoscalerread_namespaced_horizontal_pod_autoscaler第 3357 行起读取 HPApatch_namespaced_horizontal_pod_autoscaler第 2551 行起局部更新 HPA。创建调用示例注意 asyncio 客户端方法均为协程需awaitimport asyncio from kubernetes.aio import config as aio_config from kubernetes.aio.client.api.autoscaling_v2_api import AutoscalingV2Api async def create_hpa(): await aio_config.load_kube_config() async with AutoscalingV2Api() as api: created await api.create_namespaced_horizontal_pod_autoscaler( namespacedefault, bodyhpa, # 上一步构造的 V2HorizontalPodAutoscaler prettytrue, ) print(created.to_dict()) asyncio.run(create_hpa())接口还支持dry_run如All、field_manager、field_validationIgnore/Warn/Strict等参数可在提交前做服务端校验。同步版客户端kubernetes.client提供同名的非协程方法调用方式一致只需把await去掉。六、深层机制模型由 OpenAPI 规范生成勿手改从源码头部的生成注释v2_cross_version_object_reference.py可以确认整个kubernetes.aio.client包由 OpenAPI Generator 基于release-1.37版本的 Kubernetes OpenAPI 规范自动生成包版本为37.0.0snapshot见 kubernetes/aio/README.md。因此字段集合、必填规则、别名映射都以 scripts/swagger.json 为唯一事实来源升级 Kubernetes 版本后重新生成即可同步不建议手工修改生成代码若需自定义序列化行为应通过子类化或包装层实现同步版与 asyncio 版的模型定义保持一致业务逻辑代码可以平移复用仅import路径不同kubernetes.client.modelsvskubernetes.aio.client.models。七、小结V2CrossVersionObjectReference是一个小而关键的模型三个字段承载了 HPA 跨版本引用工作负载与指标对象的全部语义。掌握它的字段必填规则kindname必填、apiVersion可选、Pydantic 严格校验行为以及scaleTargetRef/describedObject两个嵌套场景就能准确构造、提交与回读 autoscaling/v2 HPA 对象。本文涉及的完整模型定义、组合关系与 API 方法均可在仓库中对应源码文件进一步查阅模型源码kubernetes/aio/client/models/v2_cross_version_object_reference.py官方模型文档kubernetes/aio/docs/V2CrossVersionObjectReference.mdOpenAPI 定义scripts/swagger.json组合场景v2_horizontal_pod_autoscaler_spec.py、v2_object_metric_source.py、v2_object_metric_status.py提交 APIautoscaling_v2_api.py赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐深入解析 Kubernetes Python 客户端中的 V1Node 模型Node 对象的异步建模与实战深入解析 Kubernetes Python 客户端中的 V1Node 模型Node 对象的异步建模与实战 本文以当前仓库GitHub 加速计划 / pyt后端云原生容器编排Kubernetes Python 客户端 V1ParentReference 模型详解父对象引用的定义、序列化与实战Kubernetes Python 客户端 V1ParentReference 模型详解父对象引用的定义、序列化与实战 导读 V1ParentReferenc后端云原生容器编排深入解析 Kubernetes Python 客户端 V1PersistentVolumeSpecPersistentVolume 规格模型与实战用法深入解析 Kubernetes Python 客户端 V1PersistentVolumeSpecPersistentVolume 规格模型与实战用法 V1P后端云原生容器编排创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考