后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载本篇文章聚焦 Kubernetes 官方 Python 客户端kubernetes-python-client中kubernetes.aio.client.models.discovery_v1_endpoint_port模块所定义的DiscoveryV1EndpointPort模型。该模型是 EndpointSlice 中描述单个网络端口的核心数据结构读者将掌握其四个字段的完整语义与校验规则、pydantic 底层序列化机制以及如何在同步与异步客户端中通过V1EndpointSlice与DiscoveryV1Api完成端口的创建、读取与转换。一、模型定位EndpointSlice 的端口描述单元DiscoveryV1EndpointPort的官方定义是 EndpointPort represents a Port used by an EndpointSlice即它在 Kubernetes 的 discovery API 体系中承担单个端点Pod/IP上暴露的一个网络端口的建模职责。在 Kubernetes 中EndpointSlicediscovery.k8s.io/v1是对传统 Endpoints 对象的一种可扩展分片替代方案。一个 EndpointSlice 由addressType、endpoints端点列表和ports端口列表三部分组成其中ports列表的每个元素正是DiscoveryV1EndpointPort。从本仓库源码 v1_endpoint_slice.py 可以看到ports: Optional[List[DiscoveryV1EndpointPort]] Field( defaultNone, descriptionports specifies the list of network ports exposed by each endpoint in this slice. ... )同时该字段还有明确的规模约束每个 slice 最多包含 100 个端口由于 Service 至少有一个端口由 EndpointSlice controller 生成的 slice 也至少包含一个端口用于其他目的的自定义 EndpointSlice 则允许ports为空列表。这正解释了为什么本文的主角是一个小而关键的模型——它直接决定了 EndpointSlice 能被 kube-proxy 等组件正确消费。二、模块文档的组织方式doc/source/kubernetes.aio.client.models.discovery_v1_endpoint_port.rst是 Sphinx 文档中的 automodule 占位页kubernetes.aio.client.models.discovery_v1_endpoint_port module .. automodule:: kubernetes.aio.client.models.discovery_v1_endpoint_port :members: :show-inheritance: :undoc-members:也就是说该 RST 页面本身并不直接书写文档正文而是通过automodule指令在构建时从 Python 模块源码中提取 docstring 自动生成 API 文档。因此文档的真实技术内容全部沉淀在模型源码 kubernetes/aio/client/models/discovery_v1_endpoint_port.py 中其类定义位于 L96-L247。文章后续的所有字段语义与行为说明均以这份源码及其生成的文档为准。三、字段完整解析核心内容DiscoveryV1EndpointPort基于 pydantic 的BaseModel定义共包含四个可选字段。其openapi_types与attribute_map见 源码 L110-L122声明了 Python 属性名与 JSON 线上的序列化名称camelCase之间的映射关系Python 属性JSON 字段类型是否必填说明摘要app_protocolappProtocolstr可选应用层协议提示遵循 Kubernetes 标签语法namenamestr可选端口名称需通过 DNS_LABEL 校验默认空字符串portportint可选端口号Service 派生 slice 时等于 targetPortprotocolprotocolstr可选IP 协议取值 UDP/TCP/SCTP默认 TCP3.1 appProtocol应用层协议提示app_protocol用于向实现方提示该端口的应用层协议帮助提供更丰富的协议感知行为例如协议检测、流量特征识别。该字段遵循标准 Kubernetes 标签label语法合法取值分为三类无前缀协议名保留给 IANA 标准服务名使用依据 RFC-6335 及 IANA service names 注册表例如http、https这类通用名称Kubernetes 定义的前缀名称kubernetes.io/h2c—— 明文 HTTP/2 直连prior knowledge对应 RFC 9113 中关于 HTTP/2 直连启动的描述kubernetes.io/ws—— 明文 WebSocket对应 RFC 6455kubernetes.io/wss—— 基于 TLS 的 WebSocket对应 RFC 6455其他协议应使用实现方自定义的前缀名称例如mycompany.com/my-custom-protocol。从 字段定义源码 L106 可见该字段使用AliasChoices(appProtocol, app_protocol)同时接受 camelCase 与 snake_case 两种输入写法序列化时固定输出为appProtocol。3.2 name端口唯一名称name表示端口名称其约束是 EndpointSlice 语义层面的核心规则一个 EndpointSlice 内所有端口的名称必须唯一。如果该 EndpointSlice 由 Kubernetes Service 派生而来则此名称对应该 Service 中ports[].name。名称取值要么是空字符串要么必须通过 DNS_LABEL 校验具体规则见 源码 L107长度不超过 63 个字符只能由小写字母、数字和连字符-组成必须以字母或数字开头和结尾。默认值为空字符串。3.3 port端点端口号port表示端点实际监听/暴露的端口号。关键的语义约定是如果 EndpointSlice 由 Kubernetes Service 派生则该值必须设置为该 Service 的 targetPort即转发到 Pod 的目标端口而非 Service 对外暴露的port。用于其他目的的自定义 EndpointSlice 允许port为None即文档所述 may have a nil port。类型上它是Optional[StrictInt]pydantic 的StrictInt会拒绝非 int 类型的隐式转换。3.4 protocolIP 层协议protocol表示该端口的 IP 层协议取值必须是UDP、TCP或SCTP三者之一默认值为TCP。结合appProtocol的使用场景可以理解protocol回答传输层用什么协议而appProtocol回答应用层是什么协议二者互补共同描述一个端口的完整协议栈。四、模型底层机制pydantic 校验与序列化作为 OpenAPI Generator 基于 Kubernetes OpenAPI 规范source 注释标注版本为release-1.37见 源码 L8自动生成的模型DiscoveryV1EndpointPort的底层行为由model_config统一控制源码 L139-L145model_config ConfigDict( validate_by_nameTrue, validate_by_aliasTrue, validate_assignmentTrue, extraforbid, protected_namespaces(), )validate_by_nameTrue与validate_by_aliasTrue既可按属性名snake_case也可按别名camelCase进行输入校验配合字段上的AliasChoices实现写app_protocol或appProtocol都能正确赋值validate_assignmentTrue实例创建之后直接给属性赋值也会触发类型校验extraforbid拒绝未知字段避免把拼写错误的字段静默带入请求体protected_namespaces()允许使用model_*之类前缀的属性名而不触发 pydantic 保留命名空间警告。在序列化层面模型提供了一组完整的方法to_dict(serializeFalse)返回 Python 字典。默认使用 public 名称snake_case如app_protocol当serializeTrue时切换为 wire 名称camelCase如appProtocol见 源码 L183-L190to_json()返回 JSON 字符串表示使用别名camelCase输出from_json(json_str)从 JSON 字符串解析出模型实例内部经由from_dictfrom_dict(obj)从字典构造实例。其内部会先调用__preprocess_input_names源码 L125-L137将 snake_case 的app_protocol归一化为appProtocol后再进行 pydantic 校验to_str()/__repr__返回便于调试打印的格式化字符串。五、实战在同步与异步客户端中使用该模型仓库中kubernetes/client同步与kubernetes/aio/client异步两个包各有一份完全同构的模型文件同步版kubernetes/client/models/discovery_v1_endpoint_port.py异步版kubernetes/aio/client/models/discovery_v1_endpoint_port.py两份实现除导入路径外逻辑一致均已在各自的models/__init__.py中导出可直接from kubernetes.aio.client.models import DiscoveryV1EndpointPort导入。5.1 基础构造与序列化以官方文档示例为基础见 kubernetes/aio/docs/DiscoveryV1EndpointPort.md模型的基本用法如下from kubernetes.aio.client.models.discovery_v1_endpoint_port import DiscoveryV1EndpointPort # 直接按字段构造 port DiscoveryV1EndpointPort( app_protocolkubernetes.io/h2c, namehttp, port8080, protocolTCP, ) # 从 JSON 字符串创建实例 port_from_json DiscoveryV1EndpointPort.from_json( {appProtocol: kubernetes.io/h2c, name: http, port: 8080, protocol: TCP} ) # 转回字典默认 snake_case与 JSONcamelCase port_dict port.to_dict() print(port.to_json()) # {appProtocol: kubernetes.io/h2c, ...} # 字典 - 模型 - 字典 的往返转换 port_from_dict DiscoveryV1EndpointPort.from_dict(port_dict)注意由于配置了extraforbid若传入{appProtocols: ...}这类拼写错误的键会直接触发校验错误这有助于在请求发出前就暴露问题。5.2 组合进 V1EndpointSlice 并调用 DiscoveryV1Api实际业务中DiscoveryV1EndpointPort极少单独使用更多是作为V1EndpointSlice.ports的元素参与 CRUD。下面给出一个异步客户端中构建并创建带端口列表的 EndpointSlice的完整流程示意import asyncio from kubernetes import config from kubernetes.aio.client import ApiClient, Configuration from kubernetes.aio.client.api import DiscoveryV1Api from kubernetes.aio.client.models import ( V1EndpointSlice, V1EndpointSliceSpec, V1Endpoint, DiscoveryV1EndpointPort, V1ObjectMeta, ) async def create_slice_with_ports(): await config.load_kube_config() # 加载 ~/.kube/config client ApiClient(Configuration()) api DiscoveryV1Api(client) ports [ DiscoveryV1EndpointPort(namehttp, port8080, protocolTCP, app_protocolkubernetes.io/h2c), DiscoveryV1EndpointPort(namemetrics, port9090, protocolTCP), ] endpoint_slice V1EndpointSlice( api_versiondiscovery.k8s.io/v1, kindEndpointSlice, metadataV1ObjectMeta(namemy-slice, namespacedefault, labels{kubernetes.io/service-name: my-service}), address_typeIPv4, endpoints[V1Endpoint(addresses[10.0.0.1])], portsports, ) created await api.create_namespaced_endpoint_slice( namespacedefault, bodyendpoint_slice ) print(created) await client.close() asyncio.run(create_slice_with_ports())从 discovery_v1_api.py 的源码结构可以看到DiscoveryV1Api为 EndpointSlice 提供了完整的异步方法族create_namespaced_endpoint_slice、read_namespaced_endpoint_slice、list_namespaced_endpoint_slice、list_endpoint_slice_for_all_namespaces、patch_namespaced_endpoint_slice、replace_namespaced_endpoint_slice、delete_namespaced_endpoint_slice每个方法还伴随_with_http_info返回(ApiResponse, status, headers)元组与_without_preload_content流式/原始响应两个变体便于按需选择调用形态。值得留意的是请求发送时V1EndpointSlice.to_dict()会逐项调用其内部DiscoveryV1EndpointPort.to_dict()见 v1_endpoint_slice.py 的 to_dict 实现 L233-L238从而确保嵌套的端口对象被正确展开为 camelCase 的 JSON 字段后写入请求体。六、版本与使用前提该模型由 OpenAPI Generator 自动生成对应 Kubernetes OpenAPI 文档版本release-1.37当前仓库源码标注适用于discovery.k8s.io/v1API 组同步版本kubernetes.client.models.discovery_v1_endpoint_port适用于常规线程阻塞式调用异步版本kubernetes.aio.client.models.discovery_v1_endpoint_port基于asyncio需配合await与异步ApiClient使用本模块是文档RST 自动生成的 API 页与源码一一对应的典型样例读者若需查看字段的完整英文原始描述可直接查阅 DiscoveryV1EndpointPort.md 或同步版文档 kubernetes/docs/DiscoveryV1EndpointPort.md。综上DiscoveryV1EndpointPort虽然只有四个字段却是连接 Service 端口语义与 EndpointSlice 网络拓扑的关键桥梁。理解其字段约束唯一名称、DNS_LABEL、targetPort 对应关系、协议取值与 pydantic 序列化行为camelCase 别名、严格校验、嵌套展开即可在基于 Kubernetes Python 客户端的服务发现、流量转发与自定义 EndpointSlice 场景中准确无误地读写端口信息。赞分享后端云原生容器编排【免费下载链接】pythonOfficial Python client library for kubernetes项目地址https://gitcode.com/gh_mirrors/python1/python点击查看免费下载相关推荐PC-Agent 实战指南基于分层多智能体协作框架的 PC 复杂任务自动化PC Agent 实战指南基于分层多智能体协作框架的 PC 复杂任务自动化 导读 PC Agent 是 MobileAgent 系列中面向 PC 生产力场景后端云原生容器编排Lemur社区与生态如何参与开源项目贡献和获取技术支持Lemur社区与生态如何参与开源项目贡献和获取技术支持 Lemur作为一款开源证书管理工具拥有活跃的社区生态系统为开发者和用户提供了丰富的参与途径和技术支后端云原生容器编排Kubernetes Python 客户端异步 API 实战CoordinationV1beta1Api 与 LeaseCandidate 资源全解析Kubernetes Python 客户端异步 API 实战CoordinationV1beta1Api 与 LeaseCandidate 资源全解析 本文基后端云原生容器编排上一篇5步掌握AI变声神器RVC从零到精通的完整实战指南下一篇并行区块引擎重新定义游戏世界加载性能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考