服务

Service 是软件服务（例如 mysql）的命名抽象，它由代理侦听的本地端口（例如 3306）以及确定哪些 Pod 将响应通过代理发送的请求的选择器组成。

apiVersion: v1

import "k8s.io/api/core/v1"

服务

Service 是软件服务（例如 mysql）的命名抽象，它由代理侦听的本地端口（例如 3306）以及确定哪些 Pod 将响应通过代理发送的请求的选择器组成。

ServiceSpec

ServiceSpec 描述了用户在服务上创建的属性。

  • selector (map[string]string)

    将服务流量路由到标签键和值与此选择器匹配的 Pod。如果为空或不存在，则假定服务有一个管理其端点的外部进程，Kubernetes 不会修改。仅适用于 ClusterIP、NodePort 和 LoadBalancer 类型。如果类型为 ExternalName 则忽略。更多信息：https://kubernetes.ac.cn/docs/concepts/services-networking/service/

  • ports ([]ServicePort)

    补丁策略：在键 port 上合并

    映射：合并时将保留键 port, protocol 上的唯一值

    此服务公开的端口列表。更多信息：https://kubernetes.ac.cn/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

    ServicePort 包含有关服务端口的信息。

    • ports.port (int32)，必需

      此服务将公开的端口。

    • ports.targetPort (IntOrString)

      服务目标 Pod 上要访问的端口号或端口名称。端口号必须在 1 到 65535 之间。端口名称必须是 IANA_SVC_NAME。如果这是一个字符串，它将作为目标 Pod 容器端口中的命名端口进行查找。如果未指定，则使用“port”字段的值（一个身份映射）。对于 clusterIP=None 的服务，此字段将被忽略，应省略或设置为等于“port”字段。更多信息：https://kubernetes.ac.cn/docs/concepts/services-networking/service/#defining-a-service

      IntOrString 是一个可以容纳 int32 或字符串的类型。当在 JSON 或 YAML 编组和解组中使用时，它会生成或消费内部类型。这允许你有一个 JSON 字段，例如，可以接受名称或数字。

    • ports.protocol (string)

      此端口的 IP 协议。支持“TCP”、“UDP”和“SCTP”。默认为 TCP。

    • ports.name (string)

      此端口在服务中的名称。这必须是 DNS_LABEL。ServiceSpec 中的所有端口都必须具有唯一的名称。在考虑服务的端点时，这必须与 EndpointPort 中的“name”字段匹配。如果此服务上只定义了一个 ServicePort，则此字段可选。

    • ports.nodePort (int32)

      当类型为 NodePort 或 LoadBalancer 时，此服务在每个节点上公开的端口。通常由系统分配。如果指定的值在范围内且未被使用，则将使用该值，否则操作将失败。如果未指定，如果此服务需要端口，则将分配一个端口。如果创建不需要此字段的服务时指定此字段，则创建将失败。当更新服务使其不再需要此字段时（例如，将类型从 NodePort 更改为 ClusterIP），此字段将被清除。更多信息：https://kubernetes.ac.cn/docs/concepts/services-networking/service/#type-nodeport

    • ports.appProtocol (string)

      此端口的应用协议。这用作实现的提示，以便为它们理解的协议提供更丰富的行为。此字段遵循标准 Kubernetes 标签语法。有效值可以是

  • type (string)

    type 决定了服务如何公开。默认为 ClusterIP。有效选项为 ExternalName、ClusterIP、NodePort 和 LoadBalancer。“ClusterIP”为负载均衡到端点分配集群内部 IP 地址。端点由选择器决定，如果未指定选择器，则通过手动构建 Endpoints 对象或 EndpointSlice 对象决定。如果 clusterIP 为“None”，则不分配虚拟 IP，并且端点作为一组端点而不是虚拟 IP 发布。“NodePort”建立在 ClusterIP 之上，并在每个节点上分配一个端口，该端口路由到与 clusterIP 相同的端点。“LoadBalancer”建立在 NodePort 之上，并创建一个外部负载均衡器（如果当前云支持），该负载均衡器路由到与 clusterIP 相同的端点。“ExternalName”将此服务别名为指定的 externalName。其他几个字段不适用于 ExternalName 服务。更多信息：https://kubernetes.ac.cn/docs/concepts/services-networking/service/#publishing-services-service-types

  • ipFamilies ([]string)

    原子性：在合并期间将被替换

    IPFamilies 是分配给此服务的 IP 系列（例如 IPv4、IPv6）列表。此字段通常根据集群配置和 ipFamilyPolicy 字段自动分配。如果手动指定此字段，并且请求的系列在集群中可用，并且 ipFamilyPolicy 允许，则将使用该字段；否则服务创建将失败。此字段是条件可变的：它允许添加或删除辅助 IP 系列，但不允许更改服务的主要 IP 系列。有效值为“IPv4”和“IPv6”。此字段仅适用于 ClusterIP、NodePort 和 LoadBalancer 类型的服务，并且适用于“无头”服务。当将服务更新为 ExternalName 类型时，此字段将被清除。

    此字段最多可以包含两个条目（双栈系列，顺序任意）。如果指定了 clusterIPs 字段，这些系列必须与 clusterIPs 字段的值对应。clusterIPs 和 ipFamilies 都受 ipFamilyPolicy 字段的控制。

  • ipFamilyPolicy (string)

    IPFamilyPolicy 表示此服务请求或需要的双栈特性。如果未提供值，则此字段将设置为 SingleStack。服务可以是“SingleStack”（单个 IP 系列）、“PreferDualStack”（在双栈配置集群上使用两个 IP 系列或在单栈集群上使用单个 IP 系列）或“RequireDualStack”（在双栈配置集群上使用两个 IP 系列，否则失败）。ipFamilies 和 clusterIPs 字段取决于此字段的值。当将服务更新为 ExternalName 类型时，此字段将被清除。

  • clusterIP (string)

    clusterIP 是服务的 IP 地址，通常是随机分配的。如果手动指定地址，该地址在范围内（根据系统配置），并且未被使用，则会将其分配给服务；否则服务创建将失败。此字段不能通过更新更改，除非类型字段也正在更改为 ExternalName（这需要此字段为空白）或类型字段正在从 ExternalName 更改（在这种情况下，此字段可以可选地指定，如上所述）。有效值为“None”、空字符串（“”）或有效的 IP 地址。将其设置为“None”将创建“无头服务”（没有虚拟 IP），当首选直接端点连接且不需要代理时，这很有用。仅适用于 ClusterIP、NodePort 和 LoadBalancer 类型。如果创建 ExternalName 类型的服务时指定此字段，创建将失败。当将服务更新为 ExternalName 类型时，此字段将被清除。更多信息：https://kubernetes.ac.cn/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

  • clusterIPs ([]string)

    原子性：在合并期间将被替换

    ClusterIPs 是分配给此服务的 IP 地址列表，通常是随机分配的。如果手动指定地址，该地址在范围内（根据系统配置），并且未被使用，则会将其分配给服务；否则服务创建将失败。此字段不能通过更新更改，除非类型字段也正在更改为 ExternalName（这需要此字段为空）或类型字段正在从 ExternalName 更改（在这种情况下，此字段可以可选地指定，如上所述）。有效值为“None”、空字符串（“”）或有效的 IP 地址。将其设置为“None”将创建“无头服务”（没有虚拟 IP），当首选直接端点连接且不需要代理时，这很有用。仅适用于 ClusterIP、NodePort 和 LoadBalancer 类型。如果创建 ExternalName 类型的服务时指定此字段，创建将失败。当将服务更新为 ExternalName 类型时，此字段将被清除。如果未指定此字段，它将从 clusterIP 字段初始化。如果指定此字段，客户端必须确保 clusterIPs[0] 和 clusterIP 具有相同的值。

    此字段最多可以包含两个条目（双栈 IP，顺序任意）。这些 IP 必须与 ipFamilies 字段的值对应。clusterIPs 和 ipFamilies 都受 ipFamilyPolicy 字段的控制。更多信息：https://kubernetes.ac.cn/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

  • externalIPs ([]string)

    原子性：在合并期间将被替换

    externalIPs 是 IP 地址列表，集群中的节点也将接受此服务的流量。这些 IP 不由 Kubernetes 管理。用户负责确保流量通过此 IP 到达节点。一个常见的例子是不属于 Kubernetes 系统的外部负载均衡器。

  • sessionAffinity (string)

    支持“ClientIP”和“None”。用于维护会话亲和性。启用基于客户端 IP 的会话亲和性。必须是 ClientIP 或 None。默认为 None。更多信息：https://kubernetes.ac.cn/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

  • loadBalancerIP (string)

    仅适用于服务类型：LoadBalancer。此功能取决于底层云提供商是否支持在创建负载均衡器时指定 loadBalancerIP。如果云提供商不支持此功能，此字段将被忽略。已弃用：此字段定义不明确，其含义因实现而异。使用它不可移植，并且可能不支持双栈。建议用户在可用时使用特定于实现的注解。

  • loadBalancerSourceRanges ([]string)

    原子性：在合并期间将被替换

    如果指定且平台支持，这将限制通过云提供商负载均衡器的流量，流量将仅限于指定的客户端 IP。如果云提供商不支持此功能，此字段将被忽略。”更多信息：https://kubernetes.ac.cn/docs/tasks/access-application-cluster/create-external-load-balancer/

  • loadBalancerClass (string)

    loadBalancerClass 是此服务所属的负载均衡器实现的类。如果指定，此字段的值必须是标签样式标识符，带有可选前缀，例如“internal-vip”或“example.com/internal-vip”。未加前缀的名称保留给最终用户。此字段只能在服务类型为“LoadBalancer”时设置。如果未设置，则使用默认负载均衡器实现，目前这通常通过云提供商集成完成，但应适用于任何默认实现。如果设置，则假定负载均衡器实现正在监视具有匹配类的服务。任何默认负载均衡器实现（例如云提供商）都应忽略设置此字段的服务。此字段只能在创建或将服务更新为“LoadBalancer”类型时设置。一旦设置，就不能更改。当服务更新为非“LoadBalancer”类型时，此字段将被清除。

  • externalName (string)

    externalName 是发现机制将作为此服务的别名返回的外部引用（例如 DNS CNAME 记录）。不涉及代理。必须是小写的 RFC-1123 主机名（https://tools.ietf.org/html/rfc1123），并且要求 type 为“ExternalName”。

  • externalTrafficPolicy (string)

    externalTrafficPolicy 描述了节点如何分配它们在服务的“面向外部”地址（NodePorts、ExternalIPs 和 LoadBalancer IPs）上接收到的服务流量。如果设置为“Local”，代理将以一种方式配置服务，假定外部负载均衡器将负责在节点之间平衡服务流量，因此每个节点将仅将流量传输到服务的节点本地端点，而无需伪装客户端源 IP。（错误地发送到没有端点的节点的流量将被丢弃。）默认值“Cluster”使用路由到所有端点的标准行为（可能受拓扑和其他功能修改）。请注意，从集群内部发送到外部 IP 或 LoadBalancer IP 的流量将始终获得“Cluster”语义，但从集群内部发送到 NodePort 的客户端在选择节点时可能需要考虑流量策略。

  • internalTrafficPolicy (string)

    InternalTrafficPolicy 描述了节点如何分配它们在 ClusterIP 上接收到的服务流量。如果设置为“Local”，代理将假定 Pod 仅希望与 Pod 所在节点上的服务端点通信，如果没有本地端点则丢弃流量。默认值“Cluster”使用路由到所有端点的标准行为（可能受拓扑和其他功能修改）。

  • healthCheckNodePort (int32)

    healthCheckNodePort 指定了服务的健康检查节点端口。这仅适用于类型设置为 LoadBalancer 且 externalTrafficPolicy 设置为 Local 的情况。如果指定的值在范围内且未被使用，则将使用该值。如果未指定，则将自动分配一个值。外部系统（例如负载均衡器）可以使用此端口来确定给定节点是否包含此服务的端点。如果创建不需要此字段的服务时指定此字段，则创建将失败。当更新服务使其不再需要此字段时（例如，更改类型），此字段将被清除。此字段一旦设置，就不能更新。

  • publishNotReadyAddresses (boolean)

    publishNotReadyAddresses 表示任何处理此服务端点的代理都应忽略任何就绪/未就绪的指示。设置此字段的主要用例是 StatefulSet 的无头服务为其 Pod 传播 SRV DNS 记录，以进行对等发现。生成 Endpoints 和 EndpointSlice 资源的 Kubernetes 控制器将其解释为所有端点都被视为“就绪”，即使 Pod 本身尚未就绪。仅通过 Endpoints 或 EndpointSlice 资源使用 Kubernetes 生成的端点的代理可以安全地假定此行为。

  • sessionAffinityConfig (SessionAffinityConfig)

    sessionAffinityConfig 包含会话亲和性的配置。

    SessionAffinityConfig 表示会话亲和性的配置。

    • sessionAffinityConfig.clientIP (ClientIPConfig)

      clientIP 包含基于客户端 IP 的会话亲和性配置。

      ClientIPConfig 表示基于客户端 IP 的会话亲和性配置。

      • sessionAffinityConfig.clientIP.timeoutSeconds (int32)

        timeoutSeconds 指定 ClientIP 类型会话粘滞时间（秒）。如果 ServiceAffinity == “ClientIP”，则值必须 >0 且 <=86400（1 天）。默认值为 10800（3 小时）。

  • allocateLoadBalancerNodePorts (boolean)

    allocateLoadBalancerNodePorts 定义了是否为类型为 LoadBalancer 的服务自动分配 NodePort。默认为“true”。如果集群负载均衡器不依赖 NodePort，则可以将其设置为“false”。如果调用者请求特定的 NodePort（通过指定值），这些请求将得到尊重，无论此字段如何。此字段只能为类型为 LoadBalancer 的服务设置，如果类型更改为任何其他类型，则将被清除。

  • trafficDistribution (string)

    TrafficDistribution 提供了一种表达如何将流量分配到服务端点的偏好方式。实现可以将此字段作为提示，但不需要保证严格遵守。如果未设置此字段，则实现将应用其默认路由策略。如果设置为“PreferClose”，则实现应优先考虑同一区域中的端点。

