Argo Workflows Java SDK 中 ServicePort 模型详解端口定义字段与 Kubernetes Service 语义【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows导读ServicePort是 Argo Workflows Java SDKsdks/java/client中描述 Kubernetes Service 端口信息的模型类对应于 Kubernetes 核心 API 的io.k8s.api.core.v1.ServicePort。在 Argo 生态中它主要用于承载事件源EventSource暴露的 Service 端口列表来自 Argo Events 的Service结构也是理解工作流控制器、事件服务如何声明与暴露端口的基础。读完本文你将掌握ServicePort全部 6 个字段的类型、含义、默认值与可选性约束并能在 Java SDK 中正确构造端口配置。一、模型定位从 Kubernetes 核心类型到 Argo Java SDKServicePort并非 Argo 自创的业务类型而是 Kubernetes 核心 APIcore/v1中ServiceSpec.ports列表元素的标准类型。在 Argo Workflows 仓库中该类型以io.k8s.api.core.v1.ServicePort的形式被引入 OpenAPI 规范并由此生成 Java SDK 客户端模型。在 Argo 生态内的实际使用场景中ServicePort出现在事件源EventSource的 Service 定义里。从 OpenAPI 规范 可以看到Argo Events 的Service结构体包含ports字段ports: { type: array, items: { $ref: #/definitions/io.k8s.api.core.v1.ServicePort } }也就是说一个事件源 Service 可以声明一个或多个ServicePort每个端口对应 Kubernetes Service 对外暴露的一个端口条目。对应到 Java SDKGithubComArgoprojArgoEventsPkgApisEventsV1alpha1Service 文档 中ports的类型即为ListServicePort。二、属性总览ServicePort共包含 6 个属性其中仅port为必填字段其余均可选。下表汇总了字段类型与说明名称类型说明可选性appProtocolString端口的应用层协议提示遵循 Kubernetes 标签语法[optional]nameStringService 内端口的名称须为 DNS_LABEL同一 ServiceSpec 内必须唯一[optional]nodePortIntegerService 类型为 NodePort 或 LoadBalancer 时每个节点上暴露的端口[optional]portInteger该 Service 对外暴露的端口必填protocolStringIP 层协议支持 TCP、UDP、SCTP默认 TCP[optional]targetPortString目标 Pod 上要访问的端口数字或名称[optional]从 OpenAPI 定义看唯一被标记进required列表的是port见 swagger.json这与 Kubernetes 官方校验一致一个端口条目至少要声明对外暴露的端口号。三、必填字段 portService 对外暴露的端口port是该模型唯一必填字段类型为Integer含义为 Thebegin▁of▁sentence## port that will be exposed by this service即 Service 对外暴露监听的端口号。它相当于 Kubernetes Service 规范中spec.ports[].port是 ClusterIP 上实际监听的端口。在 Argo 事件源场景下当事件源如 Webhook 类型的 HTTP 事件源需要对外提供访问入口时就必须在 Service 的ports列表中至少指定一个port否则该端口条目不成立。例如声明一个 12000 端口的服务Java 侧构造即需要setPort(12000)。四、targetPort从 Service 端口到 Pod 容器的映射targetPort类型为String在 Kubernetes 中实际为IntOrString即可同时承载数字或名称描述目标 Pod 上要访问的端口。OpenAPI 规范中给出了更完整的语义见 swagger.json数字形式取值范围 1 到 65535直接对应目标 Pod 的容器端口名称形式必须是IANA_SVC_NAME会被解析为目标 Pod 容器端口列表中对应的命名端口未指定时默认取port字段的值即 identity map端口映射到自身特殊场景对于clusterIPNone的 headless Service该字段会被忽略此时应省略或将值设为与port相等。由于 Java SDK 将其建模为String使用数字端口时需要以字符串形式传入例如setTargetPort(8080)或传入命名端口setTargetPort(http)。五、protocol 与 appProtocol两层协议声明protocol描述 IP 传输层协议支持TCP、UDP、SCTP三种取值默认是TCP。在 Argo 的多数事件源场景HTTP/Webhook中默认 TCP 即可满足需求。appProtocol则是应用层协议的提示hint遵循 Kubernetes 标签语法label syntax为实现了特定协议的组件提供更丰富的行为提示。其合法取值分三类完整描述见 swagger.json无前缀的协议名保留给 IANA 标准服务名依据 RFC-6335Kubernetes 定义的前缀名kubernetes.io/h2c—— 明文 HTTP/2prior knowledgekubernetes.io/ws—— 明文 WebSocketkubernetes.io/wss—— 基于 TLS 的 WebSocket实现自定义的前缀名如mycompany.com/my-custom-protocol。在实际的 Java SDK 使用中若事件源需要暴露 WebSocket 或 h2c 等服务可在appProtocol中声明相应取值帮助负载均衡器等组件识别协议。六、name 与 nodePort命名约束与节点端口nameService 内端口的名称必须是 DNS_LABEL即符合 DNS 标签规范小写字母、数字与-且以字母数字开头结尾。同一ServiceSpec内所有端口的name必须唯一当 Service 只定义了一个ServicePort时该字段可省略。需要特别注意的是Service 的 Endpoints 计算要求该字段与EndpointPort.name保持一致否则端口关联可能失效。nodePort仅当 Service 类型为NodePort或LoadBalancer时生效表示每个节点上暴露的端口。其行为规则见 swagger.json通常由系统自动分配若显式指定值必须在合法范围内且未被占用否则创建操作失败若未指定只要 Service 需要 nodePort 就会自动分配若为不需要 nodePort 的 Service如 ClusterIP 类型显式指定该字段创建会失败当 Service 从 NodePort 更新为 ClusterIP 时该字段会被清除。在 Argo 事件源场景中若希望事件源 Service 对外可通过节点端口访问例如NodePort或LoadBalancer类型即可设置该字段而默认的 ClusterIP 事件源 Service 则通常不设置。七、Java SDK 中的完整构造示例综合以上字段语义在 Argo Workflows Java SDK 中构造一个承载 WebSocket 服务的ServicePort实例如下import io.argoproj.events.models.eventsource.v1alpha1.ServicePort; // 以实际生成包名为准 ServicePort webSocketPort new ServicePort() .name(ws) .port(12000) .targetPort(12000) // String 形式承载 IntOrString .protocol(TCP) // 默认即 TCP可省略 .appProtocol(kubernetes.io/ws); // 声明 WebSocket over cleartext若再结合事件源 Service 的ports列表使用其类型为ListServicePort即可将端口定义挂载到事件源暴露的 Service 上使其真正可被集群内外访问。八、验证途径仓库中的真实引用OpenAPI 规范io.k8s.api.core.v1.ServicePort的完整定义位于 api/openapi-spec/swagger.json是 Java SDK 文档生成的权威来源Java SDK 文档本文件即 sdks/java/client/docs/ServicePort.md与GithubComArgoprojArgoEventsPkgApisEventsV1alpha1Service文档中ports: ListServicePort字段相互印证仓库测试与工具代码如 test/e2e/telemetry_stack_test.go中通过ServicePort相关常量TempoServicePort、PrometheusServicePort验证了 Argo 依赖服务端口的使用方式可作为理解该类型在端到端链路中作用的旁证。小结ServicePort是 Argo Java SDK 对 Kubernetes 标准 Service 端口模型的直接映射port是唯一必填字段targetPort承担 Service 端口到容器端口的映射支持数字与名称protocol/appProtocol分别约束传输层与应用层协议name与nodePort则负责命名唯一性和节点级暴露。掌握这 6 个字段的语义即可在事件源等场景中准确声明服务端口并避免诸如nodePort与 Service 类型不匹配、name违反 DNS_LABEL 等常见配置错误。【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考