Service

staging/src/k8s.io/api/core/v1/types.go

// 一个抽象的服务组，配合coredns做服务发现，提供负载均衡与VIP，当仅可在集群内通讯
type Service struct {
    // 公共基础结构
    metav1.TypeMeta `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`

    // 服务规范定义
    Spec ServiceSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`

    // 服务实际配置
    Status ServiceStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"`
}

// 用户声明期望的服务配置
type ServiceSpec struct {
    // 服务对外暴露的端口
    Ports []ServicePort `json:"ports,omitempty" patchStrategy:"merge" patchMergeKey:"port" protobuf:"bytes,1,rep,name=ports"`

    // 根据这里配置的标签来决定具体路由流量至后端POD
    // 如果类型是：ExternalName 则会被忽略，仅为：ClusterIP, NodePort, and LoadBalancer 类型有效；
    Selector map[string]string `json:"selector,omitempty" protobuf:"bytes,2,rep,name=selector"`

    // 一个虚拟IP地址，如果未手工配置则自动生成，手工配置必须未被使用且在有效范围内
    // 如果设置为 "None" 则不分配IP，也就是 "headless service"，一般配合有状态应用使用
    // 如果 type="ExternalName" 则不生效
    // 仅当 type 为 ClusterIP, NodePort, and LoadBalancer 生效
    ClusterIP string `json:"clusterIP,omitempty" protobuf:"bytes,3,opt,name=clusterIP"`

    // 功能同 ClusterIP，支持多个虚拟IP，如果同时配置了 ClusterIP，则必须与 ClusterIPs[0] 值相同
    ClusterIPs []string `json:"clusterIPs,omitempty" protobuf:"bytes,18,opt,name=clusterIPs"`

    // 默认类型为：ClusterIP，支持类型：ExternalName, ClusterIP, NodePort, and LoadBalancer
    Type ServiceType `json:"type,omitempty" protobuf:"bytes,4,opt,name=type,casttype=ServiceType"`

    // TODO; 具体实现待验证
    // 非K8S管理的外部IP，但用于接收这个服务的流量
    ExternalIPs []string `json:"externalIPs,omitempty" protobuf:"bytes,5,rep,name=externalIPs"`

    // 会话的亲和性，支持："ClientIP" and "None"，默认为 "None"
    SessionAffinity ServiceAffinity `json:"sessionAffinity,omitempty" protobuf:"bytes,7,opt,name=sessionAffinity,casttype=ServiceAffinity"`

    // 仅当服务类型为 "LoadBalancer" 生效，不支持双栈网络，依赖云服务提供商
    LoadBalancerIP string `json:"loadBalancerIP,omitempty" protobuf:"bytes,8,opt,name=loadBalancerIP"`

    // TODO; https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/
    LoadBalancerSourceRanges []string `json:"loadBalancerSourceRanges,omitempty" protobuf:"bytes,9,opt,name=loadBalancerSourceRanges"`

    // 设置为一个DNS地址，用于作为该服务的别名，同时 "type" 必须设置为 "ExternalName"
    ExternalName string `json:"externalName,omitempty" protobuf:"bytes,10,opt,name=externalName"`

    // 用于控制外部流量进入集群后如何路由到后端 Pod，影响 "NodePort" 或 "LoadBalancer" 类型服务
    // 如果设置为 "Local"，当该节点上没有匹配的 Pod，则流量不会被转发到集群中的其他节点，这样则会保留源客户端源 IP
    // 如果设置为 "Cluster"，将采用集群内部的负载均衡机制，无论外部流量来自哪个节点，都可被路由到对应 Pod
    ExternalTrafficPolicy ServiceExternalTrafficPolicyType `json:"externalTrafficPolicy,omitempty" protobuf:"bytes,11,opt,name=externalTrafficPolicy"`

    // 用于健康检测，仅当类型为 "LoadBalancer" 且 "externalTrafficPolicy=Local" 时有效；
    HealthCheckNodePort int32 `json:"healthCheckNodePort,omitempty" protobuf:"bytes,12,opt,name=healthCheckNodePort"`

    // TODO; 用途未知
    PublishNotReadyAddresses bool `json:"publishNotReadyAddresses,omitempty" protobuf:"varint,13,opt,name=publishNotReadyAddresses"`

    // 用于配置会话亲和性
    SessionAffinityConfig *SessionAffinityConfig `json:"sessionAffinityConfig,omitempty" protobuf:"bytes,14,opt,name=sessionAffinityConfig"`

    // 服务IP版本，可取：IPv4, IPv6，仅当类型为："ClusterIP"、"NodePort"、"LoadBalancer"
    IPFamilies []IPFamily `json:"ipFamilies,omitempty" protobuf:"bytes,19,opt,name=ipFamilies,casttype=IPFamily"`

    // 服务IP策略，是否支持双栈，可取值 "SingleStack"、"PreferDualStack"、"RequireDualStack"
    IPFamilyPolicy *IPFamilyPolicyType `json:"ipFamilyPolicy,omitempty" protobuf:"bytes,17,opt,name=ipFamilyPolicy,casttype=IPFamilyPolicyType"`

    // 当类型为 "LoadBalancer" 是否自动分配 "NodePorts" 端口，默认为 "true"
    AllocateLoadBalancerNodePorts *bool `json:"allocateLoadBalancerNodePorts,omitempty" protobuf:"bytes,20,opt,name=allocateLoadBalancerNodePorts"`

    // 当类型为 "LoadBalancer" 才有效
    LoadBalancerClass *string `json:"loadBalancerClass,omitempty" protobuf:"bytes,21,opt,name=loadBalancerClass"`

    // InternalTrafficPolicy specifies if the cluster internal traffic
    // should be routed to all endpoints or node-local endpoints only.
    // "Cluster" routes internal traffic to a Service to all endpoints.
    // "Local" routes traffic to node-local endpoints only, traffic is
    // dropped if no node-local endpoints are ready.
    // The default value is "Cluster".
    // +featureGate=ServiceInternalTrafficPolicy
    // +optional
    // 类似 externalTrafficPolicy 用于控制内部流量在集群内如何路由到后端 Pod
    InternalTrafficPolicy *ServiceInternalTrafficPolicyType `json:"internalTrafficPolicy,omitempty" protobuf:"bytes,22,opt,name=internalTrafficPolicy"`
}