ServiceStatus

ServiceStatus 表示服务的当前状态。

  • conditions ([]Condition)

    补丁策略：按键 type 合并

    映射：合并时将保留键类型上的唯一值

    当前服务状态

    Condition 包含此 API 资源当前状态的一个方面的详细信息。

    • conditions.lastTransitionTime (Time)，必需

      lastTransitionTime 是条件上次从一种状态转换到另一种状态的时间。这应该是底层条件发生变化的时间。如果不知道，则使用 API 字段发生变化的时间是可接受的。

      Time 是 time.Time 的一个包装器，支持正确地编组到 YAML 和 JSON。提供了 time 包提供的许多工厂方法的包装器。

    • conditions.message (string)，必需

      message 是一个人类可读的消息，指示有关转换的详细信息。这可能是一个空字符串。

    • conditions.reason (string)，必需

      reason 包含一个程序化标识符，指示条件上次转换的原因。特定条件类型的生产者可以定义此字段的预期值和含义，以及这些值是否被视为有保证的 API。该值应为 CamelCase 字符串。此字段不能为空。

    • conditions.status (string)，必需

      条件状态，True、False、Unknown 之一。

    • conditions.type (string)，必需

      条件类型，CamelCase 或 foo.example.com/CamelCase。

    • conditions.observedGeneration (int64)

      observedGeneration 表示条件所基于的 .metadata.generation。例如，如果 .metadata.generation 当前为 12，但 .status.conditions[x].observedGeneration 为 9，则条件与实例的当前状态相比已过时。

  • loadBalancer (LoadBalancerStatus)

    loadBalancer 包含负载均衡器的当前状态，如果存在的话。

    LoadBalancerStatus 表示负载均衡器的状态。

    • loadBalancer.ingress ([]LoadBalancerIngress)

      原子性：在合并期间将被替换

      Ingress 是一个列表，包含负载均衡器的入口点。预期发送到服务的流量应发送到这些入口点。

      LoadBalancerIngress 表示负载均衡器入口点的状态：预期发送到服务的流量应发送到入口点。

      • loadBalancer.ingress.hostname (string)

        Hostname 用于基于 DNS 的负载均衡器入口点（通常是 AWS 负载均衡器）

      • loadBalancer.ingress.ip (string)

        IP 用于基于 IP 的负载均衡器入口点（通常是 GCE 或 OpenStack 负载均衡器）

      • loadBalancer.ingress.ipMode (string)

        IPMode 指定负载均衡器 IP 的行为方式，并且只能在指定 ip 字段时指定。将其设置为“VIP”表示流量被传输到节点，目标设置为负载均衡器的 IP 和端口。将其设置为“Proxy”表示流量被传输到节点或 Pod，目标设置为节点的 IP 和节点端口或 Pod 的 IP 和端口。服务实现可以使用此信息来调整流量路由。

      • loadBalancer.ingress.ports ([]PortStatus)

        原子性：在合并期间将被替换

        Ports 是服务端口记录的列表。如果使用，服务中定义的每个端口都应该有一个条目。

        PortStatus 表示服务端口的错误情况

        • loadBalancer.ingress.ports.port (int32)，必需

          Port 是此处记录状态的服务端口的端口号。

        • loadBalancer.ingress.ports.protocol (string)，必需

          Protocol 是此处记录状态的服务端口的协议。支持的值为：“TCP”、“UDP”、“SCTP”

        • loadBalancer.ingress.ports.error (string)

          Error 用于记录服务端口的问题。错误格式应符合以下规则：- 内置错误值应在此文件中指定，并且应使用 CamelCase 名称。

          • 云提供商特定的错误值必须具有符合 foo.example.com/CamelCase 格式的名称。

