1 /* 2 Copyright 2019 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 package discovery 18 19 import ( 20 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 21 api "k8s.io/kubernetes/pkg/apis/core" 22 ) 23 24 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 25 26 // EndpointSlice represents a subset of the endpoints that implement a service. 27 // For a given service there may be multiple EndpointSlice objects, selected by 28 // labels, which must be joined to produce the full set of endpoints. 29 type EndpointSlice struct { 30 metav1.TypeMeta 31 // Standard object's metadata. 32 // +optional 33 metav1.ObjectMeta 34 // addressType specifies the type of address carried by this EndpointSlice. 35 // All addresses in this slice must be the same type. This field is 36 // immutable after creation. The following address types are currently 37 // supported: 38 // * IPv4: Represents an IPv4 Address. 39 // * IPv6: Represents an IPv6 Address. 40 // * FQDN: Represents a Fully Qualified Domain Name. [DEPRECATED] 41 AddressType AddressType 42 // endpoints is a list of unique endpoints in this slice. Each slice may 43 // include a maximum of 1000 endpoints. 44 // +listType=atomic 45 Endpoints []Endpoint 46 // ports specifies the list of network ports exposed by each endpoint in 47 // this slice. Each port must have a unique name. When ports is empty, it 48 // indicates that there are no defined ports. When a port is defined with a 49 // nil port value, it indicates "all ports". Each slice may include a 50 // maximum of 100 ports. 51 // +optional 52 // +listType=atomic 53 Ports []EndpointPort 54 } 55 56 // AddressType represents the type of address referred to by an endpoint. 57 type AddressType string 58 59 const ( 60 // AddressTypeIPv4 represents an IPv4 Address. 61 AddressTypeIPv4 = AddressType(api.IPv4Protocol) 62 // AddressTypeIPv6 represents an IPv6 Address. 63 AddressTypeIPv6 = AddressType(api.IPv6Protocol) 64 // AddressTypeFQDN represents a FQDN. 65 AddressTypeFQDN = AddressType("FQDN") 66 ) 67 68 // Endpoint represents a single logical "backend" implementing a service. 69 type Endpoint struct { 70 // addresses of this endpoint. The contents of this field are interpreted 71 // according to the corresponding EndpointSlice addressType field. Consumers 72 // must handle different types of addresses in the context of their own 73 // capabilities. This must contain at least one address but no more than 74 // 100. 75 // +listType=set 76 Addresses []string 77 // conditions contains information about the current status of the endpoint. 78 Conditions EndpointConditions 79 // hostname of this endpoint. This field may be used by consumers of 80 // endpoints to distinguish endpoints from each other (e.g. in DNS names). 81 // Multiple endpoints which use the same hostname should be considered 82 // fungible (e.g. multiple A values in DNS). Must pass DNS Label (RFC 1123) 83 // validation. 84 // +optional 85 Hostname *string 86 // targetRef is a reference to a Kubernetes object that represents this 87 // endpoint. 88 // +optional 89 TargetRef *api.ObjectReference 90 // deprecatedTopology is deprecated and only retained for round-trip 91 // compatibility with v1beta1 Topology field. When v1beta1 is removed, this 92 // should be removed, too. 93 // +optional 94 DeprecatedTopology map[string]string 95 // nodeName represents the name of the Node hosting this endpoint. This can 96 // be used to determine endpoints local to a Node. 97 // +optional 98 NodeName *string 99 // zone is the name of the Zone this endpoint exists in. 100 // +optional 101 Zone *string 102 // hints contains information associated with how an endpoint should be 103 // consumed. 104 // +featureGate=TopologyAwareHints 105 // +optional 106 Hints *EndpointHints 107 } 108 109 // EndpointConditions represents the current condition of an endpoint. 110 type EndpointConditions struct { 111 // ready indicates that this endpoint is prepared to receive traffic, 112 // according to whatever system is managing the endpoint. A nil value 113 // indicates an unknown state. In most cases consumers should interpret this 114 // unknown state as ready. For compatibility reasons, ready should never be 115 // "true" for terminating endpoints, except when the normal readiness 116 // behavior is being explicitly overridden, for example when the associated 117 // Service has set the publishNotReadyAddresses flag. 118 Ready *bool 119 120 // serving is identical to ready except that it is set regardless of the 121 // terminating state of endpoints. This condition should be set to true for 122 // a ready endpoint that is terminating. If nil, consumers should defer to 123 // the ready condition. 124 // +optional 125 Serving *bool 126 127 // terminating indicates that this endpoint is terminating. A nil value 128 // indicates an unknown state. Consumers should interpret this unknown state 129 // to mean that the endpoint is not terminating. 130 // +optional 131 Terminating *bool 132 } 133 134 // EndpointHints provides hints describing how an endpoint should be consumed. 135 type EndpointHints struct { 136 // forZones indicates the zone(s) this endpoint should be consumed by to 137 // enable topology aware routing. May contain a maximum of 8 entries. 138 ForZones []ForZone 139 } 140 141 // ForZone provides information about which zones should consume this endpoint. 142 type ForZone struct { 143 // name represents the name of the zone. 144 Name string 145 } 146 147 // EndpointPort represents a Port used by an EndpointSlice. 148 type EndpointPort struct { 149 // The name of this port. All ports in an EndpointSlice must have a unique 150 // name. If the EndpointSlice is derived from a Kubernetes service, this 151 // corresponds to the Service.ports[].name. 152 // Name must either be an empty string or pass DNS_LABEL validation: 153 // * must be no more than 63 characters long. 154 // * must consist of lower case alphanumeric characters or '-'. 155 // * must start and end with an alphanumeric character. 156 Name *string 157 // The IP protocol for this port. 158 // Must be UDP, TCP, or SCTP. 159 Protocol *api.Protocol 160 // The port number of the endpoint. 161 // If this is not specified, ports are not restricted and must be 162 // interpreted in the context of the specific consumer. 163 Port *int32 164 // The application protocol for this port. 165 // This is used as a hint for implementations to offer richer behavior for protocols that they understand. 166 // This field follows standard Kubernetes label syntax. 167 // Valid values are either: 168 // 169 // * Un-prefixed protocol names - reserved for IANA standard service names (as per 170 // RFC-6335 and https://www.iana.org/assignments/service-names). 171 // 172 // * Kubernetes-defined prefixed names: 173 // * 'kubernetes.io/h2c' - HTTP/2 prior knowledge over cleartext as described in https://www.rfc-editor.org/rfc/rfc9113.html#name-starting-http-2-with-prior- 174 // * 'kubernetes.io/ws' - WebSocket over cleartext as described in https://www.rfc-editor.org/rfc/rfc6455 175 // * 'kubernetes.io/wss' - WebSocket over TLS as described in https://www.rfc-editor.org/rfc/rfc6455 176 // 177 // * Other protocols should use implementation-defined prefixed names such as 178 // mycompany.com/my-custom-protocol. 179 // +optional 180 AppProtocol *string 181 } 182 183 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 184 185 // EndpointSliceList represents a list of endpoint slices. 186 type EndpointSliceList struct { 187 metav1.TypeMeta 188 // Standard list metadata. 189 // +optional 190 metav1.ListMeta 191 // List of endpoint slices 192 Items []EndpointSlice 193 } 194