1 package v1 2 3 import ( 4 corev1 "k8s.io/api/core/v1" 5 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 6 "k8s.io/apimachinery/pkg/util/intstr" 7 ) 8 9 // +genclient 10 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 11 // +kubebuilder:object:root=true 12 // +kubebuilder:subresource:status 13 14 // A route allows developers to expose services through an HTTP(S) aware load balancing and proxy 15 // layer via a public DNS entry. The route may further specify TLS options and a certificate, or 16 // specify a public CNAME that the router should also accept for HTTP and HTTPS traffic. An 17 // administrator typically configures their router to be visible outside the cluster firewall, and 18 // may also add additional security, caching, or traffic controls on the service content. Routers 19 // usually talk directly to the service endpoints. 20 // 21 // Once a route is created, the `host` field may not be changed. Generally, routers use the oldest 22 // route with a given host when resolving conflicts. 23 // 24 // Routers are subject to additional customization and may support additional controls via the 25 // annotations field. 26 // 27 // Because administrators may configure multiple routers, the route status field is used to 28 // return information to clients about the names and states of the route under each router. 29 // If a client chooses a duplicate name, for instance, the route status conditions are used 30 // to indicate the route cannot be chosen. 31 // 32 // To enable HTTP/2 ALPN on a route it requires a custom 33 // (non-wildcard) certificate. This prevents connection coalescing by 34 // clients, notably web browsers. We do not support HTTP/2 ALPN on 35 // routes that use the default certificate because of the risk of 36 // connection re-use/coalescing. Routes that do not have their own 37 // custom certificate will not be HTTP/2 ALPN-enabled on either the 38 // frontend or the backend. 39 // 40 // Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). 41 // +openshift:compatibility-gen:level=1 42 type Route struct { 43 metav1.TypeMeta `json:",inline"` 44 45 // metadata is the standard object's metadata. 46 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 47 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 48 49 // spec is the desired state of the route 50 Spec RouteSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"` 51 // status is the current state of the route 52 // +optional 53 Status RouteStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"` 54 } 55 56 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 57 58 // RouteList is a collection of Routes. 59 // 60 // Compatibility level 1: Stable within a major release for a minimum of 12 months or 3 minor releases (whichever is longer). 61 // +openshift:compatibility-gen:level=1 62 type RouteList struct { 63 metav1.TypeMeta `json:",inline"` 64 65 // metadata is the standard list's metadata. 66 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 67 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 68 69 // items is a list of routes 70 Items []Route `json:"items" protobuf:"bytes,2,rep,name=items"` 71 } 72 73 // RouteSpec describes the hostname or path the route exposes, any security information, 74 // and one to four backends (services) the route points to. Requests are distributed 75 // among the backends depending on the weights assigned to each backend. When using 76 // roundrobin scheduling the portion of requests that go to each backend is the backend 77 // weight divided by the sum of all of the backend weights. When the backend has more than 78 // one endpoint the requests that end up on the backend are roundrobin distributed among 79 // the endpoints. Weights are between 0 and 256 with default 100. Weight 0 causes no requests 80 // to the backend. If all weights are zero the route will be considered to have no backends 81 // and return a standard 503 response. 82 // 83 // The `tls` field is optional and allows specific certificates or behavior for the 84 // route. Routers typically configure a default certificate on a wildcard domain to 85 // terminate routes without explicit certificates, but custom hostnames usually must 86 // choose passthrough (send traffic directly to the backend via the TLS Server-Name- 87 // Indication field) or provide a certificate. 88 type RouteSpec struct { 89 // host is an alias/DNS that points to the service. Optional. 90 // If not specified a route name will typically be automatically 91 // chosen. 92 // Must follow DNS952 subdomain conventions. 93 // 94 // +optional 95 // +kubebuilder:validation:MaxLength=253 96 // +kubebuilder:validation:Pattern=`^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])(\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9]))*$` 97 Host string `json:"host,omitempty" protobuf:"bytes,1,opt,name=host"` 98 // subdomain is a DNS subdomain that is requested within the ingress controller's 99 // domain (as a subdomain). If host is set this field is ignored. An ingress 100 // controller may choose to ignore this suggested name, in which case the controller 101 // will report the assigned name in the status.ingress array or refuse to admit the 102 // route. If this value is set and the server does not support this field host will 103 // be populated automatically. Otherwise host is left empty. The field may have 104 // multiple parts separated by a dot, but not all ingress controllers may honor 105 // the request. This field may not be changed after creation except by a user with 106 // the update routes/custom-host permission. 107 // 108 // Example: subdomain `frontend` automatically receives the router subdomain 109 // `apps.mycluster.com` to have a full hostname `frontend.apps.mycluster.com`. 110 // 111 // +optional 112 // +kubebuilder:validation:MaxLength=253 113 // +kubebuilder:validation:Pattern=`^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])(\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9]))*$` 114 Subdomain string `json:"subdomain,omitempty" protobuf:"bytes,8,opt,name=subdomain"` 115 116 // path that the router watches for, to route traffic for to the service. Optional 117 // 118 // +optional 119 // +kubebuilder:validation:Pattern=`^/` 120 Path string `json:"path,omitempty" protobuf:"bytes,2,opt,name=path"` 121 122 // to is an object the route should use as the primary backend. Only the Service kind 123 // is allowed, and it will be defaulted to Service. If the weight field (0-256 default 100) 124 // is set to zero, no traffic will be sent to this backend. 125 To RouteTargetReference `json:"to" protobuf:"bytes,3,opt,name=to"` 126 127 // alternateBackends allows up to 3 additional backends to be assigned to the route. 128 // Only the Service kind is allowed, and it will be defaulted to Service. 129 // Use the weight field in RouteTargetReference object to specify relative preference. 130 // 131 // +kubebuilder:validation:MaxItems=3 132 AlternateBackends []RouteTargetReference `json:"alternateBackends,omitempty" protobuf:"bytes,4,rep,name=alternateBackends"` 133 134 // If specified, the port to be used by the router. Most routers will use all 135 // endpoints exposed by the service by default - set this value to instruct routers 136 // which port to use. 137 Port *RoutePort `json:"port,omitempty" protobuf:"bytes,5,opt,name=port"` 138 139 // The tls field provides the ability to configure certificates and termination for the route. 140 TLS *TLSConfig `json:"tls,omitempty" protobuf:"bytes,6,opt,name=tls"` 141 142 // Wildcard policy if any for the route. 143 // Currently only 'Subdomain' or 'None' is allowed. 144 // 145 // +kubebuilder:validation:Enum=None;Subdomain;"" 146 // +kubebuilder:default=None 147 WildcardPolicy WildcardPolicyType `json:"wildcardPolicy,omitempty" protobuf:"bytes,7,opt,name=wildcardPolicy"` 148 } 149 150 // RouteTargetReference specifies the target that resolve into endpoints. Only the 'Service' 151 // kind is allowed. Use 'weight' field to emphasize one over others. 152 type RouteTargetReference struct { 153 // The kind of target that the route is referring to. Currently, only 'Service' is allowed 154 // 155 // +kubebuilder:validation:Enum=Service;"" 156 // +kubebuilder:default=Service 157 Kind string `json:"kind" protobuf:"bytes,1,opt,name=kind"` 158 159 // name of the service/target that is being referred to. e.g. name of the service 160 // 161 // +kubebuilder:validation:MinLength=1 162 Name string `json:"name" protobuf:"bytes,2,opt,name=name"` 163 164 // weight as an integer between 0 and 256, default 100, that specifies the target's relative weight 165 // against other target reference objects. 0 suppresses requests to this backend. 166 // 167 // +optional 168 // +kubebuilder:validation:Minimum=0 169 // +kubebuilder:validation:Maximum=256 170 // +kubebuilder:default=100 171 Weight *int32 `json:"weight" protobuf:"varint,3,opt,name=weight"` 172 } 173 174 // RoutePort defines a port mapping from a router to an endpoint in the service endpoints. 175 type RoutePort struct { 176 // The target port on pods selected by the service this route points to. 177 // If this is a string, it will be looked up as a named port in the target 178 // endpoints port list. Required 179 TargetPort intstr.IntOrString `json:"targetPort" protobuf:"bytes,1,opt,name=targetPort"` 180 } 181 182 // RouteStatus provides relevant info about the status of a route, including which routers 183 // acknowledge it. 184 type RouteStatus struct { 185 // ingress describes the places where the route may be exposed. The list of 186 // ingress points may contain duplicate Host or RouterName values. Routes 187 // are considered live once they are `Ready` 188 Ingress []RouteIngress `json:"ingress,omitempty" protobuf:"bytes,1,rep,name=ingress"` 189 } 190 191 // RouteIngress holds information about the places where a route is exposed. 192 type RouteIngress struct { 193 // Host is the host string under which the route is exposed; this value is required 194 Host string `json:"host,omitempty" protobuf:"bytes,1,opt,name=host"` 195 // Name is a name chosen by the router to identify itself; this value is required 196 RouterName string `json:"routerName,omitempty" protobuf:"bytes,2,opt,name=routerName"` 197 // Conditions is the state of the route, may be empty. 198 Conditions []RouteIngressCondition `json:"conditions,omitempty" protobuf:"bytes,3,rep,name=conditions"` 199 // Wildcard policy is the wildcard policy that was allowed where this route is exposed. 200 WildcardPolicy WildcardPolicyType `json:"wildcardPolicy,omitempty" protobuf:"bytes,4,opt,name=wildcardPolicy"` 201 // CanonicalHostname is the external host name for the router that can be used as a CNAME 202 // for the host requested for this route. This value is optional and may not be set in all cases. 203 RouterCanonicalHostname string `json:"routerCanonicalHostname,omitempty" protobuf:"bytes,5,opt,name=routerCanonicalHostname"` 204 } 205 206 // RouteIngressConditionType is a valid value for RouteCondition 207 type RouteIngressConditionType string 208 209 // These are valid conditions of pod. 210 const ( 211 // RouteAdmitted means the route is able to service requests for the provided Host 212 RouteAdmitted RouteIngressConditionType = "Admitted" 213 // TODO: add other route condition types 214 ) 215 216 // RouteIngressCondition contains details for the current condition of this route on a particular 217 // router. 218 type RouteIngressCondition struct { 219 // Type is the type of the condition. 220 // Currently only Admitted. 221 Type RouteIngressConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=RouteIngressConditionType"` 222 // Status is the status of the condition. 223 // Can be True, False, Unknown. 224 Status corev1.ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status,casttype=k8s.io/api/core/v1.ConditionStatus"` 225 // (brief) reason for the condition's last transition, and is usually a machine and human 226 // readable constant 227 Reason string `json:"reason,omitempty" protobuf:"bytes,3,opt,name=reason"` 228 // Human readable message indicating details about last transition. 229 Message string `json:"message,omitempty" protobuf:"bytes,4,opt,name=message"` 230 // RFC 3339 date and time when this condition last transitioned 231 LastTransitionTime *metav1.Time `json:"lastTransitionTime,omitempty" protobuf:"bytes,5,opt,name=lastTransitionTime"` 232 } 233 234 // RouterShard has information of a routing shard and is used to 235 // generate host names and routing table entries when a routing shard is 236 // allocated for a specific route. 237 // Caveat: This is WIP and will likely undergo modifications when sharding 238 // support is added. 239 type RouterShard struct { 240 // shardName uniquely identifies a router shard in the "set" of 241 // routers used for routing traffic to the services. 242 ShardName string `json:"shardName" protobuf:"bytes,1,opt,name=shardName"` 243 244 // dnsSuffix for the shard ala: shard-1.v3.openshift.com 245 DNSSuffix string `json:"dnsSuffix" protobuf:"bytes,2,opt,name=dnsSuffix"` 246 } 247 248 // TLSConfig defines config used to secure a route and provide termination 249 type TLSConfig struct { 250 // termination indicates termination type. 251 // 252 // * edge - TLS termination is done by the router and http is used to communicate with the backend (default) 253 // * passthrough - Traffic is sent straight to the destination without the router providing TLS termination 254 // * reencrypt - TLS termination is done by the router and https is used to communicate with the backend 255 // 256 // +kubebuilder:validation:Enum=edge;reencrypt;passthrough 257 Termination TLSTerminationType `json:"termination" protobuf:"bytes,1,opt,name=termination,casttype=TLSTerminationType"` 258 259 // certificate provides certificate contents. This should be a single serving certificate, not a certificate 260 // chain. Do not include a CA certificate. 261 Certificate string `json:"certificate,omitempty" protobuf:"bytes,2,opt,name=certificate"` 262 263 // key provides key file contents 264 Key string `json:"key,omitempty" protobuf:"bytes,3,opt,name=key"` 265 266 // caCertificate provides the cert authority certificate contents 267 CACertificate string `json:"caCertificate,omitempty" protobuf:"bytes,4,opt,name=caCertificate"` 268 269 // destinationCACertificate provides the contents of the ca certificate of the final destination. When using reencrypt 270 // termination this file should be provided in order to have routers use it for health checks on the secure connection. 271 // If this field is not specified, the router may provide its own destination CA and perform hostname validation using 272 // the short service name (service.namespace.svc), which allows infrastructure generated certificates to automatically 273 // verify. 274 DestinationCACertificate string `json:"destinationCACertificate,omitempty" protobuf:"bytes,5,opt,name=destinationCACertificate"` 275 276 // insecureEdgeTerminationPolicy indicates the desired behavior for insecure connections to a route. While 277 // each router may make its own decisions on which ports to expose, this is normally port 80. 278 // 279 // * Allow - traffic is sent to the server on the insecure port (default) 280 // * Disable - no traffic is allowed on the insecure port. 281 // * Redirect - clients are redirected to the secure port. 282 InsecureEdgeTerminationPolicy InsecureEdgeTerminationPolicyType `json:"insecureEdgeTerminationPolicy,omitempty" protobuf:"bytes,6,opt,name=insecureEdgeTerminationPolicy,casttype=InsecureEdgeTerminationPolicyType"` 283 } 284 285 // TLSTerminationType dictates where the secure communication will stop 286 // TODO: Reconsider this type in v2 287 type TLSTerminationType string 288 289 // InsecureEdgeTerminationPolicyType dictates the behavior of insecure 290 // connections to an edge-terminated route. 291 type InsecureEdgeTerminationPolicyType string 292 293 const ( 294 // TLSTerminationEdge terminate encryption at the edge router. 295 TLSTerminationEdge TLSTerminationType = "edge" 296 // TLSTerminationPassthrough terminate encryption at the destination, the destination is responsible for decrypting traffic 297 TLSTerminationPassthrough TLSTerminationType = "passthrough" 298 // TLSTerminationReencrypt terminate encryption at the edge router and re-encrypt it with a new certificate supplied by the destination 299 TLSTerminationReencrypt TLSTerminationType = "reencrypt" 300 301 // InsecureEdgeTerminationPolicyNone disables insecure connections for an edge-terminated route. 302 InsecureEdgeTerminationPolicyNone InsecureEdgeTerminationPolicyType = "None" 303 // InsecureEdgeTerminationPolicyAllow allows insecure connections for an edge-terminated route. 304 InsecureEdgeTerminationPolicyAllow InsecureEdgeTerminationPolicyType = "Allow" 305 // InsecureEdgeTerminationPolicyRedirect redirects insecure connections for an edge-terminated route. 306 // As an example, for routers that support HTTP and HTTPS, the 307 // insecure HTTP connections will be redirected to use HTTPS. 308 InsecureEdgeTerminationPolicyRedirect InsecureEdgeTerminationPolicyType = "Redirect" 309 ) 310 311 // WildcardPolicyType indicates the type of wildcard support needed by routes. 312 type WildcardPolicyType string 313 314 const ( 315 // WildcardPolicyNone indicates no wildcard support is needed. 316 WildcardPolicyNone WildcardPolicyType = "None" 317 318 // WildcardPolicySubdomain indicates the host needs wildcard support for the subdomain. 319 // Example: For host = "www.acme.test", indicates that the router 320 // should support requests for *.acme.test 321 // Note that this will not match acme.test only *.acme.test 322 WildcardPolicySubdomain WildcardPolicyType = "Subdomain" 323 ) 324 325 // Route Annotations 326 const ( 327 // AllowNonDNSCompliantHostAnnotation indicates that the host name in a route 328 // configuration is not required to follow strict DNS compliance. 329 // Unless the annotation is set to true, the route host name must have at least one label. 330 // Labels must have no more than 63 characters from the set of 331 // alphanumeric characters, '-' or '.', and must start and end with an alphanumeric 332 // character. A trailing dot is not allowed. The total host name length must be no more 333 // than 253 characters. 334 // 335 // When the annotation is set to true, the host name must pass a smaller set of 336 // requirements, i.e.: character set as described above, and total host name 337 // length must be no more than 253 characters. 338 // 339 // NOTE: use of this annotation may validate routes that cannot be admitted and will 340 // not function. The annotation is provided to allow a custom scenario, e.g. a custom 341 // ingress controller that relies on the route API, but for some customized purpose 342 // needs to use routes with invalid hosts. 343 AllowNonDNSCompliantHostAnnotation = "route.openshift.io/allow-non-dns-compliant-host" 344 ) 345 346 // Ingress-to-route controller 347 const ( 348 // IngressToRouteIngressClassControllerName is the name of the 349 // controller that translates ingresses into routes. This value is 350 // intended to be used for the spec.controller field of ingressclasses. 351 IngressToRouteIngressClassControllerName = "openshift.io/ingress-to-route" 352 ) 353