ServiceList

ServiceList 包含服务列表。

操作

get 读取指定的 Service

HTTP 请求

GET /api/v1/namespaces/{namespace}/services/{name}

参数

  • name (在路径中): string，必填

    Service 的名称

  • namespace (在路径中): string，必填

    命名空间

  • pretty (在查询中): string

    pretty

响应

200 (Service): OK

401: 未授权

get 读取指定 Service 的状态

HTTP 请求

GET /api/v1/namespaces/{namespace}/services/{name}/status

参数

  • name (在路径中): string，必填

    Service 的名称

  • namespace (在路径中): string，必填

    命名空间

  • pretty (在查询中): string

    pretty

响应

200 (Service): OK

401: 未授权

list 列出或监视 Service 类型的对象

HTTP 请求

GET /api/v1/namespaces/{namespace}/services

参数

响应

200 (ServiceList): OK

401: 未授权

list 列出或监视 Service 类型的对象

HTTP 请求

GET /api/v1/services

参数

响应

200 (ServiceList): OK

401: 未授权

create 创建一个 Service

HTTP 请求

POST /api/v1/namespaces/{namespace}/services

参数

响应

200 (Service): OK

201 (Service): 已创建

202 (Service): 已接受

401: 未授权

update 替换指定的 Service

HTTP 请求

