API Reference¶

Packages¶

gateway.networking.x-k8s.io/v1alpha1

gateway.networking.x-k8s.io/v1alpha1¶

Package v1alpha1 contains API Schema definitions for the gateway.networking.k8s-x.io API group.

Resource Types¶

XBackendTrafficPolicy
XListenerSet

BackendTrafficPolicySpec¶

BackendTrafficPolicySpec define the desired state of BackendTrafficPolicy Note: there is no Override or Default policy configuration.

Appears in: - XBackendTrafficPolicy

Field	Description	Validation
`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 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 defines and configures session persistence for the backend. Support: Extended

BudgetDetails¶

BudgetDetails specifies the details of the budget configuration, like the percentage of requests in the budget, and the interval between checks.

Appears in: - RetryConstraint

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	BudgetInterval defines the duration in which requests will be considered for calculating the budget for retries. Support: Extended	10s

ListenerEntry¶

Appears in: - ListenerSetSpec

Field	Description	Default
`name` 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 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	Port is the network port. Multiple listeners may use the same port, subject to the Listener compatibility rules.
`protocol` ProtocolType	Protocol specifies the network protocol this listener expects to receive.
`tls` 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 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] }

ListenerEntryStatus¶

ListenerStatus is the status associated with a Listener.

Appears in: - ListenerSetStatus

Field	Description	Validation
`name` SectionName	Name is the name of the Listener that this status corresponds to.
`port` PortNumber	Port is the network port the listener is configured to listen on.
`supportedKinds` 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 array	Conditions describe the current condition of this listener.	MaxItems: 8

ListenerSetSpec¶

ListenerSetSpec defines the desired state of a ListenerSet.

Appears in: - XListenerSet

Field	Description	Default	Validation
`parentRef` ParentGatewayReference	ParentRef references the Gateway that the listeners are attached to.
`listeners` 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 ReasonTooManyListeners`<br />If a listener has a conflict, this will be reported in the<br />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¶

Appears in: - XListenerSet

Field	Description	Default	Validation
`conditions` Condition 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 array	Listeners provide status for each unique listener port defined in the Spec.		MaxItems: 64

ParentGatewayReference¶

ParentGatewayReference identifies an API object including its namespace, defaulting to Gateway.

Appears in: - ListenerSetSpec

Field	Description	Default
`group` Group	Group is the group of the referent.	gateway.networking.k8s.io
`kind` Kind	Kind is kind of the referent. For example "Gateway".	Gateway
`name` ObjectName	Name is the name of the referent.
`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.

RequestRate¶

RequestRate expresses a rate of requests over a given period of time.

Appears in: - RetryConstraint

Field	Description	Default	Validation
`count` integer	Count specifies the number of requests per time interval. Support: Extended		Maximum: 1e+06 Minimum: 1
`interval` Duration	Interval specifies the divisor of the rate of requests, the amount of time during which the given count of requests occur. Support: Extended

RetryConstraint¶

RetryConstraint defines the configuration for when to retry a request.

Appears in: - BackendTrafficPolicySpec

Field	Description	Default	Validation
`budget` BudgetDetails	Budget holds the details of the retry budget configuration.	{ interval:10s percent:20 }
`minRetryRate` 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 }

XBackendTrafficPolicy¶

XBackendTrafficPolicy defines the configuration for how traffic to a target backend should be handled.

Field	Description	Default	Validation
`apiVersion` string	`gateway.networking.x-k8s.io/v1alpha1`
`kind` string	`XBackendTrafficPolicy`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` BackendTrafficPolicySpec	Spec defines the desired state of BackendTrafficPolicy.
`status` PolicyStatus	Status defines the current state of BackendTrafficPolicy.

XListenerSet¶

XListenerSet defines a set of additional listeners to attach to an existing Gateway.

Field	Description	Default
`apiVersion` string	`gateway.networking.x-k8s.io/v1alpha1`
`kind` string	`XListenerSet`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` ListenerSetSpec	Spec defines the desired state of ListenerSet.
`status` ListenerSetStatus	Status defines the current state of ListenerSet.	{ 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]] }