mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-08-05 10:19:50 +00:00
Try to clarify EndpointSlice semantics some more
Especially, the difference between what the API allows, and what the EndpointSlice controller and kube-proxy support.
This commit is contained in:
parent
d36322f8d7
commit
ab80d57732
@ -25,9 +25,12 @@ import (
|
|||||||
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
|
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
|
||||||
// +k8s:prerelease-lifecycle-gen:introduced=1.21
|
// +k8s:prerelease-lifecycle-gen:introduced=1.21
|
||||||
|
|
||||||
// EndpointSlice represents a subset of the endpoints that implement a service.
|
// EndpointSlice represents a set of service endpoints. Most EndpointSlices are created by
|
||||||
// For a given service there may be multiple EndpointSlice objects, selected by
|
// the EndpointSlice controller to represent the Pods selected by Service objects. For a
|
||||||
// labels, which must be joined to produce the full set of endpoints.
|
// given service there may be multiple EndpointSlice objects which must be joined to
|
||||||
|
// produce the full set of endpoints; you can find all of the slices for a given service
|
||||||
|
// by listing EndpointSlices in the service's namespace whose `kubernetes.io/service-name`
|
||||||
|
// label contains the service's name.
|
||||||
type EndpointSlice struct {
|
type EndpointSlice struct {
|
||||||
metav1.TypeMeta `json:",inline"`
|
metav1.TypeMeta `json:",inline"`
|
||||||
|
|
||||||
@ -41,7 +44,10 @@ type EndpointSlice struct {
|
|||||||
// supported:
|
// supported:
|
||||||
// * IPv4: Represents an IPv4 Address.
|
// * IPv4: Represents an IPv4 Address.
|
||||||
// * IPv6: Represents an IPv6 Address.
|
// * IPv6: Represents an IPv6 Address.
|
||||||
// * FQDN: Represents a Fully Qualified Domain Name.
|
// * FQDN: Represents a Fully Qualified Domain Name. (Deprecated)
|
||||||
|
// The EndpointSlice controller only generates, and kube-proxy only processes,
|
||||||
|
// slices of addressType "IPv4" and "IPv6". No semantics are defined for
|
||||||
|
// the "FQDN" type.
|
||||||
AddressType AddressType `json:"addressType" protobuf:"bytes,4,rep,name=addressType"`
|
AddressType AddressType `json:"addressType" protobuf:"bytes,4,rep,name=addressType"`
|
||||||
|
|
||||||
// endpoints is a list of unique endpoints in this slice. Each slice may
|
// endpoints is a list of unique endpoints in this slice. Each slice may
|
||||||
@ -50,10 +56,11 @@ type EndpointSlice struct {
|
|||||||
Endpoints []Endpoint `json:"endpoints" protobuf:"bytes,2,rep,name=endpoints"`
|
Endpoints []Endpoint `json:"endpoints" protobuf:"bytes,2,rep,name=endpoints"`
|
||||||
|
|
||||||
// ports specifies the list of network ports exposed by each endpoint in
|
// ports specifies the list of network ports exposed by each endpoint in
|
||||||
// this slice. Each port must have a unique name. When ports is empty, it
|
// this slice. Each port must have a unique name. Each slice may include a
|
||||||
// indicates that there are no defined ports. When a port is defined with a
|
|
||||||
// nil port value, it indicates "all ports". Each slice may include a
|
|
||||||
// maximum of 100 ports.
|
// maximum of 100 ports.
|
||||||
|
// Services always have at least 1 port, so EndpointSlices generated by the
|
||||||
|
// EndpointSlice controller will likewise always have at least 1 port.
|
||||||
|
// EndpointSlices used for other purposes may have an empty ports list.
|
||||||
// +optional
|
// +optional
|
||||||
// +listType=atomic
|
// +listType=atomic
|
||||||
Ports []EndpointPort `json:"ports" protobuf:"bytes,3,rep,name=ports"`
|
Ports []EndpointPort `json:"ports" protobuf:"bytes,3,rep,name=ports"`
|
||||||
@ -76,12 +83,12 @@ const (
|
|||||||
|
|
||||||
// Endpoint represents a single logical "backend" implementing a service.
|
// Endpoint represents a single logical "backend" implementing a service.
|
||||||
type Endpoint struct {
|
type Endpoint struct {
|
||||||
// addresses of this endpoint. The contents of this field are interpreted
|
// addresses of this endpoint. For EndpointSlices of addressType "IPv4" or "IPv6",
|
||||||
// according to the corresponding EndpointSlice addressType field. Consumers
|
// the values are IP addresses in canonical form. The syntax and semantics of
|
||||||
// must handle different types of addresses in the context of their own
|
// other addressType values are not defined. This must contain at least one
|
||||||
// capabilities. This must contain at least one address but no more than
|
// address but no more than 100. EndpointSlices generated by the EndpointSlice
|
||||||
// 100. These are all assumed to be fungible and clients may choose to only
|
// controller will always have exactly 1 address. No semantics are defined for
|
||||||
// use the first element. Refer to: https://issue.k8s.io/106267
|
// additional addresses beyond the first, and kube-proxy does not look at them.
|
||||||
// +listType=set
|
// +listType=set
|
||||||
Addresses []string `json:"addresses" protobuf:"bytes,1,rep,name=addresses"`
|
Addresses []string `json:"addresses" protobuf:"bytes,1,rep,name=addresses"`
|
||||||
|
|
||||||
@ -127,26 +134,25 @@ type Endpoint struct {
|
|||||||
|
|
||||||
// EndpointConditions represents the current condition of an endpoint.
|
// EndpointConditions represents the current condition of an endpoint.
|
||||||
type EndpointConditions struct {
|
type EndpointConditions struct {
|
||||||
// ready indicates that this endpoint is prepared to receive traffic,
|
// ready indicates that this endpoint is ready to receive traffic,
|
||||||
// according to whatever system is managing the endpoint. A nil value
|
// according to whatever system is managing the endpoint. A nil value
|
||||||
// indicates an unknown state. In most cases consumers should interpret this
|
// should be interpreted as "true". In general, an endpoint should be
|
||||||
// unknown state as ready. For compatibility reasons, ready should never be
|
// marked ready if it is serving and not terminating, though this can
|
||||||
// "true" for terminating endpoints, except when the normal readiness
|
// be overridden in some cases, such as when the associated Service has
|
||||||
// behavior is being explicitly overridden, for example when the associated
|
// set the publishNotReadyAddresses flag.
|
||||||
// Service has set the publishNotReadyAddresses flag.
|
|
||||||
// +optional
|
// +optional
|
||||||
Ready *bool `json:"ready,omitempty" protobuf:"bytes,1,name=ready"`
|
Ready *bool `json:"ready,omitempty" protobuf:"bytes,1,name=ready"`
|
||||||
|
|
||||||
// serving is identical to ready except that it is set regardless of the
|
// serving indicates that this endpoint is able to receive traffic,
|
||||||
// terminating state of endpoints. This condition should be set to true for
|
// according to whatever system is managing the endpoint. For endpoints
|
||||||
// a ready endpoint that is terminating. If nil, consumers should defer to
|
// backed by pods, the EndpointSlice controller will mark the endpoint
|
||||||
// the ready condition.
|
// as serving if the pod's Ready condition is True. A nil value should be
|
||||||
|
// interpreted as "true".
|
||||||
// +optional
|
// +optional
|
||||||
Serving *bool `json:"serving,omitempty" protobuf:"bytes,2,name=serving"`
|
Serving *bool `json:"serving,omitempty" protobuf:"bytes,2,name=serving"`
|
||||||
|
|
||||||
// terminating indicates that this endpoint is terminating. A nil value
|
// terminating indicates that this endpoint is terminating. A nil value
|
||||||
// indicates an unknown state. Consumers should interpret this unknown state
|
// should be interpreted as "false".
|
||||||
// to mean that the endpoint is not terminating.
|
|
||||||
// +optional
|
// +optional
|
||||||
Terminating *bool `json:"terminating,omitempty" protobuf:"bytes,3,name=terminating"`
|
Terminating *bool `json:"terminating,omitempty" protobuf:"bytes,3,name=terminating"`
|
||||||
}
|
}
|
||||||
@ -183,8 +189,9 @@ type EndpointPort struct {
|
|||||||
Protocol *v1.Protocol `json:"protocol,omitempty" protobuf:"bytes,2,name=protocol"`
|
Protocol *v1.Protocol `json:"protocol,omitempty" protobuf:"bytes,2,name=protocol"`
|
||||||
|
|
||||||
// port represents the port number of the endpoint.
|
// port represents the port number of the endpoint.
|
||||||
// If this is not specified, ports are not restricted and must be
|
// If the EndpointSlice is derived from a Kubernetes service, this must be set
|
||||||
// interpreted in the context of the specific consumer.
|
// to the service's target port. EndpointSlices used for other purposes may have
|
||||||
|
// a nil port.
|
||||||
Port *int32 `json:"port,omitempty" protobuf:"bytes,3,opt,name=port"`
|
Port *int32 `json:"port,omitempty" protobuf:"bytes,3,opt,name=port"`
|
||||||
|
|
||||||
// The application protocol for this port.
|
// The application protocol for this port.
|
||||||
|
Loading…
Reference in New Issue
Block a user