PUT /api/v1/namespaces/{namespace}/services/{name}

参数

  • name (在路径中): string，必填

    Service 的名称

  • namespace (在路径中): string，必填

    命名空间

  • body: Service，必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • pretty (在查询中): string

    pretty

响应

200 (Service): OK

201 (Service): 已创建

401: 未授权

update 替换指定的 Service 状态

HTTP 请求

PUT /api/v1/namespaces/{namespace}/services/{name}/status

参数

  • name (在路径中): string，必填

    Service 的名称

  • namespace (在路径中): string，必填

    命名空间

  • body: Service，必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • pretty (在查询中): string

    pretty

响应

200 (Service): OK

201 (Service): 已创建

401: 未授权

patch 部分更新指定的 Service

HTTP 请求

PATCH /api/v1/namespaces/{namespace}/services/{name}

参数

  • name (在路径中): string，必填

    Service 的名称

  • namespace (在路径中): string，必填

    命名空间

  • body: Patch，必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • force (在查询中): boolean

    force

  • pretty (在查询中): string

    pretty

响应

200 (Service): OK

201 (Service): 已创建

401: 未授权

patch 部分更新指定的 Service 状态

HTTP 请求

PATCH /api/v1/namespaces/{namespace}/services/{name}/status

参数

  • name (在路径中): string，必填

    Service 的名称

  • namespace (在路径中): string，必填

    命名空间

  • body: Patch，必需

  • dryRun (在查询中): string

    dryRun

  • fieldManager (在查询中): string

    fieldManager

  • fieldValidation (在查询中): string

    fieldValidation

  • force (在查询中): boolean

    force

  • pretty (在查询中): string

    pretty

响应

200 (Service): OK

201 (Service): 已创建

401: 未授权

delete 删除一个 Service

HTTP 请求

DELETE /api/v1/namespaces/{namespace}/services/{name}

参数

响应

200 (Service): OK

202 (Service): 已接受

401: 未授权

deletecollection 删除 Service 集合

HTTP 请求

DELETE /api/v1/namespaces/{namespace}/services

参数

响应

200 (Status): OK

401: 未授权

本页面是自动生成的。

如果你打算报告此页面存在的问题，请在问题描述中提及此页面是自动生成的。修复可能需要在 Kubernetes 项目的其他地方进行。

最后修改时间：2025 年 4 月 24 日上午 9:14 PST：v1.33 的 Markdown API 参考 (b84ec30bbb)