1 /* 2 Copyright 2020 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 v1 18 19 import ( 20 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 21 ) 22 23 // +genclient 24 // +kubebuilder:object:root=true 25 // +kubebuilder:resource:categories=gateway-api 26 // +kubebuilder:subresource:status 27 // +kubebuilder:printcolumn:name="Hostnames",type=string,JSONPath=`.spec.hostnames` 28 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp` 29 30 // HTTPRoute provides a way to route HTTP requests. This includes the capability 31 // to match requests by hostname, path, header, or query param. Filters can be 32 // used to specify additional processing steps. Backends specify where matching 33 // requests should be routed. 34 type HTTPRoute struct { 35 metav1.TypeMeta `json:",inline"` 36 metav1.ObjectMeta `json:"metadata,omitempty"` 37 38 // Spec defines the desired state of HTTPRoute. 39 Spec HTTPRouteSpec `json:"spec"` 40 41 // Status defines the current state of HTTPRoute. 42 Status HTTPRouteStatus `json:"status,omitempty"` 43 } 44 45 // +kubebuilder:object:root=true 46 47 // HTTPRouteList contains a list of HTTPRoute. 48 type HTTPRouteList struct { 49 metav1.TypeMeta `json:",inline"` 50 metav1.ListMeta `json:"metadata,omitempty"` 51 Items []HTTPRoute `json:"items"` 52 } 53 54 // HTTPRouteSpec defines the desired state of HTTPRoute 55 type HTTPRouteSpec struct { 56 CommonRouteSpec `json:",inline"` 57 58 // Hostnames defines a set of hostnames that should match against the HTTP Host 59 // header to select a HTTPRoute used to process the request. Implementations 60 // MUST ignore any port value specified in the HTTP Host header while 61 // performing a match and (absent of any applicable header modification 62 // configuration) MUST forward this header unmodified to the backend. 63 // 64 // Valid values for Hostnames are determined by RFC 1123 definition of a 65 // hostname with 2 notable exceptions: 66 // 67 // 1. IPs are not allowed. 68 // 2. A hostname may be prefixed with a wildcard label (`*.`). The wildcard 69 // label must appear by itself as the first label. 70 // 71 // If a hostname is specified by both the Listener and HTTPRoute, there 72 // must be at least one intersecting hostname for the HTTPRoute to be 73 // attached to the Listener. For example: 74 // 75 // * A Listener with `test.example.com` as the hostname matches HTTPRoutes 76 // that have either not specified any hostnames, or have specified at 77 // least one of `test.example.com` or `*.example.com`. 78 // * A Listener with `*.example.com` as the hostname matches HTTPRoutes 79 // that have either not specified any hostnames or have specified at least 80 // one hostname that matches the Listener hostname. For example, 81 // `*.example.com`, `test.example.com`, and `foo.test.example.com` would 82 // all match. On the other hand, `example.com` and `test.example.net` would 83 // not match. 84 // 85 // Hostnames that are prefixed with a wildcard label (`*.`) are interpreted 86 // as a suffix match. That means that a match for `*.example.com` would match 87 // both `test.example.com`, and `foo.test.example.com`, but not `example.com`. 88 // 89 // If both the Listener and HTTPRoute have specified hostnames, any 90 // HTTPRoute hostnames that do not match the Listener hostname MUST be 91 // ignored. For example, if a Listener specified `*.example.com`, and the 92 // HTTPRoute specified `test.example.com` and `test.example.net`, 93 // `test.example.net` must not be considered for a match. 94 // 95 // If both the Listener and HTTPRoute have specified hostnames, and none 96 // match with the criteria above, then the HTTPRoute is not accepted. The 97 // implementation must raise an 'Accepted' Condition with a status of 98 // `False` in the corresponding RouteParentStatus. 99 // 100 // In the event that multiple HTTPRoutes specify intersecting hostnames (e.g. 101 // overlapping wildcard matching and exact matching hostnames), precedence must 102 // be given to rules from the HTTPRoute with the largest number of: 103 // 104 // * Characters in a matching non-wildcard hostname. 105 // * Characters in a matching hostname. 106 // 107 // If ties exist across multiple Routes, the matching precedence rules for 108 // HTTPRouteMatches takes over. 109 // 110 // Support: Core 111 // 112 // +optional 113 // +kubebuilder:validation:MaxItems=16 114 Hostnames []Hostname `json:"hostnames,omitempty"` 115 116 // Rules are a list of HTTP matchers, filters and actions. 117 // 118 // +optional 119 // +kubebuilder:validation:MaxItems=16 120 // +kubebuilder:default={{matches: {{path: {type: "PathPrefix", value: "/"}}}}} 121 Rules []HTTPRouteRule `json:"rules,omitempty"` 122 } 123 124 // HTTPRouteRule defines semantics for matching an HTTP request based on 125 // conditions (matches), processing it (filters), and forwarding the request to 126 // an API object (backendRefs). 127 // 128 // +kubebuilder:validation:XValidation:message="RequestRedirect filter must not be used together with backendRefs",rule="(has(self.backendRefs) && size(self.backendRefs) > 0) ? (!has(self.filters) || self.filters.all(f, !has(f.requestRedirect))): true" 129 // +kubebuilder:validation:XValidation:message="When using RequestRedirect filter with path.replacePrefixMatch, exactly one PathPrefix match must be specified",rule="(has(self.filters) && self.filters.exists_one(f, has(f.requestRedirect) && has(f.requestRedirect.path) && f.requestRedirect.path.type == 'ReplacePrefixMatch' && has(f.requestRedirect.path.replacePrefixMatch))) ? ((size(self.matches) != 1 || !has(self.matches[0].path) || self.matches[0].path.type != 'PathPrefix') ? false : true) : true" 130 // +kubebuilder:validation:XValidation:message="When using URLRewrite filter with path.replacePrefixMatch, exactly one PathPrefix match must be specified",rule="(has(self.filters) && self.filters.exists_one(f, has(f.urlRewrite) && has(f.urlRewrite.path) && f.urlRewrite.path.type == 'ReplacePrefixMatch' && has(f.urlRewrite.path.replacePrefixMatch))) ? ((size(self.matches) != 1 || !has(self.matches[0].path) || self.matches[0].path.type != 'PathPrefix') ? false : true) : true" 131 // +kubebuilder:validation:XValidation:message="Within backendRefs, when using RequestRedirect filter with path.replacePrefixMatch, exactly one PathPrefix match must be specified",rule="(has(self.backendRefs) && self.backendRefs.exists_one(b, (has(b.filters) && b.filters.exists_one(f, has(f.requestRedirect) && has(f.requestRedirect.path) && f.requestRedirect.path.type == 'ReplacePrefixMatch' && has(f.requestRedirect.path.replacePrefixMatch))) )) ? ((size(self.matches) != 1 || !has(self.matches[0].path) || self.matches[0].path.type != 'PathPrefix') ? false : true) : true" 132 // +kubebuilder:validation:XValidation:message="Within backendRefs, When using URLRewrite filter with path.replacePrefixMatch, exactly one PathPrefix match must be specified",rule="(has(self.backendRefs) && self.backendRefs.exists_one(b, (has(b.filters) && b.filters.exists_one(f, has(f.urlRewrite) && has(f.urlRewrite.path) && f.urlRewrite.path.type == 'ReplacePrefixMatch' && has(f.urlRewrite.path.replacePrefixMatch))) )) ? ((size(self.matches) != 1 || !has(self.matches[0].path) || self.matches[0].path.type != 'PathPrefix') ? false : true) : true" 133 type HTTPRouteRule struct { 134 // Matches define conditions used for matching the rule against incoming 135 // HTTP requests. Each match is independent, i.e. this rule will be matched 136 // if **any** one of the matches is satisfied. 137 // 138 // For example, take the following matches configuration: 139 // 140 // ``` 141 // matches: 142 // - path: 143 // value: "/foo" 144 // headers: 145 // - name: "version" 146 // value: "v2" 147 // - path: 148 // value: "/v2/foo" 149 // ``` 150 // 151 // For a request to match against this rule, a request must satisfy 152 // EITHER of the two conditions: 153 // 154 // - path prefixed with `/foo` AND contains the header `version: v2` 155 // - path prefix of `/v2/foo` 156 // 157 // See the documentation for HTTPRouteMatch on how to specify multiple 158 // match conditions that should be ANDed together. 159 // 160 // If no matches are specified, the default is a prefix 161 // path match on "/", which has the effect of matching every 162 // HTTP request. 163 // 164 // Proxy or Load Balancer routing configuration generated from HTTPRoutes 165 // MUST prioritize matches based on the following criteria, continuing on 166 // ties. Across all rules specified on applicable Routes, precedence must be 167 // given to the match having: 168 // 169 // * "Exact" path match. 170 // * "Prefix" path match with largest number of characters. 171 // * Method match. 172 // * Largest number of header matches. 173 // * Largest number of query param matches. 174 // 175 // Note: The precedence of RegularExpression path matches are implementation-specific. 176 // 177 // If ties still exist across multiple Routes, matching precedence MUST be 178 // determined in order of the following criteria, continuing on ties: 179 // 180 // * The oldest Route based on creation timestamp. 181 // * The Route appearing first in alphabetical order by 182 // "{namespace}/{name}". 183 // 184 // If ties still exist within an HTTPRoute, matching precedence MUST be granted 185 // to the FIRST matching rule (in list order) with a match meeting the above 186 // criteria. 187 // 188 // When no rules matching a request have been successfully attached to the 189 // parent a request is coming from, a HTTP 404 status code MUST be returned. 190 // 191 // +optional 192 // +kubebuilder:validation:MaxItems=8 193 // +kubebuilder:default={{path:{ type: "PathPrefix", value: "/"}}} 194 Matches []HTTPRouteMatch `json:"matches,omitempty"` 195 196 // Filters define the filters that are applied to requests that match 197 // this rule. 198 // 199 // The effects of ordering of multiple behaviors are currently unspecified. 200 // This can change in the future based on feedback during the alpha stage. 201 // 202 // Conformance-levels at this level are defined based on the type of filter: 203 // 204 // - ALL core filters MUST be supported by all implementations. 205 // - Implementers are encouraged to support extended filters. 206 // - Implementation-specific custom filters have no API guarantees across 207 // implementations. 208 // 209 // Specifying the same filter multiple times is not supported unless explicitly 210 // indicated in the filter. 211 // 212 // All filters are expected to be compatible with each other except for the 213 // URLRewrite and RequestRedirect filters, which may not be combined. If an 214 // implementation can not support other combinations of filters, they must clearly 215 // document that limitation. In cases where incompatible or unsupported 216 // filters are specified and cause the `Accepted` condition to be set to status 217 // `False`, implementations may use the `IncompatibleFilters` reason to specify 218 // this configuration error. 219 // 220 // Support: Core 221 // 222 // +optional 223 // +kubebuilder:validation:MaxItems=16 224 // +kubebuilder:validation:XValidation:message="May specify either httpRouteFilterRequestRedirect or httpRouteFilterRequestRewrite, but not both",rule="!(self.exists(f, f.type == 'RequestRedirect') && self.exists(f, f.type == 'URLRewrite'))" 225 // +kubebuilder:validation:XValidation:message="RequestHeaderModifier filter cannot be repeated",rule="self.filter(f, f.type == 'RequestHeaderModifier').size() <= 1" 226 // +kubebuilder:validation:XValidation:message="ResponseHeaderModifier filter cannot be repeated",rule="self.filter(f, f.type == 'ResponseHeaderModifier').size() <= 1" 227 // +kubebuilder:validation:XValidation:message="RequestRedirect filter cannot be repeated",rule="self.filter(f, f.type == 'RequestRedirect').size() <= 1" 228 // +kubebuilder:validation:XValidation:message="URLRewrite filter cannot be repeated",rule="self.filter(f, f.type == 'URLRewrite').size() <= 1" 229 Filters []HTTPRouteFilter `json:"filters,omitempty"` 230 231 // BackendRefs defines the backend(s) where matching requests should be 232 // sent. 233 // 234 // Failure behavior here depends on how many BackendRefs are specified and 235 // how many are invalid. 236 // 237 // If *all* entries in BackendRefs are invalid, and there are also no filters 238 // specified in this route rule, *all* traffic which matches this rule MUST 239 // receive a 500 status code. 240 // 241 // See the HTTPBackendRef definition for the rules about what makes a single 242 // HTTPBackendRef invalid. 243 // 244 // When a HTTPBackendRef is invalid, 500 status codes MUST be returned for 245 // requests that would have otherwise been routed to an invalid backend. If 246 // multiple backends are specified, and some are invalid, the proportion of 247 // requests that would otherwise have been routed to an invalid backend 248 // MUST receive a 500 status code. 249 // 250 // For example, if two backends are specified with equal weights, and one is 251 // invalid, 50 percent of traffic must receive a 500. Implementations may 252 // choose how that 50 percent is determined. 253 // 254 // Support: Core for Kubernetes Service 255 // 256 // Support: Extended for Kubernetes ServiceImport 257 // 258 // Support: Implementation-specific for any other resource 259 // 260 // Support for weight: Core 261 // 262 // +optional 263 // +kubebuilder:validation:MaxItems=16 264 BackendRefs []HTTPBackendRef `json:"backendRefs,omitempty"` 265 266 // Timeouts defines the timeouts that can be configured for an HTTP request. 267 // 268 // Support: Extended 269 // 270 // +optional 271 // <gateway:experimental> 272 Timeouts *HTTPRouteTimeouts `json:"timeouts,omitempty"` 273 } 274 275 // HTTPRouteTimeouts defines timeouts that can be configured for an HTTPRoute. 276 // Timeout values are represented with Gateway API Duration formatting. 277 // Specifying a zero value such as "0s" is interpreted as no timeout. 278 // 279 // +kubebuilder:validation:XValidation:message="backendRequest timeout cannot be longer than request timeout",rule="!(has(self.request) && has(self.backendRequest) && duration(self.request) != duration('0s') && duration(self.backendRequest) > duration(self.request))" 280 type HTTPRouteTimeouts struct { 281 // Request specifies the maximum duration for a gateway to respond to an HTTP request. 282 // If the gateway has not been able to respond before this deadline is met, the gateway 283 // MUST return a timeout error. 284 // 285 // For example, setting the `rules.timeouts.request` field to the value `10s` in an 286 // `HTTPRoute` will cause a timeout if a client request is taking longer than 10 seconds 287 // to complete. 288 // 289 // This timeout is intended to cover as close to the whole request-response transaction 290 // as possible although an implementation MAY choose to start the timeout after the entire 291 // request stream has been received instead of immediately after the transaction is 292 // initiated by the client. 293 // 294 // When this field is unspecified, request timeout behavior is implementation-specific. 295 // 296 // Support: Extended 297 // 298 // +optional 299 Request *Duration `json:"request,omitempty"` 300 301 // BackendRequest specifies a timeout for an individual request from the gateway 302 // to a backend. This covers the time from when the request first starts being 303 // sent from the gateway to when the full response has been received from the backend. 304 // 305 // An entire client HTTP transaction with a gateway, covered by the Request timeout, 306 // may result in more than one call from the gateway to the destination backend, 307 // for example, if automatic retries are supported. 308 // 309 // Because the Request timeout encompasses the BackendRequest timeout, the value of 310 // BackendRequest must be <= the value of Request timeout. 311 // 312 // Support: Extended 313 // 314 // +optional 315 BackendRequest *Duration `json:"backendRequest,omitempty"` 316 } 317 318 // PathMatchType specifies the semantics of how HTTP paths should be compared. 319 // Valid PathMatchType values, along with their support levels, are: 320 // 321 // * "Exact" - Core 322 // * "PathPrefix" - Core 323 // * "RegularExpression" - Implementation Specific 324 // 325 // PathPrefix and Exact paths must be syntactically valid: 326 // 327 // - Must begin with the `/` character 328 // - Must not contain consecutive `/` characters (e.g. `/foo///`, `//`). 329 // 330 // Note that values may be added to this enum, implementations 331 // must ensure that unknown values will not cause a crash. 332 // 333 // Unknown values here must result in the implementation setting the 334 // Accepted Condition for the Route to `status: False`, with a 335 // Reason of `UnsupportedValue`. 336 // 337 // +kubebuilder:validation:Enum=Exact;PathPrefix;RegularExpression 338 type PathMatchType string 339 340 const ( 341 // Matches the URL path exactly and with case sensitivity. This means that 342 // an exact path match on `/abc` will only match requests to `/abc`, NOT 343 // `/abc/`, `/Abc`, or `/abcd`. 344 PathMatchExact PathMatchType = "Exact" 345 346 // Matches based on a URL path prefix split by `/`. Matching is 347 // case sensitive and done on a path element by element basis. A 348 // path element refers to the list of labels in the path split by 349 // the `/` separator. When specified, a trailing `/` is ignored. 350 // 351 // For example, the paths `/abc`, `/abc/`, and `/abc/def` would all match 352 // the prefix `/abc`, but the path `/abcd` would not. 353 // 354 // "PathPrefix" is semantically equivalent to the "Prefix" path type in the 355 // Kubernetes Ingress API. 356 PathMatchPathPrefix PathMatchType = "PathPrefix" 357 358 // Matches if the URL path matches the given regular expression with 359 // case sensitivity. 360 // 361 // Since `"RegularExpression"` has implementation-specific conformance, 362 // implementations can support POSIX, PCRE, RE2 or any other regular expression 363 // dialect. 364 // Please read the implementation's documentation to determine the supported 365 // dialect. 366 PathMatchRegularExpression PathMatchType = "RegularExpression" 367 ) 368 369 // HTTPPathMatch describes how to select a HTTP route by matching the HTTP request path. 370 // 371 // +kubebuilder:validation:XValidation:message="value must be an absolute path and start with '/' when type one of ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? self.value.startsWith('/') : true" 372 // +kubebuilder:validation:XValidation:message="must not contain '//' when type one of ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? !self.value.contains('//') : true" 373 // +kubebuilder:validation:XValidation:message="must not contain '/./' when type one of ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? !self.value.contains('/./') : true" 374 // +kubebuilder:validation:XValidation:message="must not contain '/../' when type one of ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? !self.value.contains('/../') : true" 375 // +kubebuilder:validation:XValidation:message="must not contain '%2f' when type one of ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? !self.value.contains('%2f') : true" 376 // +kubebuilder:validation:XValidation:message="must not contain '%2F' when type one of ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? !self.value.contains('%2F') : true" 377 // +kubebuilder:validation:XValidation:message="must not contain '#' when type one of ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? !self.value.contains('#') : true" 378 // +kubebuilder:validation:XValidation:message="must not end with '/..' when type one of ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? !self.value.endsWith('/..') : true" 379 // +kubebuilder:validation:XValidation:message="must not end with '/.' when type one of ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? !self.value.endsWith('/.') : true" 380 // +kubebuilder:validation:XValidation:message="type must be one of ['Exact', 'PathPrefix', 'RegularExpression']",rule="self.type in ['Exact','PathPrefix'] || self.type == 'RegularExpression'" 381 // +kubebuilder:validation:XValidation:message="must only contain valid characters (matching ^(?:[-A-Za-z0-9/._~!$&'()*+,;=:@]|[%][0-9a-fA-F]{2})+$) for types ['Exact', 'PathPrefix']",rule="(self.type in ['Exact','PathPrefix']) ? self.value.matches(r\"\"\"^(?:[-A-Za-z0-9/._~!$&'()*+,;=:@]|[%][0-9a-fA-F]{2})+$\"\"\") : true" 382 type HTTPPathMatch struct { 383 // Type specifies how to match against the path Value. 384 // 385 // Support: Core (Exact, PathPrefix) 386 // 387 // Support: Implementation-specific (RegularExpression) 388 // 389 // +optional 390 // +kubebuilder:default=PathPrefix 391 Type *PathMatchType `json:"type,omitempty"` 392 393 // Value of the HTTP path to match against. 394 // 395 // +optional 396 // +kubebuilder:default="/" 397 // +kubebuilder:validation:MaxLength=1024 398 Value *string `json:"value,omitempty"` 399 } 400 401 // HeaderMatchType specifies the semantics of how HTTP header values should be 402 // compared. Valid HeaderMatchType values, along with their conformance levels, are: 403 // 404 // * "Exact" - Core 405 // * "RegularExpression" - Implementation Specific 406 // 407 // Note that values may be added to this enum, implementations 408 // must ensure that unknown values will not cause a crash. 409 // 410 // Unknown values here must result in the implementation setting the 411 // Accepted Condition for the Route to `status: False`, with a 412 // Reason of `UnsupportedValue`. 413 // 414 // +kubebuilder:validation:Enum=Exact;RegularExpression 415 type HeaderMatchType string 416 417 // HeaderMatchType constants. 418 const ( 419 HeaderMatchExact HeaderMatchType = "Exact" 420 HeaderMatchRegularExpression HeaderMatchType = "RegularExpression" 421 ) 422 423 // HTTPHeaderName is the name of an HTTP header. 424 // 425 // Valid values include: 426 // 427 // * "Authorization" 428 // * "Set-Cookie" 429 // 430 // Invalid values include: 431 // 432 // - ":method" - ":" is an invalid character. This means that HTTP/2 pseudo 433 // headers are not currently supported by this type. 434 // - "/invalid" - "/ " is an invalid character 435 type HTTPHeaderName HeaderName 436 437 // HTTPHeaderMatch describes how to select a HTTP route by matching HTTP request 438 // headers. 439 type HTTPHeaderMatch struct { 440 // Type specifies how to match against the value of the header. 441 // 442 // Support: Core (Exact) 443 // 444 // Support: Implementation-specific (RegularExpression) 445 // 446 // Since RegularExpression HeaderMatchType has implementation-specific 447 // conformance, implementations can support POSIX, PCRE or any other dialects 448 // of regular expressions. Please read the implementation's documentation to 449 // determine the supported dialect. 450 // 451 // +optional 452 // +kubebuilder:default=Exact 453 Type *HeaderMatchType `json:"type,omitempty"` 454 455 // Name is the name of the HTTP Header to be matched. Name matching MUST be 456 // case insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). 457 // 458 // If multiple entries specify equivalent header names, only the first 459 // entry with an equivalent name MUST be considered for a match. Subsequent 460 // entries with an equivalent header name MUST be ignored. Due to the 461 // case-insensitivity of header names, "foo" and "Foo" are considered 462 // equivalent. 463 // 464 // When a header is repeated in an HTTP request, it is 465 // implementation-specific behavior as to how this is represented. 466 // Generally, proxies should follow the guidance from the RFC: 467 // https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2.2 regarding 468 // processing a repeated header, with special handling for "Set-Cookie". 469 Name HTTPHeaderName `json:"name"` 470 471 // Value is the value of HTTP Header to be matched. 472 // 473 // +kubebuilder:validation:MinLength=1 474 // +kubebuilder:validation:MaxLength=4096 475 Value string `json:"value"` 476 } 477 478 // QueryParamMatchType specifies the semantics of how HTTP query parameter 479 // values should be compared. Valid QueryParamMatchType values, along with their 480 // conformance levels, are: 481 // 482 // * "Exact" - Core 483 // * "RegularExpression" - Implementation Specific 484 // 485 // Note that values may be added to this enum, implementations 486 // must ensure that unknown values will not cause a crash. 487 // 488 // Unknown values here must result in the implementation setting the 489 // Accepted Condition for the Route to `status: False`, with a 490 // Reason of `UnsupportedValue`. 491 // 492 // +kubebuilder:validation:Enum=Exact;RegularExpression 493 type QueryParamMatchType string 494 495 // QueryParamMatchType constants. 496 const ( 497 QueryParamMatchExact QueryParamMatchType = "Exact" 498 QueryParamMatchRegularExpression QueryParamMatchType = "RegularExpression" 499 ) 500 501 // HTTPQueryParamMatch describes how to select a HTTP route by matching HTTP 502 // query parameters. 503 type HTTPQueryParamMatch struct { 504 // Type specifies how to match against the value of the query parameter. 505 // 506 // Support: Extended (Exact) 507 // 508 // Support: Implementation-specific (RegularExpression) 509 // 510 // Since RegularExpression QueryParamMatchType has Implementation-specific 511 // conformance, implementations can support POSIX, PCRE or any other 512 // dialects of regular expressions. Please read the implementation's 513 // documentation to determine the supported dialect. 514 // 515 // +optional 516 // +kubebuilder:default=Exact 517 Type *QueryParamMatchType `json:"type,omitempty"` 518 519 // Name is the name of the HTTP query param to be matched. This must be an 520 // exact string match. (See 521 // https://tools.ietf.org/html/rfc7230#section-2.7.3). 522 // 523 // If multiple entries specify equivalent query param names, only the first 524 // entry with an equivalent name MUST be considered for a match. Subsequent 525 // entries with an equivalent query param name MUST be ignored. 526 // 527 // If a query param is repeated in an HTTP request, the behavior is 528 // purposely left undefined, since different data planes have different 529 // capabilities. However, it is *recommended* that implementations should 530 // match against the first value of the param if the data plane supports it, 531 // as this behavior is expected in other load balancing contexts outside of 532 // the Gateway API. 533 // 534 // Users SHOULD NOT route traffic based on repeated query params to guard 535 // themselves against potential differences in the implementations. 536 Name HTTPHeaderName `json:"name"` 537 538 // Value is the value of HTTP query param to be matched. 539 // 540 // +kubebuilder:validation:MinLength=1 541 // +kubebuilder:validation:MaxLength=1024 542 Value string `json:"value"` 543 } 544 545 // HTTPMethod describes how to select a HTTP route by matching the HTTP 546 // method as defined by 547 // [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-4) and 548 // [RFC 5789](https://datatracker.ietf.org/doc/html/rfc5789#section-2). 549 // The value is expected in upper case. 550 // 551 // Note that values may be added to this enum, implementations 552 // must ensure that unknown values will not cause a crash. 553 // 554 // Unknown values here must result in the implementation setting the 555 // Accepted Condition for the Route to `status: False`, with a 556 // Reason of `UnsupportedValue`. 557 // 558 // +kubebuilder:validation:Enum=GET;HEAD;POST;PUT;DELETE;CONNECT;OPTIONS;TRACE;PATCH 559 type HTTPMethod string 560 561 const ( 562 HTTPMethodGet HTTPMethod = "GET" 563 HTTPMethodHead HTTPMethod = "HEAD" 564 HTTPMethodPost HTTPMethod = "POST" 565 HTTPMethodPut HTTPMethod = "PUT" 566 HTTPMethodDelete HTTPMethod = "DELETE" 567 HTTPMethodConnect HTTPMethod = "CONNECT" 568 HTTPMethodOptions HTTPMethod = "OPTIONS" 569 HTTPMethodTrace HTTPMethod = "TRACE" 570 HTTPMethodPatch HTTPMethod = "PATCH" 571 ) 572 573 // HTTPRouteMatch defines the predicate used to match requests to a given 574 // action. Multiple match types are ANDed together, i.e. the match will 575 // evaluate to true only if all conditions are satisfied. 576 // 577 // For example, the match below will match a HTTP request only if its path 578 // starts with `/foo` AND it contains the `version: v1` header: 579 // 580 // ``` 581 // match: 582 // 583 // path: 584 // value: "/foo" 585 // headers: 586 // - name: "version" 587 // value "v1" 588 // 589 // ``` 590 type HTTPRouteMatch struct { 591 // Path specifies a HTTP request path matcher. If this field is not 592 // specified, a default prefix match on the "/" path is provided. 593 // 594 // +optional 595 // +kubebuilder:default={type: "PathPrefix", value: "/"} 596 Path *HTTPPathMatch `json:"path,omitempty"` 597 598 // Headers specifies HTTP request header matchers. Multiple match values are 599 // ANDed together, meaning, a request must match all the specified headers 600 // to select the route. 601 // 602 // +listType=map 603 // +listMapKey=name 604 // +optional 605 // +kubebuilder:validation:MaxItems=16 606 Headers []HTTPHeaderMatch `json:"headers,omitempty"` 607 608 // QueryParams specifies HTTP query parameter matchers. Multiple match 609 // values are ANDed together, meaning, a request must match all the 610 // specified query parameters to select the route. 611 // 612 // Support: Extended 613 // 614 // +listType=map 615 // +listMapKey=name 616 // +optional 617 // +kubebuilder:validation:MaxItems=16 618 QueryParams []HTTPQueryParamMatch `json:"queryParams,omitempty"` 619 620 // Method specifies HTTP method matcher. 621 // When specified, this route will be matched only if the request has the 622 // specified method. 623 // 624 // Support: Extended 625 // 626 // +optional 627 Method *HTTPMethod `json:"method,omitempty"` 628 } 629 630 // HTTPRouteFilter defines processing steps that must be completed during the 631 // request or response lifecycle. HTTPRouteFilters are meant as an extension 632 // point to express processing that may be done in Gateway implementations. Some 633 // examples include request or response modification, implementing 634 // authentication strategies, rate-limiting, and traffic shaping. API 635 // guarantee/conformance is defined based on the type of the filter. 636 // 637 // +kubebuilder:validation:XValidation:message="filter.requestHeaderModifier must be nil if the filter.type is not RequestHeaderModifier",rule="!(has(self.requestHeaderModifier) && self.type != 'RequestHeaderModifier')" 638 // +kubebuilder:validation:XValidation:message="filter.requestHeaderModifier must be specified for RequestHeaderModifier filter.type",rule="!(!has(self.requestHeaderModifier) && self.type == 'RequestHeaderModifier')" 639 // +kubebuilder:validation:XValidation:message="filter.responseHeaderModifier must be nil if the filter.type is not ResponseHeaderModifier",rule="!(has(self.responseHeaderModifier) && self.type != 'ResponseHeaderModifier')" 640 // +kubebuilder:validation:XValidation:message="filter.responseHeaderModifier must be specified for ResponseHeaderModifier filter.type",rule="!(!has(self.responseHeaderModifier) && self.type == 'ResponseHeaderModifier')" 641 // +kubebuilder:validation:XValidation:message="filter.requestMirror must be nil if the filter.type is not RequestMirror",rule="!(has(self.requestMirror) && self.type != 'RequestMirror')" 642 // +kubebuilder:validation:XValidation:message="filter.requestMirror must be specified for RequestMirror filter.type",rule="!(!has(self.requestMirror) && self.type == 'RequestMirror')" 643 // +kubebuilder:validation:XValidation:message="filter.requestRedirect must be nil if the filter.type is not RequestRedirect",rule="!(has(self.requestRedirect) && self.type != 'RequestRedirect')" 644 // +kubebuilder:validation:XValidation:message="filter.requestRedirect must be specified for RequestRedirect filter.type",rule="!(!has(self.requestRedirect) && self.type == 'RequestRedirect')" 645 // +kubebuilder:validation:XValidation:message="filter.urlRewrite must be nil if the filter.type is not URLRewrite",rule="!(has(self.urlRewrite) && self.type != 'URLRewrite')" 646 // +kubebuilder:validation:XValidation:message="filter.urlRewrite must be specified for URLRewrite filter.type",rule="!(!has(self.urlRewrite) && self.type == 'URLRewrite')" 647 // +kubebuilder:validation:XValidation:message="filter.extensionRef must be nil if the filter.type is not ExtensionRef",rule="!(has(self.extensionRef) && self.type != 'ExtensionRef')" 648 // +kubebuilder:validation:XValidation:message="filter.extensionRef must be specified for ExtensionRef filter.type",rule="!(!has(self.extensionRef) && self.type == 'ExtensionRef')" 649 type HTTPRouteFilter struct { 650 // Type identifies the type of filter to apply. As with other API fields, 651 // types are classified into three conformance levels: 652 // 653 // - Core: Filter types and their corresponding configuration defined by 654 // "Support: Core" in this package, e.g. "RequestHeaderModifier". All 655 // implementations must support core filters. 656 // 657 // - Extended: Filter types and their corresponding configuration defined by 658 // "Support: Extended" in this package, e.g. "RequestMirror". Implementers 659 // are encouraged to support extended filters. 660 // 661 // - Implementation-specific: Filters that are defined and supported by 662 // specific vendors. 663 // In the future, filters showing convergence in behavior across multiple 664 // implementations will be considered for inclusion in extended or core 665 // conformance levels. Filter-specific configuration for such filters 666 // is specified using the ExtensionRef field. `Type` should be set to 667 // "ExtensionRef" for custom filters. 668 // 669 // Implementers are encouraged to define custom implementation types to 670 // extend the core API with implementation-specific behavior. 671 // 672 // If a reference to a custom filter type cannot be resolved, the filter 673 // MUST NOT be skipped. Instead, requests that would have been processed by 674 // that filter MUST receive a HTTP error response. 675 // 676 // Note that values may be added to this enum, implementations 677 // must ensure that unknown values will not cause a crash. 678 // 679 // Unknown values here must result in the implementation setting the 680 // Accepted Condition for the Route to `status: False`, with a 681 // Reason of `UnsupportedValue`. 682 // 683 // +unionDiscriminator 684 // +kubebuilder:validation:Enum=RequestHeaderModifier;ResponseHeaderModifier;RequestMirror;RequestRedirect;URLRewrite;ExtensionRef 685 Type HTTPRouteFilterType `json:"type"` 686 687 // RequestHeaderModifier defines a schema for a filter that modifies request 688 // headers. 689 // 690 // Support: Core 691 // 692 // +optional 693 RequestHeaderModifier *HTTPHeaderFilter `json:"requestHeaderModifier,omitempty"` 694 695 // ResponseHeaderModifier defines a schema for a filter that modifies response 696 // headers. 697 // 698 // Support: Extended 699 // 700 // +optional 701 ResponseHeaderModifier *HTTPHeaderFilter `json:"responseHeaderModifier,omitempty"` 702 703 // RequestMirror defines a schema for a filter that mirrors requests. 704 // Requests are sent to the specified destination, but responses from 705 // that destination are ignored. 706 // 707 // This filter can be used multiple times within the same rule. Note that 708 // not all implementations will be able to support mirroring to multiple 709 // backends. 710 // 711 // Support: Extended 712 // 713 // +optional 714 RequestMirror *HTTPRequestMirrorFilter `json:"requestMirror,omitempty"` 715 716 // RequestRedirect defines a schema for a filter that responds to the 717 // request with an HTTP redirection. 718 // 719 // Support: Core 720 // 721 // +optional 722 RequestRedirect *HTTPRequestRedirectFilter `json:"requestRedirect,omitempty"` 723 724 // URLRewrite defines a schema for a filter that modifies a request during forwarding. 725 // 726 // Support: Extended 727 // 728 // +optional 729 URLRewrite *HTTPURLRewriteFilter `json:"urlRewrite,omitempty"` 730 731 // ExtensionRef is an optional, implementation-specific extension to the 732 // "filter" behavior. For example, resource "myroutefilter" in group 733 // "networking.example.net"). ExtensionRef MUST NOT be used for core and 734 // extended filters. 735 // 736 // This filter can be used multiple times within the same rule. 737 // 738 // Support: Implementation-specific 739 // 740 // +optional 741 ExtensionRef *LocalObjectReference `json:"extensionRef,omitempty"` 742 } 743 744 // HTTPRouteFilterType identifies a type of HTTPRoute filter. 745 type HTTPRouteFilterType string 746 747 const ( 748 // HTTPRouteFilterRequestHeaderModifier can be used to add or remove an HTTP 749 // header from an HTTP request before it is sent to the upstream target. 750 // 751 // Support in HTTPRouteRule: Core 752 // 753 // Support in HTTPBackendRef: Extended 754 HTTPRouteFilterRequestHeaderModifier HTTPRouteFilterType = "RequestHeaderModifier" 755 756 // HTTPRouteFilterResponseHeaderModifier can be used to add or remove an HTTP 757 // header from an HTTP response before it is sent to the client. 758 // 759 // Support in HTTPRouteRule: Extended 760 // 761 // Support in HTTPBackendRef: Extended 762 HTTPRouteFilterResponseHeaderModifier HTTPRouteFilterType = "ResponseHeaderModifier" 763 764 // HTTPRouteFilterRequestRedirect can be used to redirect a request to 765 // another location. This filter can also be used for HTTP to HTTPS 766 // redirects. This may not be used on the same Route rule or BackendRef as a 767 // URLRewrite filter. 768 // 769 // Support in HTTPRouteRule: Core 770 // 771 // Support in HTTPBackendRef: Extended 772 HTTPRouteFilterRequestRedirect HTTPRouteFilterType = "RequestRedirect" 773 774 // HTTPRouteFilterURLRewrite can be used to modify a request during 775 // forwarding. At most one of these filters may be used on a Route rule. 776 // This may not be used on the same Route rule or BackendRef as a 777 // RequestRedirect filter. 778 // 779 // Support in HTTPRouteRule: Extended 780 // 781 // Support in HTTPBackendRef: Extended 782 HTTPRouteFilterURLRewrite HTTPRouteFilterType = "URLRewrite" 783 784 // HTTPRouteFilterRequestMirror can be used to mirror HTTP requests to a 785 // different backend. The responses from this backend MUST be ignored by 786 // the Gateway. 787 // 788 // Support in HTTPRouteRule: Extended 789 // 790 // Support in HTTPBackendRef: Extended 791 HTTPRouteFilterRequestMirror HTTPRouteFilterType = "RequestMirror" 792 793 // HTTPRouteFilterExtensionRef should be used for configuring custom 794 // HTTP filters. 795 // 796 // Support in HTTPRouteRule: Implementation-specific 797 // 798 // Support in HTTPBackendRef: Implementation-specific 799 HTTPRouteFilterExtensionRef HTTPRouteFilterType = "ExtensionRef" 800 ) 801 802 // HTTPHeader represents an HTTP Header name and value as defined by RFC 7230. 803 type HTTPHeader struct { 804 // Name is the name of the HTTP Header to be matched. Name matching MUST be 805 // case insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). 806 // 807 // If multiple entries specify equivalent header names, the first entry with 808 // an equivalent name MUST be considered for a match. Subsequent entries 809 // with an equivalent header name MUST be ignored. Due to the 810 // case-insensitivity of header names, "foo" and "Foo" are considered 811 // equivalent. 812 Name HTTPHeaderName `json:"name"` 813 814 // Value is the value of HTTP Header to be matched. 815 // 816 // +kubebuilder:validation:MinLength=1 817 // +kubebuilder:validation:MaxLength=4096 818 Value string `json:"value"` 819 } 820 821 // HTTPHeaderFilter defines a filter that modifies the headers of an HTTP 822 // request or response. Only one action for a given header name is permitted. 823 // Filters specifying multiple actions of the same or different type for any one 824 // header name are invalid and will be rejected by the webhook if installed. 825 // Configuration to set or add multiple values for a header must use RFC 7230 826 // header value formatting, separating each value with a comma. 827 type HTTPHeaderFilter struct { 828 // Set overwrites the request with the given header (name, value) 829 // before the action. 830 // 831 // Input: 832 // GET /foo HTTP/1.1 833 // my-header: foo 834 // 835 // Config: 836 // set: 837 // - name: "my-header" 838 // value: "bar" 839 // 840 // Output: 841 // GET /foo HTTP/1.1 842 // my-header: bar 843 // 844 // +optional 845 // +listType=map 846 // +listMapKey=name 847 // +kubebuilder:validation:MaxItems=16 848 Set []HTTPHeader `json:"set,omitempty"` 849 850 // Add adds the given header(s) (name, value) to the request 851 // before the action. It appends to any existing values associated 852 // with the header name. 853 // 854 // Input: 855 // GET /foo HTTP/1.1 856 // my-header: foo 857 // 858 // Config: 859 // add: 860 // - name: "my-header" 861 // value: "bar,baz" 862 // 863 // Output: 864 // GET /foo HTTP/1.1 865 // my-header: foo,bar,baz 866 // 867 // +optional 868 // +listType=map 869 // +listMapKey=name 870 // +kubebuilder:validation:MaxItems=16 871 Add []HTTPHeader `json:"add,omitempty"` 872 873 // Remove the given header(s) from the HTTP request before the action. The 874 // value of Remove is a list of HTTP header names. Note that the header 875 // names are case-insensitive (see 876 // https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). 877 // 878 // Input: 879 // GET /foo HTTP/1.1 880 // my-header1: foo 881 // my-header2: bar 882 // my-header3: baz 883 // 884 // Config: 885 // remove: ["my-header1", "my-header3"] 886 // 887 // Output: 888 // GET /foo HTTP/1.1 889 // my-header2: bar 890 // 891 // +optional 892 // +listType=set 893 // +kubebuilder:validation:MaxItems=16 894 Remove []string `json:"remove,omitempty"` 895 } 896 897 // HTTPPathModifierType defines the type of path redirect or rewrite. 898 type HTTPPathModifierType string 899 900 const ( 901 // This type of modifier indicates that the full path will be replaced 902 // by the specified value. 903 FullPathHTTPPathModifier HTTPPathModifierType = "ReplaceFullPath" 904 905 // This type of modifier indicates that any prefix path matches will be 906 // replaced by the substitution value. For example, a path with a prefix 907 // match of "/foo" and a ReplacePrefixMatch substitution of "/bar" will have 908 // the "/foo" prefix replaced with "/bar" in matching requests. 909 // 910 // Note that this matches the behavior of the PathPrefix match type. This 911 // matches full path elements. A path element refers to the list of labels 912 // in the path split by the `/` separator. When specified, a trailing `/` is 913 // ignored. For example, the paths `/abc`, `/abc/`, and `/abc/def` would all 914 // match the prefix `/abc`, but the path `/abcd` would not. 915 PrefixMatchHTTPPathModifier HTTPPathModifierType = "ReplacePrefixMatch" 916 ) 917 918 // HTTPPathModifier defines configuration for path modifiers. 919 // 920 // +kubebuilder:validation:XValidation:message="replaceFullPath must be specified when type is set to 'ReplaceFullPath'",rule="self.type == 'ReplaceFullPath' ? has(self.replaceFullPath) : true" 921 // +kubebuilder:validation:XValidation:message="type must be 'ReplaceFullPath' when replaceFullPath is set",rule="has(self.replaceFullPath) ? self.type == 'ReplaceFullPath' : true" 922 // +kubebuilder:validation:XValidation:message="replacePrefixMatch must be specified when type is set to 'ReplacePrefixMatch'",rule="self.type == 'ReplacePrefixMatch' ? has(self.replacePrefixMatch) : true" 923 // +kubebuilder:validation:XValidation:message="type must be 'ReplacePrefixMatch' when replacePrefixMatch is set",rule="has(self.replacePrefixMatch) ? self.type == 'ReplacePrefixMatch' : true" 924 type HTTPPathModifier struct { 925 // Type defines the type of path modifier. Additional types may be 926 // added in a future release of the API. 927 // 928 // Note that values may be added to this enum, implementations 929 // must ensure that unknown values will not cause a crash. 930 // 931 // Unknown values here must result in the implementation setting the 932 // Accepted Condition for the Route to `status: False`, with a 933 // Reason of `UnsupportedValue`. 934 // 935 // +kubebuilder:validation:Enum=ReplaceFullPath;ReplacePrefixMatch 936 Type HTTPPathModifierType `json:"type"` 937 938 // ReplaceFullPath specifies the value with which to replace the full path 939 // of a request during a rewrite or redirect. 940 // 941 // +kubebuilder:validation:MaxLength=1024 942 // +optional 943 ReplaceFullPath *string `json:"replaceFullPath,omitempty"` 944 945 // ReplacePrefixMatch specifies the value with which to replace the prefix 946 // match of a request during a rewrite or redirect. For example, a request 947 // to "/foo/bar" with a prefix match of "/foo" and a ReplacePrefixMatch 948 // of "/xyz" would be modified to "/xyz/bar". 949 // 950 // Note that this matches the behavior of the PathPrefix match type. This 951 // matches full path elements. A path element refers to the list of labels 952 // in the path split by the `/` separator. When specified, a trailing `/` is 953 // ignored. For example, the paths `/abc`, `/abc/`, and `/abc/def` would all 954 // match the prefix `/abc`, but the path `/abcd` would not. 955 // 956 // ReplacePrefixMatch is only compatible with a `PathPrefix` HTTPRouteMatch. 957 // Using any other HTTPRouteMatch type on the same HTTPRouteRule will result in 958 // the implementation setting the Accepted Condition for the Route to `status: False`. 959 // 960 // Request Path | Prefix Match | Replace Prefix | Modified Path 961 // -------------|--------------|----------------|---------- 962 // /foo/bar | /foo | /xyz | /xyz/bar 963 // /foo/bar | /foo | /xyz/ | /xyz/bar 964 // /foo/bar | /foo/ | /xyz | /xyz/bar 965 // /foo/bar | /foo/ | /xyz/ | /xyz/bar 966 // /foo | /foo | /xyz | /xyz 967 // /foo/ | /foo | /xyz | /xyz/ 968 // /foo/bar | /foo | <empty string> | /bar 969 // /foo/ | /foo | <empty string> | / 970 // /foo | /foo | <empty string> | / 971 // /foo/ | /foo | / | / 972 // /foo | /foo | / | / 973 // 974 // +kubebuilder:validation:MaxLength=1024 975 // +optional 976 ReplacePrefixMatch *string `json:"replacePrefixMatch,omitempty"` 977 } 978 979 // HTTPRequestRedirect defines a filter that redirects a request. This filter 980 // MUST NOT be used on the same Route rule as a HTTPURLRewrite filter. 981 type HTTPRequestRedirectFilter struct { 982 // Scheme is the scheme to be used in the value of the `Location` header in 983 // the response. When empty, the scheme of the request is used. 984 // 985 // Scheme redirects can affect the port of the redirect, for more information, 986 // refer to the documentation for the port field of this filter. 987 // 988 // Note that values may be added to this enum, implementations 989 // must ensure that unknown values will not cause a crash. 990 // 991 // Unknown values here must result in the implementation setting the 992 // Accepted Condition for the Route to `status: False`, with a 993 // Reason of `UnsupportedValue`. 994 // 995 // Support: Extended 996 // 997 // +optional 998 // +kubebuilder:validation:Enum=http;https 999 Scheme *string `json:"scheme,omitempty"` 1000 1001 // Hostname is the hostname to be used in the value of the `Location` 1002 // header in the response. 1003 // When empty, the hostname in the `Host` header of the request is used. 1004 // 1005 // Support: Core 1006 // 1007 // +optional 1008 Hostname *PreciseHostname `json:"hostname,omitempty"` 1009 1010 // Path defines parameters used to modify the path of the incoming request. 1011 // The modified path is then used to construct the `Location` header. When 1012 // empty, the request path is used as-is. 1013 // 1014 // Support: Extended 1015 // 1016 // +optional 1017 Path *HTTPPathModifier `json:"path,omitempty"` 1018 1019 // Port is the port to be used in the value of the `Location` 1020 // header in the response. 1021 // 1022 // If no port is specified, the redirect port MUST be derived using the 1023 // following rules: 1024 // 1025 // * If redirect scheme is not-empty, the redirect port MUST be the well-known 1026 // port associated with the redirect scheme. Specifically "http" to port 80 1027 // and "https" to port 443. If the redirect scheme does not have a 1028 // well-known port, the listener port of the Gateway SHOULD be used. 1029 // * If redirect scheme is empty, the redirect port MUST be the Gateway 1030 // Listener port. 1031 // 1032 // Implementations SHOULD NOT add the port number in the 'Location' 1033 // header in the following cases: 1034 // 1035 // * A Location header that will use HTTP (whether that is determined via 1036 // the Listener protocol or the Scheme field) _and_ use port 80. 1037 // * A Location header that will use HTTPS (whether that is determined via 1038 // the Listener protocol or the Scheme field) _and_ use port 443. 1039 // 1040 // Support: Extended 1041 // 1042 // +optional 1043 Port *PortNumber `json:"port,omitempty"` 1044 1045 // StatusCode is the HTTP status code to be used in response. 1046 // 1047 // Note that values may be added to this enum, implementations 1048 // must ensure that unknown values will not cause a crash. 1049 // 1050 // Unknown values here must result in the implementation setting the 1051 // Accepted Condition for the Route to `status: False`, with a 1052 // Reason of `UnsupportedValue`. 1053 // 1054 // Support: Core 1055 // 1056 // +optional 1057 // +kubebuilder:default=302 1058 // +kubebuilder:validation:Enum=301;302 1059 StatusCode *int `json:"statusCode,omitempty"` 1060 } 1061 1062 // HTTPURLRewriteFilter defines a filter that modifies a request during 1063 // forwarding. At most one of these filters may be used on a Route rule. This 1064 // MUST NOT be used on the same Route rule as a HTTPRequestRedirect filter. 1065 // 1066 // Support: Extended 1067 type HTTPURLRewriteFilter struct { 1068 // Hostname is the value to be used to replace the Host header value during 1069 // forwarding. 1070 // 1071 // Support: Extended 1072 // 1073 // +optional 1074 Hostname *PreciseHostname `json:"hostname,omitempty"` 1075 1076 // Path defines a path rewrite. 1077 // 1078 // Support: Extended 1079 // 1080 // +optional 1081 Path *HTTPPathModifier `json:"path,omitempty"` 1082 } 1083 1084 // HTTPRequestMirrorFilter defines configuration for the RequestMirror filter. 1085 type HTTPRequestMirrorFilter struct { 1086 // BackendRef references a resource where mirrored requests are sent. 1087 // 1088 // Mirrored requests must be sent only to a single destination endpoint 1089 // within this BackendRef, irrespective of how many endpoints are present 1090 // within this BackendRef. 1091 // 1092 // If the referent cannot be found, this BackendRef is invalid and must be 1093 // dropped from the Gateway. The controller must ensure the "ResolvedRefs" 1094 // condition on the Route status is set to `status: False` and not configure 1095 // this backend in the underlying implementation. 1096 // 1097 // If there is a cross-namespace reference to an *existing* object 1098 // that is not allowed by a ReferenceGrant, the controller must ensure the 1099 // "ResolvedRefs" condition on the Route is set to `status: False`, 1100 // with the "RefNotPermitted" reason and not configure this backend in the 1101 // underlying implementation. 1102 // 1103 // In either error case, the Message of the `ResolvedRefs` Condition 1104 // should be used to provide more detail about the problem. 1105 // 1106 // Support: Extended for Kubernetes Service 1107 // 1108 // Support: Implementation-specific for any other resource 1109 BackendRef BackendObjectReference `json:"backendRef"` 1110 } 1111 1112 // HTTPBackendRef defines how a HTTPRoute forwards a HTTP request. 1113 // 1114 // Note that when a namespace different than the local namespace is specified, a 1115 // ReferenceGrant object is required in the referent namespace to allow that 1116 // namespace's owner to accept the reference. See the ReferenceGrant 1117 // documentation for details. 1118 // 1119 // <gateway:experimental:description> 1120 // 1121 // When the BackendRef points to a Kubernetes Service, implementations SHOULD 1122 // honor the appProtocol field if it is set for the target Service Port. 1123 // 1124 // Implementations supporting appProtocol SHOULD recognize the Kubernetes 1125 // Standard Application Protocols defined in KEP-3726. 1126 // 1127 // If a Service appProtocol isn't specified, an implementation MAY infer the 1128 // backend protocol through its own means. Implementations MAY infer the 1129 // protocol from the Route type referring to the backend Service. 1130 // 1131 // If a Route is not able to send traffic to the backend using the specified 1132 // protocol then the backend is considered invalid. Implementations MUST set the 1133 // "ResolvedRefs" condition to "False" with the "UnsupportedProtocol" reason. 1134 // 1135 // </gateway:experimental:description> 1136 type HTTPBackendRef struct { 1137 // BackendRef is a reference to a backend to forward matched requests to. 1138 // 1139 // A BackendRef can be invalid for the following reasons. In all cases, the 1140 // implementation MUST ensure the `ResolvedRefs` Condition on the Route 1141 // is set to `status: False`, with a Reason and Message that indicate 1142 // what is the cause of the error. 1143 // 1144 // A BackendRef is invalid if: 1145 // 1146 // * It refers to an unknown or unsupported kind of resource. In this 1147 // case, the Reason must be set to `InvalidKind` and Message of the 1148 // Condition must explain which kind of resource is unknown or unsupported. 1149 // 1150 // * It refers to a resource that does not exist. In this case, the Reason must 1151 // be set to `BackendNotFound` and the Message of the Condition must explain 1152 // which resource does not exist. 1153 // 1154 // * It refers a resource in another namespace when the reference has not been 1155 // explicitly allowed by a ReferenceGrant (or equivalent concept). In this 1156 // case, the Reason must be set to `RefNotPermitted` and the Message of the 1157 // Condition must explain which cross-namespace reference is not allowed. 1158 // 1159 // * It refers to a Kubernetes Service that has an incompatible appProtocol 1160 // for the given Route type 1161 // 1162 // * The BackendTLSPolicy object is installed in the cluster, a BackendTLSPolicy 1163 // is present that refers to the Service, and the implementation is unable 1164 // to meet the requirement. At the time of writing, BackendTLSPolicy is 1165 // experimental, but once it becomes standard, this will become a MUST 1166 // requirement. 1167 // 1168 // Support: Core for Kubernetes Service 1169 // 1170 // Support: Implementation-specific for any other resource 1171 // 1172 // Support for weight: Core 1173 // 1174 // Support for Kubernetes Service appProtocol: Extended 1175 // 1176 // Support for BackendTLSPolicy: Experimental and ImplementationSpecific 1177 // 1178 // +optional 1179 BackendRef `json:",inline"` 1180 1181 // Filters defined at this level should be executed if and only if the 1182 // request is being forwarded to the backend defined here. 1183 // 1184 // Support: Implementation-specific (For broader support of filters, use the 1185 // Filters field in HTTPRouteRule.) 1186 // 1187 // +optional 1188 // +kubebuilder:validation:MaxItems=16 1189 // +kubebuilder:validation:XValidation:message="May specify either httpRouteFilterRequestRedirect or httpRouteFilterRequestRewrite, but not both",rule="!(self.exists(f, f.type == 'RequestRedirect') && self.exists(f, f.type == 'URLRewrite'))" 1190 // +kubebuilder:validation:XValidation:message="May specify either httpRouteFilterRequestRedirect or httpRouteFilterRequestRewrite, but not both",rule="!(self.exists(f, f.type == 'RequestRedirect') && self.exists(f, f.type == 'URLRewrite'))" 1191 // +kubebuilder:validation:XValidation:message="RequestHeaderModifier filter cannot be repeated",rule="self.filter(f, f.type == 'RequestHeaderModifier').size() <= 1" 1192 // +kubebuilder:validation:XValidation:message="ResponseHeaderModifier filter cannot be repeated",rule="self.filter(f, f.type == 'ResponseHeaderModifier').size() <= 1" 1193 // +kubebuilder:validation:XValidation:message="RequestRedirect filter cannot be repeated",rule="self.filter(f, f.type == 'RequestRedirect').size() <= 1" 1194 // +kubebuilder:validation:XValidation:message="URLRewrite filter cannot be repeated",rule="self.filter(f, f.type == 'URLRewrite').size() <= 1" 1195 Filters []HTTPRouteFilter `json:"filters,omitempty"` 1196 } 1197 1198 // HTTPRouteStatus defines the observed state of HTTPRoute. 1199 type HTTPRouteStatus struct { 1200 RouteStatus `json:",inline"` 1201 } 1202