type ServicePort struct {
    // 各服务名称必须是唯一的
    Name string `json:"name,omitempty" protobuf:"bytes,1,opt,name=name"`

    // 该端口协议，支持："TCP", "UDP", and "SCTP"，默认为："TCP"
    Protocol Protocol `json:"protocol,omitempty" protobuf:"bytes,2,opt,name=protocol,casttype=Protocol"`

    // TODO; 待确认
    AppProtocol *string `json:"appProtocol,omitempty" protobuf:"bytes,6,opt,name=appProtocol"`

    // 提供外部连接使用的服务端口
    Port int32 `json:"port" protobuf:"varint,3,opt,name=port"`

    // 后端容器端口或者端口关联的唯一名字，这个字段比较特殊，同时支持字符串与数字格式
    // 如果数字格式，说明为端口，必须在 1 至 65535 范围内
    // 如果是字符串格式，则说明为对应容器端口的名称
    TargetPort intstr.IntOrString `json:"targetPort,omitempty" protobuf:"bytes,4,opt,name=targetPort"`

    // 当类型为 "NodePort" 或 "LoadBalancer" 用于在工作节点额外开启提供外部服务的端口
    NodePort int32 `json:"nodePort,omitempty" protobuf:"varint,5,opt,name=nodePort"`
}

// Service Type string describes ingress methods for a service
type ServiceType string

const (
    // ServiceTypeClusterIP means a service will only be accessible inside the
    // cluster, via the cluster IP.
    ServiceTypeClusterIP ServiceType = "ClusterIP"

    // ServiceTypeNodePort means a service will be exposed on one port of
    // every node, in addition to 'ClusterIP' type.
    ServiceTypeNodePort ServiceType = "NodePort"

    // ServiceTypeLoadBalancer means a service will be exposed via an
    // external load balancer (if the cloud provider supports it), in addition
    // to 'NodePort' type.
    ServiceTypeLoadBalancer ServiceType = "LoadBalancer"

    // ServiceTypeExternalName means a service consists of only a reference to
    // an external name that kubedns or equivalent will return as a CNAME
    // record, with no exposing or proxying of any pods involved.
    ServiceTypeExternalName ServiceType = "ExternalName"
)

