API Reference

Validations:
MaxItems: 16
MinItems: 1
Required

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.

Validations:
Optional

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

gateway:experimental

Validations:
Optional

SessionPersistence defines and configures session persistence for the backend.

Support: Extended

Default: 20

Validations:
Maximum: 100
Minimum: 0
Optional

Percent defines the maximum percentage of active requests that may be made up of retries.

Support: Extended

Default: 10s

Validations:
Optional

Interval defines the duration in which requests will be considered for calculating the budget for retries.

Support: Extended

Validations:
Required

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

Validations:
Optional

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.

Default: 0

Validations:
Maximum: 65535
Minimum: 0
Optional

Port is the network port. Multiple listeners may use the same port, subject to the Listener compatibility rules.

If the port is not set or specified as zero, the implementation will assign a unique port. If the implementation does not support dynamic port assignment, it MUST set Accepted condition to False with the UnsupportedPort reason.

Validations:
Required

Protocol specifies the network protocol this listener expects to receive.

Validations:
Optional

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 ListenerTLSConfig 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.

Default: { namespaces:map[from:Same] }

Validations:
Optional

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.

Validations:
Required

Name is the name of the Listener that this status corresponds to.

Validations:
Maximum: 65535
Minimum: 1
Required

Port is the network port the listener is configured to listen on.

Validations:
MaxItems: 8
Required

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.

Validations:
Required

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.

Validations:
MaxItems: 8
Required

Conditions describe the current condition of this listener.

Validations:
Required

ParentRef references the Gateway that the listeners are attached to.

Validations:
MaxItems: 64
MinItems: 1
Required

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.

Default: [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]]

Validations:
MaxItems: 8
Optional

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"

Validations:
MaxItems: 64
Optional

Listeners provide status for each unique listener port defined in the Spec.

Validations:
Required

ControllerName is the name of a controller that is managing Gateway API resources for mesh traffic management. The value of this field MUST be a domain prefixed path.

Example: "example.com/awesome-mesh".

This field is not mutable and cannot be empty.

Support: Core

Validations:
Optional

ParametersRef is an optional reference to a resource that contains implementation-specific configuration for this Mesh. If no implementation-specific parameters are needed, this field MUST be omitted.

ParametersRef can reference a standard Kubernetes resource, i.e. ConfigMap, or an implementation-specific custom resource. The resource can be cluster-scoped or namespace-scoped.

If the referent cannot be found, refers to an unsupported kind, or when the data within that resource is malformed, the Mesh MUST be rejected with the "Accepted" status condition set to "False" and an "InvalidParameters" reason.

Support: Implementation-specific

Validations:
MaxLength: 64
Optional

Description optionally provides a human-readable description of a Mesh.

Default: [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]]

Validations:
MaxItems: 8
Optional

Conditions is the current status from the controller for this Mesh.

Controllers should prefer to publish conditions using values of MeshConditionType for the type of each Condition.

Validations:
MaxItems: 64
Optional

SupportedFeatures is the set of features the Mesh support. It MUST be sorted in ascending alphabetical order by the Name key.

Default: gateway.networking.k8s.io

Validations:
Optional

Group is the group of the referent.

Default: Gateway

Validations:
Optional

Kind is kind of the referent. For example "Gateway".

Validations:
Required

Name is the name of the referent.

Validations:
Optional

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.

Validations:
Maximum: 1e+06
Minimum: 1
Optional

Count specifies the number of requests per time interval.

Support: Extended

Validations:
Optional

Interval specifies the divisor of the rate of requests, the amount of time during which the given count of requests occur.

Support: Extended

Default: { interval:10s percent:20 }

Validations:
Optional

Budget holds the details of the retry budget configuration.

Default: { count:10 interval:1s }

Validations:
Optional

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

Validations:
Optional

Validations:
Required

Spec defines the desired state of BackendTrafficPolicy.

Validations:
Optional

Status defines the current state of BackendTrafficPolicy.

Validations:
Optional

Validations:
Required

Spec defines the desired state of ListenerSet.

Default: { conditions:[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]] }

Validations:
Optional

Status defines the current state of ListenerSet.

Validations:
Optional

Validations:
Required

Spec defines the desired state of XMesh.

Default: { conditions:[map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Accepted]] }

Validations:
Optional

Status defines the current state of XMesh.