diff --git a/apis/v1/grpcroute_types.go b/apis/v1/grpcroute_types.go index 0cae5e5020..74c595f7a4 100644 --- a/apis/v1/grpcroute_types.go +++ b/apis/v1/grpcroute_types.go @@ -165,7 +165,6 @@ type GRPCRouteRule struct { // // For example, take the following matches configuration: // - // ``` // matches: // - method: // service: foo.bar @@ -174,7 +173,6 @@ type GRPCRouteRule struct { // version: 2 // - method: // service: foo.bar.v2 - // ``` // // For a request to match against this rule, it MUST satisfy // EITHER of the two conditions: diff --git a/apis/v1/httproute_types.go b/apis/v1/httproute_types.go index 6131d70b7b..9dffe10174 100644 --- a/apis/v1/httproute_types.go +++ b/apis/v1/httproute_types.go @@ -147,7 +147,6 @@ type HTTPRouteRule struct { // // For example, take the following matches configuration: // - // ``` // matches: // - path: // value: "/foo" @@ -156,7 +155,6 @@ type HTTPRouteRule struct { // value: "v2" // - path: // value: "/v2/foo" - // ``` // // For a request to match against this rule, a request must satisfy // EITHER of the two conditions: diff --git a/config/crd/experimental/gateway.networking.k8s.io_grpcroutes.yaml b/config/crd/experimental/gateway.networking.k8s.io_grpcroutes.yaml index 8efb5867b7..6f2148a492 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_grpcroutes.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_grpcroutes.yaml @@ -1645,7 +1645,6 @@ spec: For example, take the following matches configuration: - ``` matches: - method: service: foo.bar @@ -1654,7 +1653,6 @@ spec: version: 2 - method: service: foo.bar.v2 - ``` For a request to match against this rule, it MUST satisfy EITHER of the two conditions: diff --git a/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml b/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml index 050ba3277d..0016131cf7 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml @@ -2774,7 +2774,6 @@ spec: For example, take the following matches configuration: - ``` matches: - path: value: "/foo" @@ -2783,7 +2782,6 @@ spec: value: "v2" - path: value: "/v2/foo" - ``` For a request to match against this rule, a request must satisfy EITHER of the two conditions: @@ -6400,7 +6398,6 @@ spec: For example, take the following matches configuration: - ``` matches: - path: value: "/foo" @@ -6409,7 +6406,6 @@ spec: value: "v2" - path: value: "/v2/foo" - ``` For a request to match against this rule, a request must satisfy EITHER of the two conditions: diff --git a/config/crd/standard/gateway.networking.k8s.io_grpcroutes.yaml b/config/crd/standard/gateway.networking.k8s.io_grpcroutes.yaml index 4f18905f6d..dab1d0852e 100644 --- a/config/crd/standard/gateway.networking.k8s.io_grpcroutes.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_grpcroutes.yaml @@ -1598,7 +1598,6 @@ spec: For example, take the following matches configuration: - ``` matches: - method: service: foo.bar @@ -1607,7 +1606,6 @@ spec: version: 2 - method: service: foo.bar.v2 - ``` For a request to match against this rule, it MUST satisfy EITHER of the two conditions: diff --git a/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml b/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml index a8df425088..8ff9ef8f3b 100644 --- a/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml @@ -2149,7 +2149,6 @@ spec: For example, take the following matches configuration: - ``` matches: - path: value: "/foo" @@ -2158,7 +2157,6 @@ spec: value: "v2" - path: value: "/v2/foo" - ``` For a request to match against this rule, a request must satisfy EITHER of the two conditions: @@ -4944,7 +4942,6 @@ spec: For example, take the following matches configuration: - ``` matches: - path: value: "/foo" @@ -4953,7 +4950,6 @@ spec: value: "v2" - path: value: "/v2/foo" - ``` For a request to match against this rule, a request must satisfy EITHER of the two conditions: diff --git a/pkg/generated/openapi/zz_generated.openapi.go b/pkg/generated/openapi/zz_generated.openapi.go index 9279b1767a..01bcac5c07 100644 --- a/pkg/generated/openapi/zz_generated.openapi.go +++ b/pkg/generated/openapi/zz_generated.openapi.go @@ -3416,7 +3416,7 @@ func schema_sigsk8sio_gateway_api_apis_v1_GRPCRouteRule(ref common.ReferenceCall }, "matches": { SchemaProps: spec.SchemaProps{ - Description: "Matches define conditions used for matching the rule against incoming gRPC requests. Each match is independent, i.e. this rule will be matched if **any** one of the matches is satisfied.\n\nFor example, take the following matches configuration:\n\n``` matches: - method:\n service: foo.bar\n headers:\n values:\n version: 2\n- method:\n service: foo.bar.v2\n```\n\nFor a request to match against this rule, it MUST satisfy EITHER of the two conditions:\n\n- service of foo.bar AND contains the header `version: 2` - service of foo.bar.v2\n\nSee the documentation for GRPCRouteMatch on how to specify multiple match conditions to be ANDed together.\n\nIf no matches are specified, the implementation MUST match every gRPC request.\n\nProxy or Load Balancer routing configuration generated from GRPCRoutes MUST prioritize rules based on the following criteria, continuing on ties. Merging MUST not be done between GRPCRoutes and HTTPRoutes. Precedence MUST be given to the rule with the largest number of:\n\n* Characters in a matching non-wildcard hostname. * Characters in a matching hostname. * Characters in a matching service. * Characters in a matching method. * Header matches.\n\nIf ties still exist across multiple Routes, matching precedence MUST be determined in order of the following criteria, continuing on ties:\n\n* The oldest Route based on creation timestamp. * The Route appearing first in alphabetical order by\n \"{namespace}/{name}\".\n\nIf ties still exist within the Route that has been given precedence, matching precedence MUST be granted to the first matching rule meeting the above criteria.", + Description: "Matches define conditions used for matching the rule against incoming gRPC requests. Each match is independent, i.e. this rule will be matched if **any** one of the matches is satisfied.\n\nFor example, take the following matches configuration:\n\nmatches: - method:\n service: foo.bar\n headers:\n values:\n version: 2\n- method:\n service: foo.bar.v2\n\nFor a request to match against this rule, it MUST satisfy EITHER of the two conditions:\n\n- service of foo.bar AND contains the header `version: 2` - service of foo.bar.v2\n\nSee the documentation for GRPCRouteMatch on how to specify multiple match conditions to be ANDed together.\n\nIf no matches are specified, the implementation MUST match every gRPC request.\n\nProxy or Load Balancer routing configuration generated from GRPCRoutes MUST prioritize rules based on the following criteria, continuing on ties. Merging MUST not be done between GRPCRoutes and HTTPRoutes. Precedence MUST be given to the rule with the largest number of:\n\n* Characters in a matching non-wildcard hostname. * Characters in a matching hostname. * Characters in a matching service. * Characters in a matching method. * Header matches.\n\nIf ties still exist across multiple Routes, matching precedence MUST be determined in order of the following criteria, continuing on ties:\n\n* The oldest Route based on creation timestamp. * The Route appearing first in alphabetical order by\n \"{namespace}/{name}\".\n\nIf ties still exist within the Route that has been given precedence, matching precedence MUST be granted to the first matching rule meeting the above criteria.", Type: []string{"array"}, Items: &spec.SchemaOrArray{ Schema: &spec.Schema{ @@ -4995,7 +4995,7 @@ func schema_sigsk8sio_gateway_api_apis_v1_HTTPRouteRule(ref common.ReferenceCall }, "matches": { SchemaProps: spec.SchemaProps{ - Description: "Matches define conditions used for matching the rule against incoming HTTP requests. Each match is independent, i.e. this rule will be matched if **any** one of the matches is satisfied.\n\nFor example, take the following matches configuration:\n\n``` matches: - path:\n value: \"/foo\"\n headers:\n - name: \"version\"\n value: \"v2\"\n- path:\n value: \"/v2/foo\"\n```\n\nFor a request to match against this rule, a request must satisfy EITHER of the two conditions:\n\n- path prefixed with `/foo` AND contains the header `version: v2` - path prefix of `/v2/foo`\n\nSee the documentation for HTTPRouteMatch on how to specify multiple match conditions that should be ANDed together.\n\nIf no matches are specified, the default is a prefix path match on \"/\", which has the effect of matching every HTTP request.\n\nProxy or Load Balancer routing configuration generated from HTTPRoutes MUST prioritize matches based on the following criteria, continuing on ties. Across all rules specified on applicable Routes, precedence must be given to the match having:\n\n* \"Exact\" path match. * \"Prefix\" path match with largest number of characters. * Method match. * Largest number of header matches. * Largest number of query param matches.\n\nNote: The precedence of RegularExpression path matches are implementation-specific.\n\nIf ties still exist across multiple Routes, matching precedence MUST be determined in order of the following criteria, continuing on ties:\n\n* The oldest Route based on creation timestamp. * The Route appearing first in alphabetical order by\n \"{namespace}/{name}\".\n\nIf ties still exist within an HTTPRoute, matching precedence MUST be granted to the FIRST matching rule (in list order) with a match meeting the above criteria.\n\nWhen no rules matching a request have been successfully attached to the parent a request is coming from, a HTTP 404 status code MUST be returned.", + Description: "Matches define conditions used for matching the rule against incoming HTTP requests. Each match is independent, i.e. this rule will be matched if **any** one of the matches is satisfied.\n\nFor example, take the following matches configuration:\n\nmatches: - path:\n value: \"/foo\"\n headers:\n - name: \"version\"\n value: \"v2\"\n- path:\n value: \"/v2/foo\"\n\nFor a request to match against this rule, a request must satisfy EITHER of the two conditions:\n\n- path prefixed with `/foo` AND contains the header `version: v2` - path prefix of `/v2/foo`\n\nSee the documentation for HTTPRouteMatch on how to specify multiple match conditions that should be ANDed together.\n\nIf no matches are specified, the default is a prefix path match on \"/\", which has the effect of matching every HTTP request.\n\nProxy or Load Balancer routing configuration generated from HTTPRoutes MUST prioritize matches based on the following criteria, continuing on ties. Across all rules specified on applicable Routes, precedence must be given to the match having:\n\n* \"Exact\" path match. * \"Prefix\" path match with largest number of characters. * Method match. * Largest number of header matches. * Largest number of query param matches.\n\nNote: The precedence of RegularExpression path matches are implementation-specific.\n\nIf ties still exist across multiple Routes, matching precedence MUST be determined in order of the following criteria, continuing on ties:\n\n* The oldest Route based on creation timestamp. * The Route appearing first in alphabetical order by\n \"{namespace}/{name}\".\n\nIf ties still exist within an HTTPRoute, matching precedence MUST be granted to the FIRST matching rule (in list order) with a match meeting the above criteria.\n\nWhen no rules matching a request have been successfully attached to the parent a request is coming from, a HTTP 404 status code MUST be returned.", Type: []string{"array"}, Items: &spec.SchemaOrArray{ Schema: &spec.Schema{ diff --git a/site-src/reference/specx.md b/site-src/reference/specx.md index d234d9750f..d2f6479918 100644 --- a/site-src/reference/specx.md +++ b/site-src/reference/specx.md @@ -16,6 +16,21 @@ API group. +#### AllowedRoutes + + + + + + + +_Appears in:_ +- [ListenerEntry](#listenerentry) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `namespaces` _[RouteNamespaces](#routenamespaces)_ | Namespaces indicates namespaces from which Routes may be attached to this
Listener. This is restricted to the namespace of this Gateway by default.

Support: Core | \{ from:Same \} | | +| `kinds` _[RouteGroupKind](#routegroupkind) array_ | Kinds specifies the groups and kinds of Routes that are allowed to bind
to this Gateway Listener. When unspecified or empty, the kinds of Routes
selected are determined using the Listener protocol.

A RouteGroupKind MUST correspond to kinds of Routes that are compatible
with the application protocol specified in the Listener's Protocol field.
If an implementation does not support or recognize this resource type, it
MUST set the "ResolvedRefs" condition to False for this Listener with the
"InvalidRouteKinds" reason.

Support: Core | | MaxItems: 8
| #### BackendTrafficPolicySpec @@ -32,9 +47,9 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `targetRefs` _[LocalPolicyTargetReference](#localpolicytargetreference) array_ | TargetRefs identifies API object(s) to apply this policy to.
Currently, Backends (A grouping of like endpoints such as Service,
ServiceImport, or any implementation-specific backendRef) are the only
valid API target references.
Currently, a TargetRef can not be scoped to a specific port on a
Service. | | MaxItems: 16
MinItems: 1
| -| `retryConstraint` _[RetryConstraint](#retryconstraint)_ | RetryConstraint defines the configuration for when to allow or prevent
further retries to a target backend, by dynamically calculating a 'retry
budget'. This budget is calculated based on the percentage of incoming
traffic composed of retries over a given time interval. Once the budget
is exceeded, additional retries will be rejected.
For example, if the retry budget interval is 10 seconds, there have been
1000 active requests in the past 10 seconds, and the allowed percentage
of requests that can be retried is 20% (the default), then 200 of those
requests may be composed of retries. Active requests will only be
considered for the duration of the interval when calculating the retry
budget. Retrying the same original request multiple times within the
retry budget interval will lead to each retry being counted towards
calculating the budget.
Configuring a RetryConstraint in BackendTrafficPolicy is compatible with
HTTPRoute Retry settings for each HTTPRouteRule that targets the same
backend. While the HTTPRouteRule Retry stanza can specify whether a
request will be retried, and the number of retry attempts each client
may perform, RetryConstraint helps prevent cascading failures such as
retry storms during periods of consistent failures.
After the retry budget has been exceeded, additional retries to the
backend MUST return a 503 response to the client.
Additional configurations for defining a constraint on retries MAY be
defined in the future.
Support: Extended
| | | -| `sessionPersistence` _[SessionPersistence](#sessionpersistence)_ | SessionPersistence defines and configures session persistence
for the backend.
Support: Extended | | | +| `targetRefs` _LocalPolicyTargetReference array_ | TargetRefs identifies API object(s) to apply this policy to.
Currently, Backends (A grouping of like endpoints such as Service,
ServiceImport, or any implementation-specific backendRef) are the only
valid API target references.

Currently, a TargetRef can not be scoped to a specific port on a
Service. | | MaxItems: 16
MinItems: 1
| +| `retryConstraint` _[RetryConstraint](#retryconstraint)_ | RetryConstraint defines the configuration for when to allow or prevent
further retries to a target backend, by dynamically calculating a 'retry
budget'. This budget is calculated based on the percentage of incoming
traffic composed of retries over a given time interval. Once the budget
is exceeded, additional retries will be rejected.

For example, if the retry budget interval is 10 seconds, there have been
1000 active requests in the past 10 seconds, and the allowed percentage
of requests that can be retried is 20% (the default), then 200 of those
requests may be composed of retries. Active requests will only be
considered for the duration of the interval when calculating the retry
budget. Retrying the same original request multiple times within the
retry budget interval will lead to each retry being counted towards
calculating the budget.

Configuring a RetryConstraint in BackendTrafficPolicy is compatible with
HTTPRoute Retry settings for each HTTPRouteRule that targets the same
backend. While the HTTPRouteRule Retry stanza can specify whether a
request will be retried, and the number of retry attempts each client
may perform, RetryConstraint helps prevent cascading failures such as
retry storms during periods of consistent failures.

After the retry budget has been exceeded, additional retries to the
backend MUST return a 503 response to the client.

Additional configurations for defining a constraint on retries MAY be
defined in the future.

Support: Extended

| | | +| `sessionPersistence` _[SessionPersistence](#sessionpersistence)_ | SessionPersistence defines and configures session persistence
for the backend.

Support: Extended | | | #### BudgetDetails @@ -52,20 +67,130 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `percent` _integer_ | BudgetPercent defines the maximum percentage of active requests that may
be made up of retries.
Support: Extended | 20 | Maximum: 100
Minimum: 0
| -| `interval` _[Duration](#duration)_ | BudgetInterval defines the duration in which requests will be considered
for calculating the budget for retries.
Support: Extended | 10s | | +| `percent` _integer_ | BudgetPercent defines the maximum percentage of active requests that may
be made up of retries.

Support: Extended | 20 | Maximum: 100
Minimum: 0
| +| `interval` _[Duration](#duration)_ | BudgetInterval defines the duration in which requests will be considered
for calculating the budget for retries.

Support: Extended | 10s | Pattern: `^([0-9]\{1,5\}(h\|m\|s\|ms))\{1,4\}$`
| +#### Duration +_Underlying type:_ _string_ +_Appears in:_ +- [BudgetDetails](#budgetdetails) +- [RequestRate](#requestrate) +- SessionPersistence + + + +#### GatewayTLSConfig + + + +_Appears in:_ +- [ListenerEntry](#listenerentry) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `mode` _[TLSModeType](#tlsmodetype)_ | Mode defines the TLS behavior for the TLS session initiated by the client.
There are two possible modes:

- Terminate: The TLS session between the downstream client and the
Gateway is terminated at the Gateway. This mode requires certificates
to be specified in some way, such as populating the certificateRefs
field.
- Passthrough: The TLS session is NOT terminated by the Gateway. This
implies that the Gateway can't decipher the TLS stream except for
the ClientHello message of the TLS protocol. The certificateRefs field
is ignored in this mode.

Support: Core | Terminate | Enum: [Terminate Passthrough]
| +| `certificateRefs` _[SecretObjectReference](#secretobjectreference) array_ | CertificateRefs contains a series of references to Kubernetes objects that
contains TLS certificates and private keys. These certificates are used to
establish a TLS handshake for requests that match the hostname of the
associated listener.

A single CertificateRef to a Kubernetes Secret has "Core" support.
Implementations MAY choose to support attaching multiple certificates to
a Listener, but this behavior is implementation-specific.

References to a resource in different namespace are invalid UNLESS there
is a ReferenceGrant in the target namespace that allows the certificate
to be attached. If a ReferenceGrant does not allow this reference, the
"ResolvedRefs" condition MUST be set to False for this listener with the
"RefNotPermitted" reason.

This field is required to have at least one element when the mode is set
to "Terminate" (default) and is optional otherwise.

CertificateRefs can reference to standard Kubernetes resources, i.e.
Secret, or implementation-specific custom resources.

Support: Core - A single reference to a Kubernetes Secret of type kubernetes.io/tls

Support: Implementation-specific (More than one reference or other resource types) | | MaxItems: 64
| +| `frontendValidation` _[FrontendTLSValidation](#frontendtlsvalidation)_ | FrontendValidation holds configuration information for validating the frontend (client).
Setting this field will require clients to send a client certificate
required for validation during the TLS handshake. In browsers this may result in a dialog appearing
that requests a user to specify the client certificate.
The maximum depth of a certificate chain accepted in verification is Implementation specific.

Support: Extended

| | | +| `options` _object (keys:[AnnotationKey](#annotationkey), values:[AnnotationValue](#annotationvalue))_ | Options are a list of key/value pairs to enable extended TLS
configuration for each implementation. For example, configuring the
minimum TLS version or supported cipher suites.

A set of common keys MAY be defined by the API in the future. To avoid
any ambiguity, implementation-specific definitions MUST use
domain-prefixed names, such as `example.com/my-custom-option`.
Un-prefixed names are reserved for key names defined by Gateway API.

Support: Implementation-specific | | MaxProperties: 16
| + + +#### Group + +_Underlying type:_ _string_ + +Group refers to a Kubernetes Group. It must either be an empty string or a +RFC 1123 subdomain. + + +This validation is based off of the corresponding Kubernetes validation: +https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/util/validation/validation.go#L208 + + +Valid values include: + + +* "" - empty string implies core Kubernetes API group +* "gateway.networking.k8s.io" +* "foo.example.com" + + +Invalid values include: + + +* "example.com/bar" - "/" is an invalid character + +_Validation:_ +- MaxLength: 253 +- Pattern: `^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$` + +_Appears in:_ +- LocalPolicyTargetReference +- [ObjectReference](#objectreference) +- [ParentGatewayReference](#parentgatewayreference) +- [ParentReference](#parentreference) +- [RouteGroupKind](#routegroupkind) +- [SecretObjectReference](#secretobjectreference) + + + +#### Hostname + +_Underlying type:_ _string_ + + + + + +_Appears in:_ +- [ListenerEntry](#listenerentry) + + + +#### Kind + +_Underlying type:_ _string_ + +Kind refers to a Kubernetes Kind. + + +Valid values include: + + +* "Service" +* "HTTPRoute" + + +Invalid values include: + + +* "invalid/kind" - "/" is an invalid character + +_Validation:_ +- MaxLength: 63 +- MinLength: 1 +- Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$` + +_Appears in:_ +- LocalPolicyTargetReference +- [ObjectReference](#objectreference) +- [ParentGatewayReference](#parentgatewayreference) +- [ParentReference](#parentreference) +- [RouteGroupKind](#routegroupkind) +- [SecretObjectReference](#secretobjectreference) + + + #### ListenerEntry @@ -79,12 +204,12 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `name` _[SectionName](#sectionname)_ | Name is the name of the Listener. This name MUST be unique within a
ListenerSet.
Name is not required to be unique across a Gateway and ListenerSets.
Routes can attach to a Listener by having a ListenerSet as a parentRef
and setting the SectionName | | | -| `hostname` _[Hostname](#hostname)_ | Hostname specifies the virtual hostname to match for protocol types that
define this concept. When unspecified, all hostnames are matched. This
field is ignored for protocols that don't require hostname based
matching.
Implementations MUST apply Hostname matching appropriately for each of
the following protocols:
* TLS: The Listener Hostname MUST match the SNI.
* HTTP: The Listener Hostname MUST match the Host header of the request.
* HTTPS: The Listener Hostname SHOULD match at both the TLS and HTTP
protocol layers as described above. If an implementation does not
ensure that both the SNI and Host header match the Listener hostname,
it MUST clearly document that.
For HTTPRoute and TLSRoute resources, there is an interaction with the
`spec.hostnames` array. When both listener and route specify hostnames,
there MUST be an intersection between the values for a Route to be
accepted. For more information, refer to the Route specific Hostnames
documentation.
Hostnames that are prefixed with a wildcard label (`*.`) are interpreted
as a suffix match. That means that a match for `*.example.com` would match
both `test.example.com`, and `foo.test.example.com`, but not `example.com`. | | | +| `name` _[SectionName](#sectionname)_ | Name is the name of the Listener. This name MUST be unique within a
ListenerSet.

Name is not required to be unique across a Gateway and ListenerSets.
Routes can attach to a Listener by having a ListenerSet as a parentRef
and setting the SectionName | | | +| `hostname` _[Hostname](#hostname)_ | Hostname specifies the virtual hostname to match for protocol types that
define this concept. When unspecified, all hostnames are matched. This
field is ignored for protocols that don't require hostname based
matching.

Implementations MUST apply Hostname matching appropriately for each of
the following protocols:

* TLS: The Listener Hostname MUST match the SNI.
* HTTP: The Listener Hostname MUST match the Host header of the request.
* HTTPS: The Listener Hostname SHOULD match at both the TLS and HTTP
protocol layers as described above. If an implementation does not
ensure that both the SNI and Host header match the Listener hostname,
it MUST clearly document that.

For HTTPRoute and TLSRoute resources, there is an interaction with the
`spec.hostnames` array. When both listener and route specify hostnames,
there MUST be an intersection between the values for a Route to be
accepted. For more information, refer to the Route specific Hostnames
documentation.

Hostnames that are prefixed with a wildcard label (`*.`) are interpreted
as a suffix match. That means that a match for `*.example.com` would match
both `test.example.com`, and `foo.test.example.com`, but not `example.com`. | | | | `port` _[PortNumber](#portnumber)_ | Port is the network port. Multiple listeners may use the
same port, subject to the Listener compatibility rules. | | | | `protocol` _[ProtocolType](#protocoltype)_ | Protocol specifies the network protocol this listener expects to receive. | | | -| `tls` _[GatewayTLSConfig](#gatewaytlsconfig)_ | TLS is the TLS configuration for the Listener. This field is required if
the Protocol field is "HTTPS" or "TLS". It is invalid to set this field
if the Protocol field is "HTTP", "TCP", or "UDP".
The association of SNIs to Certificate defined in GatewayTLSConfig is
defined based on the Hostname field for this listener.
The GatewayClass MUST use the longest matching SNI out of all
available certificates for any TLS handshake. | | | -| `allowedRoutes` _[AllowedRoutes](#allowedroutes)_ | AllowedRoutes defines the types of routes that MAY be attached to a
Listener and the trusted namespaces where those Route resources MAY be
present.
Although a client request may match multiple route rules, only one rule
may ultimately receive the request. Matching precedence MUST be
determined in order of the following criteria:
* The most specific match as defined by the Route type.
* The oldest Route based on creation timestamp. For example, a Route with
a creation timestamp of "2020-09-08 01:02:03" is given precedence over
a Route with a creation timestamp of "2020-09-08 01:02:04".
* If everything else is equivalent, the Route appearing first in
alphabetical order (namespace/name) should be given precedence. For
example, foo/bar is given precedence over foo/baz.
All valid rules within a Route attached to this Listener should be
implemented. Invalid Route rules can be ignored (sometimes that will mean
the full Route). If a Route rule transitions from valid to invalid,
support for that Route rule should be dropped to ensure consistency. For
example, even if a filter specified by a Route rule is invalid, the rest
of the rules within that Route should still be supported. | \{ namespaces:map[from:Same] \} | | +| `tls` _[GatewayTLSConfig](#gatewaytlsconfig)_ | TLS is the TLS configuration for the Listener. This field is required if
the Protocol field is "HTTPS" or "TLS". It is invalid to set this field
if the Protocol field is "HTTP", "TCP", or "UDP".

The association of SNIs to Certificate defined in GatewayTLSConfig is
defined based on the Hostname field for this listener.

The GatewayClass MUST use the longest matching SNI out of all
available certificates for any TLS handshake. | | | +| `allowedRoutes` _[AllowedRoutes](#allowedroutes)_ | AllowedRoutes defines the types of routes that MAY be attached to a
Listener and the trusted namespaces where those Route resources MAY be
present.

Although a client request may match multiple route rules, only one rule
may ultimately receive the request. Matching precedence MUST be
determined in order of the following criteria:

* The most specific match as defined by the Route type.
* The oldest Route based on creation timestamp. For example, a Route with
a creation timestamp of "2020-09-08 01:02:03" is given precedence over
a Route with a creation timestamp of "2020-09-08 01:02:04".
* If everything else is equivalent, the Route appearing first in
alphabetical order (namespace/name) should be given precedence. For
example, foo/bar is given precedence over foo/baz.

All valid rules within a Route attached to this Listener should be
implemented. Invalid Route rules can be ignored (sometimes that will mean
the full Route). If a Route rule transitions from valid to invalid,
support for that Route rule should be dropped to ensure consistency. For
example, even if a filter specified by a Route rule is invalid, the rest
of the rules within that Route should still be supported. | \{ namespaces:map[from:Same] \} | | @@ -106,8 +231,8 @@ _Appears in:_ | --- | --- | --- | --- | | `name` _[SectionName](#sectionname)_ | Name is the name of the Listener that this status corresponds to. | | | | `port` _[PortNumber](#portnumber)_ | Port is the network port the listener is configured to listen on. | | | -| `supportedKinds` _[RouteGroupKind](#routegroupkind) array_ | SupportedKinds is the list indicating the Kinds supported by this
listener. This MUST represent the kinds an implementation supports for
that Listener configuration.
If kinds are specified in Spec that are not supported, they MUST NOT
appear in this list and an implementation MUST set the "ResolvedRefs"
condition to "False" with the "InvalidRouteKinds" reason. If both valid
and invalid Route kinds are specified, the implementation MUST
reference the valid Route kinds that have been specified. | | MaxItems: 8
| -| `attachedRoutes` _integer_ | AttachedRoutes represents the total number of Routes that have been
successfully attached to this Listener.
Successful attachment of a Route to a Listener is based solely on the
combination of the AllowedRoutes field on the corresponding Listener
and the Route's ParentRefs field. A Route is successfully attached to
a Listener when it is selected by the Listener's AllowedRoutes field
AND the Route has a valid ParentRef selecting the whole Gateway
resource or a specific Listener as a parent resource (more detail on
attachment semantics can be found in the documentation on the various
Route kinds ParentRefs fields). Listener or Route status does not impact
successful attachment, i.e. the AttachedRoutes field count MUST be set
for Listeners with condition Accepted: false and MUST count successfully
attached Routes that may themselves have Accepted: false conditions.
Uses for this field include troubleshooting Route attachment and
measuring blast radius/impact of changes to a Listener. | | | +| `supportedKinds` _[RouteGroupKind](#routegroupkind) array_ | SupportedKinds is the list indicating the Kinds supported by this
listener. This MUST represent the kinds an implementation supports for
that Listener configuration.

If kinds are specified in Spec that are not supported, they MUST NOT
appear in this list and an implementation MUST set the "ResolvedRefs"
condition to "False" with the "InvalidRouteKinds" reason. If both valid
and invalid Route kinds are specified, the implementation MUST
reference the valid Route kinds that have been specified. | | MaxItems: 8
| +| `attachedRoutes` _integer_ | AttachedRoutes represents the total number of Routes that have been
successfully attached to this Listener.

Successful attachment of a Route to a Listener is based solely on the
combination of the AllowedRoutes field on the corresponding Listener
and the Route's ParentRefs field. A Route is successfully attached to
a Listener when it is selected by the Listener's AllowedRoutes field
AND the Route has a valid ParentRef selecting the whole Gateway
resource or a specific Listener as a parent resource (more detail on
attachment semantics can be found in the documentation on the various
Route kinds ParentRefs fields). Listener or Route status does not impact
successful attachment, i.e. the AttachedRoutes field count MUST be set
for Listeners with condition Accepted: false and MUST count successfully
attached Routes that may themselves have Accepted: false conditions.

Uses for this field include troubleshooting Route attachment and
measuring blast radius/impact of changes to a Listener. | | | | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#condition-v1-meta) array_ | Conditions describe the current condition of this listener. | | MaxItems: 8
| @@ -129,7 +254,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `parentRef` _[ParentGatewayReference](#parentgatewayreference)_ | ParentRef references the Gateway that the listeners are attached to. | | | -| `listeners` _[ListenerEntry](#listenerentry) array_ | Listeners associated with this ListenerSet. Listeners define
logical endpoints that are bound on this referenced parent Gateway's addresses.
Listeners in a `Gateway` and their attached `ListenerSets` are concatenated
as a list when programming the underlying infrastructure. Each listener
name does not need to be unique across the Gateway and ListenerSets.
See ListenerEntry.Name for more details.
Implementations MUST treat the parent Gateway as having the merged
list of all listeners from itself and attached ListenerSets using
the following precedence:
1. "parent" Gateway
2. ListenerSet ordered by creation time (oldest first)
3. ListenerSet ordered alphabetically by “\{namespace\}/\{name\}”.
An implementation MAY reject listeners by setting the ListenerEntryStatus
`Accepted`` condition to False with the Reason `TooManyListeners`
If a listener has a conflict, this will be reported in the
Status.ListenerEntryStatus setting the `Conflicted` condition to True.
Implementations SHOULD be cautious about what information from the
parent or siblings are reported to avoid accidentally leaking
sensitive information that the child would not otherwise have access
to. This can include contents of secrets etc. | | MaxItems: 64
MinItems: 1
| +| `listeners` _[ListenerEntry](#listenerentry) array_ | Listeners associated with this ListenerSet. Listeners define
logical endpoints that are bound on this referenced parent Gateway's addresses.

Listeners in a `Gateway` and their attached `ListenerSets` are concatenated
as a list when programming the underlying infrastructure. Each listener
name does not need to be unique across the Gateway and ListenerSets.
See ListenerEntry.Name for more details.

Implementations MUST treat the parent Gateway as having the merged
list of all listeners from itself and attached ListenerSets using
the following precedence:

1. "parent" Gateway
2. ListenerSet ordered by creation time (oldest first)
3. ListenerSet ordered alphabetically by “\{namespace\}/\{name\}”.

An implementation MAY reject listeners by setting the ListenerEntryStatus
`Accepted`` condition to False with the Reason `TooManyListeners`

If a listener has a conflict, this will be reported in the
Status.ListenerEntryStatus setting the `Conflicted` condition to True.

Implementations SHOULD be cautious about what information from the
parent or siblings are reported to avoid accidentally leaking
sensitive information that the child would not otherwise have access
to. This can include contents of secrets etc. | | MaxItems: 64
MinItems: 1
| #### ListenerSetStatus @@ -145,14 +270,86 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#condition-v1-meta) array_ | Conditions describe the current conditions of the ListenerSet.
Implementations MUST express ListenerSet conditions using the
`ListenerSetConditionType` and `ListenerSetConditionReason`
constants so that operators and tools can converge on a common
vocabulary to describe ListenerSet state.
Known condition types are:
* "Accepted"
* "Programmed" | [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Accepted] map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Programmed]] | MaxItems: 8
| +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#condition-v1-meta) array_ | Conditions describe the current conditions of the ListenerSet.

Implementations MUST express ListenerSet conditions using the
`ListenerSetConditionType` and `ListenerSetConditionReason`
constants so that operators and tools can converge on a common
vocabulary to describe ListenerSet state.

Known condition types are:

* "Accepted"
* "Programmed" | [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Accepted] map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Programmed]] | MaxItems: 8
| | `listeners` _[ListenerEntryStatus](#listenerentrystatus) array_ | Listeners provide status for each unique listener port defined in the Spec. | | MaxItems: 64
| +#### LocalPolicyTargetReference + + + + + + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `group` _[Group](#group)_ | Group is the group of the target resource. | | MaxLength: 253
Pattern: `^$\|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
| +| `kind` _[Kind](#kind)_ | Kind is kind of the target resource. | | MaxLength: 63
MinLength: 1
Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$`
| +| `name` _[ObjectName](#objectname)_ | Name is the name of the target resource. | | MaxLength: 253
MinLength: 1
| + + +#### Namespace + +_Underlying type:_ _string_ + +Namespace refers to a Kubernetes namespace. It must be a RFC 1123 label. + + +This validation is based off of the corresponding Kubernetes validation: +https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/util/validation/validation.go#L187 + + +This is used for Namespace name validation here: +https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/api/validation/generic.go#L63 + + +Valid values include: + + +* "example" +Invalid values include: +* "example.com" - "." is an invalid character + +_Validation:_ +- MaxLength: 63 +- MinLength: 1 +- Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` + +_Appears in:_ +- [ObjectReference](#objectreference) +- [ParentGatewayReference](#parentgatewayreference) +- [ParentReference](#parentreference) +- [SecretObjectReference](#secretobjectreference) + + + +#### ObjectName + +_Underlying type:_ _string_ + +ObjectName refers to the name of a Kubernetes object. +Object names can have a variety of forms, including RFC 1123 subdomains, +RFC 1123 labels, or RFC 1035 labels. + +_Validation:_ +- MaxLength: 253 +- MinLength: 1 + +_Appears in:_ +- LocalPolicyTargetReference +- [ObjectReference](#objectreference) +- [ParentGatewayReference](#parentgatewayreference) +- [ParentReference](#parentreference) +- [SecretObjectReference](#secretobjectreference) + #### ParentGatewayReference @@ -169,16 +366,61 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `group` _[Group](#group)_ | Group is the group of the referent. | gateway.networking.k8s.io | | -| `kind` _[Kind](#kind)_ | Kind is kind of the referent. For example "Gateway". | Gateway | | -| `name` _[ObjectName](#objectname)_ | Name is the name of the referent. | | | -| `namespace` _[Namespace](#namespace)_ | Namespace is the namespace of the referent. If not present,
the namespace of the referent is assumed to be the same as
the namespace of the referring object. | | | +| `group` _[Group](#group)_ | Group is the group of the referent. | gateway.networking.k8s.io | MaxLength: 253
Pattern: `^$\|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
| +| `kind` _[Kind](#kind)_ | Kind is kind of the referent. For example "Gateway". | Gateway | MaxLength: 63
MinLength: 1
Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$`
| +| `name` _[ObjectName](#objectname)_ | Name is the name of the referent. | | MaxLength: 253
MinLength: 1
| +| `namespace` _[Namespace](#namespace)_ | Namespace is the namespace of the referent. If not present,
the namespace of the referent is assumed to be the same as
the namespace of the referring object. | | MaxLength: 63
MinLength: 1
Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
| + + +#### PolicyStatus + + + + + + + +_Appears in:_ +- [XBackendTrafficPolicy](#xbackendtrafficpolicy) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `ancestors` _[PolicyAncestorStatus](#policyancestorstatus) array_ | Ancestors is a list of ancestor resources (usually Gateways) that are
associated with the policy, and the status of the policy with respect to
each ancestor. When this policy attaches to a parent, the controller that
manages the parent and the ancestors MUST add an entry to this list when
the controller first sees the policy and SHOULD update the entry as
appropriate when the relevant ancestor is modified.

Note that choosing the relevant ancestor is left to the Policy designers;
an important part of Policy design is designing the right object level at
which to namespace this status.

Note also that implementations MUST ONLY populate ancestor status for
the Ancestor resources they are responsible for. Implementations MUST
use the ControllerName field to uniquely identify the entries in this list
that they are responsible for.

Note that to achieve this, the list of PolicyAncestorStatus structs
MUST be treated as a map with a composite key, made up of the AncestorRef
and ControllerName fields combined.

A maximum of 16 ancestors will be represented in this list. An empty list
means the Policy is not relevant for any ancestors.

If this slice is full, implementations MUST NOT add further entries.
Instead they MUST consider the policy unimplementable and signal that
on any related resources such as the ancestor that would be referenced
here. For example, if this list was full on BackendTLSPolicy, no
additional Gateways would be able to reference the Service targeted by
the BackendTLSPolicy. | | MaxItems: 16
| + + +#### PortNumber +_Underlying type:_ _integer_ +_Appears in:_ +- [ListenerEntry](#listenerentry) +- [ListenerEntryStatus](#listenerentrystatus) +- [ParentReference](#parentreference) + + + +#### ProtocolType + +_Underlying type:_ _string_ + + + + + +_Appears in:_ +- [ListenerEntry](#listenerentry) + +| Field | Description | +| --- | --- | +| `HTTP` | Accepts cleartext HTTP/1.1 sessions over TCP. Implementations MAY also
support HTTP/2 over cleartext. If implementations support HTTP/2 over
cleartext on "HTTP" listeners, that MUST be clearly documented by the
implementation.
| +| `HTTPS` | Accepts HTTP/1.1 or HTTP/2 sessions over TLS.
| +| `TLS` | Accepts TLS sessions over TCP.
| +| `TCP` | Accepts TCP sessions.
| +| `UDP` | Accepts UDP packets.
| #### RequestRate @@ -194,8 +436,8 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `count` _integer_ | Count specifies the number of requests per time interval.
Support: Extended | | Maximum: 1e+06
Minimum: 1
| -| `interval` _[Duration](#duration)_ | Interval specifies the divisor of the rate of requests, the amount of
time during which the given count of requests occur.
Support: Extended | | | +| `count` _integer_ | Count specifies the number of requests per time interval.

Support: Extended | | Maximum: 1e+06
Minimum: 1
| +| `interval` _[Duration](#duration)_ | Interval specifies the divisor of the rate of requests, the amount of
time during which the given count of requests occur.

Support: Extended | | Pattern: `^([0-9]\{1,5\}(h\|m\|s\|ms))\{1,4\}$`
| #### RetryConstraint @@ -212,13 +454,60 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `budget` _[BudgetDetails](#budgetdetails)_ | Budget holds the details of the retry budget configuration. | \{ interval:10s percent:20 \} | | -| `minRetryRate` _[RequestRate](#requestrate)_ | MinRetryRate defines the minimum rate of retries that will be allowable
over a specified duration of time.
The effective overall minimum rate of retries targeting the backend
service may be much higher, as there can be any number of clients which
are applying this setting locally.
This ensures that requests can still be retried during periods of low
traffic, where the budget for retries may be calculated as a very low
value.
Support: Extended | \{ count:10 interval:1s \} | | +| `minRetryRate` _[RequestRate](#requestrate)_ | MinRetryRate defines the minimum rate of retries that will be allowable
over a specified duration of time.

The effective overall minimum rate of retries targeting the backend
service may be much higher, as there can be any number of clients which
are applying this setting locally.

This ensures that requests can still be retried during periods of low
traffic, where the budget for retries may be calculated as a very low
value.

Support: Extended | \{ count:10 interval:1s \} | | + + +#### RouteGroupKind + + + +RouteGroupKind indicates the group and kind of a Route resource. + + + +_Appears in:_ +- AllowedRoutes +- [ListenerEntryStatus](#listenerentrystatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `group` _[Group](#group)_ | Group is the group of the Route. | gateway.networking.k8s.io | MaxLength: 253
Pattern: `^$\|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
| +| `kind` _[Kind](#kind)_ | Kind is the kind of the Route. | | MaxLength: 63
MinLength: 1
Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$`
| + + +#### SectionName + +_Underlying type:_ _string_ + + + + + +_Appears in:_ +- [ListenerEntry](#listenerentry) +- [ListenerEntryStatus](#listenerentrystatus) +- [ParentReference](#parentreference) + + + +#### SessionPersistence + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `sessionName` _string_ | SessionName defines the name of the persistent session token
which may be reflected in the cookie or the header. Users
should avoid reusing session names to prevent unintended
consequences, such as rejection or unpredictable behavior.

Support: Implementation-specific | | MaxLength: 128
| +| `absoluteTimeout` _[Duration](#duration)_ | AbsoluteTimeout defines the absolute timeout of the persistent
session. Once the AbsoluteTimeout duration has elapsed, the
session becomes invalid.

Support: Extended | | Pattern: `^([0-9]\{1,5\}(h\|m\|s\|ms))\{1,4\}$`
| +| `idleTimeout` _[Duration](#duration)_ | IdleTimeout defines the idle timeout of the persistent session.
Once the session has been idle for more than the specified
IdleTimeout duration, the session becomes invalid.

Support: Extended | | Pattern: `^([0-9]\{1,5\}(h\|m\|s\|ms))\{1,4\}$`
| +| `type` _[SessionPersistenceType](#sessionpersistencetype)_ | Type defines the type of session persistence such as through
the use a header or cookie. Defaults to cookie based session
persistence.

Support: Core for "Cookie" type

Support: Extended for "Header" type | Cookie | Enum: [Cookie Header]
| +| `cookieConfig` _[CookieConfig](#cookieconfig)_ | CookieConfig provides configuration settings that are specific
to cookie-based session persistence.

Support: Core | | | #### XBackendTrafficPolicy