// Session Affinity Type string
type ServiceAffinity string

const (
    // ServiceAffinityClientIP is the Client IP based.
    ServiceAffinityClientIP ServiceAffinity = "ClientIP"

    // ServiceAffinityNone - no session affinity.
    ServiceAffinityNone ServiceAffinity = "None"
)

// Service External Traffic Policy Type string
type ServiceExternalTrafficPolicyType string

const (
    // ServiceExternalTrafficPolicyTypeLocal specifies node-local endpoints behavior.
    ServiceExternalTrafficPolicyTypeLocal ServiceExternalTrafficPolicyType = "Local"
    // ServiceExternalTrafficPolicyTypeCluster specifies node-global (legacy) behavior.
    ServiceExternalTrafficPolicyTypeCluster ServiceExternalTrafficPolicyType = "Cluster"
)

// SessionAffinityConfig represents the configurations of session affinity.
type SessionAffinityConfig struct {
    // clientIP contains the configurations of Client IP based session affinity.
    // +optional
    ClientIP *ClientIPConfig `json:"clientIP,omitempty" protobuf:"bytes,1,opt,name=clientIP"`
}

// ClientIPConfig represents the configurations of Client IP based session affinity.
type ClientIPConfig struct {
    // timeoutSeconds specifies the seconds of ClientIP type session sticky time.
    // The value must be >0 && <=86400(for 1 day) if ServiceAffinity == "ClientIP".
    // Default value is 10800(for 3 hours).
    // +optional
    TimeoutSeconds *int32 `json:"timeoutSeconds,omitempty" protobuf:"varint,1,opt,name=timeoutSeconds"`
}

// IPFamilyPolicyType represents the dual-stack-ness requested or required by a Service
type IPFamilyPolicyType string

const (
    // IPFamilyPolicySingleStack indicates that this service is required to have a single IPFamily.
    // The IPFamily assigned is based on the default IPFamily used by the cluster
    // or as identified by service.spec.ipFamilies field
    IPFamilyPolicySingleStack IPFamilyPolicyType = "SingleStack"
    // IPFamilyPolicyPreferDualStack indicates that this service prefers dual-stack when
    // the cluster is configured for dual-stack. If the cluster is not configured
    // for dual-stack the service will be assigned a single IPFamily. If the IPFamily is not
    // set in service.spec.ipFamilies then the service will be assigned the default IPFamily
    // configured on the cluster
    IPFamilyPolicyPreferDualStack IPFamilyPolicyType = "PreferDualStack"
    // IPFamilyPolicyRequireDualStack indicates that this service requires dual-stack. Using
    // IPFamilyPolicyRequireDualStack on a single stack cluster will result in validation errors. The
    // IPFamilies (and their order) assigned  to this service is based on service.spec.ipFamilies. If
    // service.spec.ipFamilies was not provided then it will be assigned according to how they are
    // configured on the cluster. If service.spec.ipFamilies has only one entry then the alternative
    // IPFamily will be added by apiserver
    IPFamilyPolicyRequireDualStack IPFamilyPolicyType = "RequireDualStack"
)

// ServiceInternalTrafficPolicyType describes the type of traffic routing for
// internal traffic
type ServiceInternalTrafficPolicyType string

const (
    // ServiceInternalTrafficPolicyCluster routes traffic to all endpoints
    ServiceInternalTrafficPolicyCluster ServiceInternalTrafficPolicyType = "Cluster"

    // ServiceInternalTrafficPolicyLocal only routes to node-local
    // endpoints, otherwise drops the traffic
    ServiceInternalTrafficPolicyLocal ServiceInternalTrafficPolicyType = "Local"
)

// Service External Traffic Policy Type string
type ServiceExternalTrafficPolicyType string

const (
    // ServiceExternalTrafficPolicyTypeLocal specifies node-local endpoints behavior.
    ServiceExternalTrafficPolicyTypeLocal ServiceExternalTrafficPolicyType = "Local"
    // ServiceExternalTrafficPolicyTypeCluster specifies node-global (legacy) behavior.
    ServiceExternalTrafficPolicyTypeCluster ServiceExternalTrafficPolicyType = "Cluster"
)