API Specification

Packages:

• gateway.networking.k8s.io/v1alpha2

gateway.networking.k8s.io/v1alpha2

Package v1alpha2 contains API Schema definitions for the gateway.networking.k8s.io API group.

Resource Types:

• Gateway
• GatewayClass
• HTTPRoute
• ReferencePolicy
• TCPRoute
• TLSRoute
• UDPRoute

Gateway

Gateway represents an instantiation of a service-traffic handling infrastructure by binding Listeners to a set of IP addresses.

Implementations should add the gateway-exists-finalizer.gateway.networking.k8s.io finalizer on the associated GatewayClass whenever Gateway(s) is running. This ensures that a GatewayClass associated with a Gateway(s) is not deleted while in use.

Field	Description
apiVersion string	gateway.networking.k8s.io/v1alpha2
kind string	Gateway
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec GatewaySpec	Spec defines the desired state of Gateway. gatewayClassName string GatewayClassName used for this Gateway. This is the name of a GatewayClass resource. listeners []Listener Listeners associated with this Gateway. Listeners define logical endpoints that are bound on this Gateway’s addresses. At least one Listener MUST be specified. An implementation MAY group Listeners by Port and then collapse each group of Listeners into a single Listener if the implementation determines that the Listeners in the group are “compatible”. An implementation MAY also group together and collapse compatible Listeners belonging to different Gateways. For example, an implementation might consider Listeners to be compatible with each other if all of the following conditions are met: Either each Listener within the group specifies the “HTTP” Protocol or each Listener within the group specifies either the “HTTPS” or “TLS” Protocol. Each Listener within the group specifies a Hostname that is unique within the group. As a special case, one Listener within a group may omit Hostname, in which case this Listener matches when no other Listener matches. If the implementation does collapse compatible Listeners, the hostname provided in the incoming client request MUST be matched to a Listener to find the correct set of Routes. The incoming hostname MUST be matched using the Hostname field for each Listener in order of most to least specific. That is, exact matches must be processed before wildcard matches. If this field specifies multiple Listeners that have the same Port value but are not compatible, the implementation must raise a “Conflicted” condition in the Listener status. Support: Core addresses []GatewayAddress (Optional) Addresses requested for this gateway. This is optional and behavior can depend on the GatewayClass. If a value is set in the spec and the requested address is invalid, the GatewayClass MUST indicate this in the associated entry in GatewayStatus.Addresses. If no Addresses are specified, the GatewayClass may schedule the Gateway in an implementation-defined manner, assigning an appropriate set of Addresses. The GatewayClass MUST bind all Listeners to every GatewayAddress that it assigns to the Gateway. Support: Core
status GatewayStatus	Status defines the current state of Gateway.

GatewayClass

GatewayClass describes a class of Gateways available to the user for creating Gateway resources.

GatewayClass is a Cluster level resource.

Field	Description
apiVersion string	gateway.networking.k8s.io/v1alpha2
kind string	GatewayClass
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec GatewayClassSpec	Spec defines the desired state of GatewayClass. controller GatewayController Controller is a domain/path string that indicates the controller that is managing Gateways of this class. Example: “acme.io/gateway-controller”. This field is not mutable and cannot be empty. The format of this field is DOMAIN “/” PATH, where DOMAIN is a valid Kubernetes name (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) and PATH is a valid HTTP path as defined by RFC 3986. Support: Core parametersRef ParametersReference (Optional) ParametersRef is a reference to a resource that contains the configuration parameters corresponding to the GatewayClass. This is optional if the controller does not require any additional configuration. 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, the GatewayClass’s “InvalidParameters” status condition will be true. Support: Custom description string (Optional) Description helps describe a GatewayClass with more details.
status GatewayClassStatus	Status defines the current state of GatewayClass.

HTTPRoute

HTTPRoute is the Schema for the HTTPRoute resource.

Field	Description
apiVersion string	gateway.networking.k8s.io/v1alpha2
kind string	HTTPRoute
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec HTTPRouteSpec	Spec defines the desired state of HTTPRoute. CommonRouteSpec CommonRouteSpec (Members of CommonRouteSpec are embedded into this type.) hostnames []Hostname (Optional) Hostnames defines a set of hostname that should match against the HTTP Host header to select a HTTPRoute to process the request. Hostname is the fully qualified domain name of a network host, as defined by RFC 3986. Note the following deviations from the “host” part of the URI as defined in the RFC: IPs are not allowed. The : delimiter is not respected because ports are not allowed. Incoming requests are matched against the hostnames before the HTTPRoute rules. If no hostname is specified, traffic is routed based on the HTTPRouteRules. Requests will be matched against the Host field in the following order: If Hostname is precise, the request matches this rule if the HTTP Host header is equal to the Hostname. If Hostname is a wildcard, then the request matches this rule if the HTTP Host header is to equal to the suffix (removing the first label) of the wildcard rule. If Hostname is unspecified, empty, or *, then any request will match this route. If a hostname is specified by the Listener that the HTTPRoute is bound to, at least one hostname specified here must match the Listener specified hostname as per the rules above. Other hostnames will not affect processing of the route in that case. If no hostname is specified by the Listener, then that value will be treated as ‘*’, match any hostname, and so any hostname on this Route will match. If all hostnames do not match, then the HTTPRoute is not admitted, and the implementation must raise an ‘Admitted’ Condition with a status of false for that Listener. Examples: - A Listener with unspecified, empty, or * values for Hostname matches any HTTPRoute hostname. - A HTTPRoute with unspecified, empty, or * values for Hostname matches any Listener hostname. - A Listener with test.foo.com as the hostname matches only test.foo.com or *.foo.com. Any other hostnames present must be ignored. - A Listener with *.foo.com as hostname, all hostnames in the HTTPRoute must have any single label where the star is, and the rest of the hostname must match exactly. So, test.foo.com, *.foo.com or blog.foo.com match. test.blog.foo.com, test.bar.com, or bar.com do not. Hostnames that do not match will be ignored. Support: Core rules []HTTPRouteRule (Optional) Rules are a list of HTTP matchers, filters and actions.
status HTTPRouteStatus	Status defines the current state of HTTPRoute.

ReferencePolicy

ReferencePolicy identifies kinds of resources in other namespaces that are trusted to reference the specified kinds of resources in the same namespace as the policy.

Each ReferencePolicy can be used to represent a unique trust relationship. Additional Reference Policies can be used to add to the set of trusted sources of inbound references for the namespace they are defined within.

All cross-namespace references in Gateway API (with the exception of cross-namespace Gateway-route attachment) require a ReferencePolicy.

Support: Core

Field	Description
apiVersion string	gateway.networking.k8s.io/v1alpha2
kind string	ReferencePolicy
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ReferencePolicySpec	Spec defines the desired state of ReferencePolicy. from []ReferencePolicyFrom From describes the trusted namespaces and kinds that can reference the resources described in “To”. Each entry in this list must be considered to be an additional place that references can be valid from, or to put this another way, entries must be combined using OR. Support: Core to []ReferencePolicyTo To describes the resources that may be referenced by the resources described in “From”. Each entry in this list must be considered to be an additional place that references can be valid to, or to put this another way, entries must be combined using OR. Support: Core

TCPRoute

TCPRoute is the Schema for the TCPRoute resource.

Field	Description
apiVersion string	gateway.networking.k8s.io/v1alpha2
kind string	TCPRoute
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec TCPRouteSpec	Spec defines the desired state of TCPRoute. CommonRouteSpec CommonRouteSpec (Members of CommonRouteSpec are embedded into this type.) rules []TCPRouteRule Rules are a list of TCP matchers and actions.
status TCPRouteStatus	Status defines the current state of TCPRoute.

TLSRoute

The TLSRoute resource is similar to TCPRoute, but can be configured to match against TLS-specific metadata. This allows more flexibility in matching streams for a given TLS listener.

If you need to forward traffic to a single target for a TLS listener, you could choose to use a TCPRoute with a TLS listener.

Field	Description
apiVersion string	gateway.networking.k8s.io/v1alpha2
kind string	TLSRoute
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec TLSRouteSpec	Spec defines the desired state of TLSRoute. CommonRouteSpec CommonRouteSpec (Members of CommonRouteSpec are embedded into this type.) hostnames []Hostname (Optional) Hostnames defines a set of SNI names that should match against the SNI attribute of TLS ClientHello message in TLS handshake. SNI can be “precise” which is a domain name without the terminating dot of a network host (e.g. “foo.example.com”) or “wildcard”, which is a domain name prefixed with a single wildcard label (e.g. *.example.com). The wildcard character * must appear by itself as the first DNS label and matches only a single label. You cannot have a wildcard label by itself (e.g. Host == *). Requests will be matched against the Host field in the following order: If SNI is precise, the request matches this rule if the SNI in ClientHello is equal to one of the defined SNIs. If SNI is a wildcard, then the request matches this rule if the SNI is to equal to the suffix (removing the first label) of the wildcard rule. If SNIs is unspecified, all requests associated with the gateway TLS listener will match. This can be used to define a default backend for a TLS listener. Support: Core rules []TLSRouteRule Rules are a list of TLS matchers and actions.
status TLSRouteStatus	Status defines the current state of TLSRoute.

UDPRoute

UDPRoute is a resource that specifies how a Gateway should forward UDP traffic.

Field	Description
apiVersion string	gateway.networking.k8s.io/v1alpha2
kind string	UDPRoute
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec UDPRouteSpec	Spec defines the desired state of UDPRoute. CommonRouteSpec CommonRouteSpec (Members of CommonRouteSpec are embedded into this type.) rules []UDPRouteRule Rules are a list of UDP matchers and actions.
status UDPRouteStatus	Status defines the current state of UDPRoute.

AddressType (string alias)

(Appears on: GatewayAddress)

AddressType defines how a network address is represented as a text string.

If the requested address is unsupported, the controller should raise the “Detached” listener status condition on the Gateway with the “UnsupportedAddress” reason.

Value	Description
"Hostname"	A Hostname represents a DNS based ingress point. This is similar to the corresponding hostname field in Kubernetes load balancer status. For example, this concept may be used for cloud load balancers where a DNS name is used to expose a load balancer. Support: Extended
"IPAddress"	A textual representation of a numeric IP address. IPv4 addresses must be in dotted-decimal form. IPv6 addresses must be in a standard IPv6 text representation (see RFC 5952). Support: Extended
"NamedAddress"	A NamedAddress provides a way to reference a specific IP address by name. For example, this may be a name or other unique identifier that refers to a resource on a cloud provider such as a static IP. Support: Implementation-Specific

BackendObjectReference

(Appears on: BackendRef, HTTPRequestMirrorFilter)

BackendObjectReference defines how an ObjectReference that is specific to BackendRef. It includes a few additional fields and features than a regular ObjectReference.

Note that when a namespace is specified, a ReferencePolicy object is required in the referent namespace to allow that namespace’s owner to accept the reference. See the ReferencePolicy documentation for details.

Field	Description
group Group	(Optional) Group is the group of the referent. For example, “networking.k8s.io”. When unspecified (empty string), core API group is inferred.
kind Kind	(Optional) Kind is kind of the referent. For example “HTTPRoute” or “Service”.
name string	Name is the name of the referent.
namespace Namespace	(Optional) Namespace is the namespace of the backend. When unspecified, the local namespace is inferred. Note that when a namespace is specified, a ReferencePolicy object is required in the referent namespace to allow that namespace’s owner to accept the reference. See the ReferencePolicy documentation for details. Support: Core
port PortNumber	(Optional) Port specifies the destination port number to use for this resource. Port is required when the referent is a Kubernetes Service. For other resources, destination port can be derived from the referent resource or this field.

BackendRef

(Appears on: HTTPBackendRef, TCPRouteRule, TLSRouteRule, UDPRouteRule)

BackendRef defines how a Route should forward a request to a Kubernetes resource.

Note that when a namespace is specified, a ReferencePolicy object is required in the referent namespace to allow that namespace’s owner to accept the reference. See the ReferencePolicy documentation for details.

Field	Description
BackendObjectReference BackendObjectReference	(Members of BackendObjectReference are embedded into this type.) BackendObjectReference references a Kubernetes object.
weight int32	(Optional) Weight specifies the proportion of HTTP requests forwarded to the referenced backend. This is computed as weight/(sum of all weights in this ForwardTo list). For non-zero values, there may be some epsilon from the exact proportion defined here depending on the precision an implementation supports. Weight is not a percentage and the sum of weights does not need to equal 100. If only one backend is specified and it has a weight greater than 0, 100% of the traffic is forwarded to that backend. If weight is set to 0, no traffic should be forwarded for this entry. If unspecified, weight defaults to 1. Support for this field varies based on the context where used.

CommonRouteSpec

(Appears on: HTTPRouteSpec, TCPRouteSpec, TLSRouteSpec, UDPRouteSpec)

CommonRouteSpec defines the common attributes that all Routes should include within their spec.

Field

Description

parentRefs []ParentRef

(Optional) ParentRefs references the resources (usually Gateways) that a Route wants to be attached to. Note that the referenced parent resource needs to allow this for the attachment to be complete. For Gateways, that means the Gateway needs to allow attachment from Routes of this kind and namespace. The only kind of parent resource with “Core” support is Gateway. This API may be extended in the future to support additional kinds of parent resources such as one of the route kinds. It is invalid to reference an identical parent more than once. It is valid to reference multiple distinct sections within the same parent resource, such as 2 Listeners within a Gateway. It is possible to separately reference multiple distinct objects that may be collapsed by an implementation. For example, some implementations may choose to merge compatible Gateway Listeners together. If that is the case, the list of routes attached to those resources should also be merged.

GatewayAddress

(Appears on: GatewaySpec, GatewayStatus)

GatewayAddress describes an address that can be bound to a Gateway.

Field	Description
type AddressType	(Optional) Type of the address. Support: Extended
value string	Value of the address. The validity of the values will depend on the type and support by the controller. Examples: 1.2.3.4, 128::1, my-ip-address.

GatewayClassConditionReason (string alias)

GatewayClassConditionReason defines the set of reasons that explain why a particular GatewayClass condition type has been raised.

Value	Description
"Admitted"	This reason is used with the “Admitted” condition when the condition is true.
"InvalidParameters"	This reason is used with the “Admitted” condition when the GatewayClass was not admitted because the parametersRef field was invalid, with more detail in the message.
"Waiting"	This reason is used with the “Admitted” condition when the requested controller has not yet made a decision about whether to admit the GatewayClass. It is the default Reason on a new GatewayClass. It indicates

GatewayClassConditionType (string alias)

GatewayClassConditionType is the type for status conditions on Gateway resources. This type should be used with the GatewayClassStatus.Conditions field.

Value

Description

"Admitted"

This condition indicates whether the GatewayClass has been admitted by the controller requested in the spec.controller field. This condition defaults to False, and MUST be set by a controller when it sees a GatewayClass using its controller string. The status of this condition MUST be set to true if the controller will support provisioning Gateways using this class. Otherwise, this status MUST be set to false. If the status is set to false, the controller SHOULD set a Message and Reason as an explanation. Possible reasons for this condition to be true are: “Admitted” Possible reasons for this condition to be false are: “InvalidParameters” “Waiting” Controllers should prefer to use the values of GatewayClassConditionReason for the corresponding Reason, where appropriate.

GatewayClassSpec

(Appears on: GatewayClass)

GatewayClassSpec reflects the configuration of a class of Gateways.

Field	Description
controller GatewayController	Controller is a domain/path string that indicates the controller that is managing Gateways of this class. Example: “acme.io/gateway-controller”. This field is not mutable and cannot be empty. The format of this field is DOMAIN “/” PATH, where DOMAIN is a valid Kubernetes name (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) and PATH is a valid HTTP path as defined by RFC 3986. Support: Core
parametersRef ParametersReference	(Optional) ParametersRef is a reference to a resource that contains the configuration parameters corresponding to the GatewayClass. This is optional if the controller does not require any additional configuration. 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, the GatewayClass’s “InvalidParameters” status condition will be true. Support: Custom
description string	(Optional) Description helps describe a GatewayClass with more details.

GatewayClassStatus

(Appears on: GatewayClass)

GatewayClassStatus is the current status for the GatewayClass.

Field	Description
conditions []Kubernetes meta/v1.Condition	(Optional) Conditions is the current status from the controller for this GatewayClass. Controllers should prefer to publish conditions using values of GatewayClassConditionType for the type of each Condition.

GatewayConditionReason (string alias)

GatewayConditionReason defines the set of reasons that explain why a particular Gateway condition type has been raised.

Value	Description
"AddressNotAssigned"	This reason is used with the “Ready” condition when the requested address has not been assigned to the Gateway. This reason can be used to express a range of circumstances, including (but not limited to) IPAM address exhaustion, invalid or unsupported address requests, or a named address not being found.
"ListenersNotReady"	This reason is used with the “Ready” condition when one or more Listeners are not ready to serve traffic.
"ListenersNotValid"	This reason is used with the “Ready” condition when one or more Listeners have an invalid or unsupported configuration and cannot be configured on the Gateway.
"NoResources"	This reason is used with the “Scheduled” condition when the Gateway is not scheduled because insufficient infrastructure resources are available.
"NoSuchGatewayClass"	This reason is used with the “Scheduled” condition when the Gateway is not scheduled because there is no controller that recognizes the GatewayClassName. This reason has been deprecated and will be removed in a future release.
"NotReconciled"	This reason is used with the “Scheduled” condition when been recently created and no controller has reconciled it yet.
"Ready"	This reason is used with the “Ready” condition when the condition is true.
"Scheduled"	This reason is used with the “Scheduled” condition when the condition is true.

GatewayConditionType (string alias)

GatewayConditionType is a type of condition associated with a Gateway. This type should be used with the GatewayStatus.Conditions field.

Value	Description
"Ready"	This condition is true when the Gateway is expected to be able to serve traffic. Note that this does not indicate that the Gateway configuration is current or even complete (e.g. the controller may still not have reconciled the latest version, or some parts of the configuration could be missing). If both the “ListenersNotValid” and “ListenersNotReady” reasons are true, the Gateway controller should prefer the “ListenersNotValid” reason. Possible reasons for this condition to be true are: “Ready” Possible reasons for this condition to be false are: “ListenersNotValid” “ListenersNotReady” “AddressNotAssigned” Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.
"Scheduled"	This condition is true when the controller managing the Gateway has scheduled the Gateway to the underlying network infrastructure. Possible reasons for this condition to be true are: “Scheduled” Possible reasons for this condition to be false are: “NotReconciled” “NoSuchGatewayClass” “NoResources” Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.

GatewayController (string alias)

(Appears on: GatewayClassSpec, RouteParentStatus)

GatewayController is the name of a Gateway API controller. It must be a domain prefixed path.

Valid values include:

• “example.com/bar”

Invalid values include:

• “example.com” - must include path
• “foo.example.com” - must include path

GatewaySpec

(Appears on: Gateway)

GatewaySpec defines the desired state of Gateway.

Not all possible combinations of options specified in the Spec are valid. Some invalid configurations can be caught synchronously via a webhook, but there are many cases that will require asynchronous signaling via the GatewayStatus block.

Field	Description
gatewayClassName string	GatewayClassName used for this Gateway. This is the name of a GatewayClass resource.
listeners []Listener	Listeners associated with this Gateway. Listeners define logical endpoints that are bound on this Gateway’s addresses. At least one Listener MUST be specified. An implementation MAY group Listeners by Port and then collapse each group of Listeners into a single Listener if the implementation determines that the Listeners in the group are “compatible”. An implementation MAY also group together and collapse compatible Listeners belonging to different Gateways. For example, an implementation might consider Listeners to be compatible with each other if all of the following conditions are met: Either each Listener within the group specifies the “HTTP” Protocol or each Listener within the group specifies either the “HTTPS” or “TLS” Protocol. Each Listener within the group specifies a Hostname that is unique within the group. As a special case, one Listener within a group may omit Hostname, in which case this Listener matches when no other Listener matches. If the implementation does collapse compatible Listeners, the hostname provided in the incoming client request MUST be matched to a Listener to find the correct set of Routes. The incoming hostname MUST be matched using the Hostname field for each Listener in order of most to least specific. That is, exact matches must be processed before wildcard matches. If this field specifies multiple Listeners that have the same Port value but are not compatible, the implementation must raise a “Conflicted” condition in the Listener status. Support: Core
addresses []GatewayAddress	(Optional) Addresses requested for this gateway. This is optional and behavior can depend on the GatewayClass. If a value is set in the spec and the requested address is invalid, the GatewayClass MUST indicate this in the associated entry in GatewayStatus.Addresses. If no Addresses are specified, the GatewayClass may schedule the Gateway in an implementation-defined manner, assigning an appropriate set of Addresses. The GatewayClass MUST bind all Listeners to every GatewayAddress that it assigns to the Gateway. Support: Core

GatewayStatus

(Appears on: Gateway)

GatewayStatus defines the observed state of Gateway.

Field	Description
addresses []GatewayAddress	(Optional) Addresses lists the IP addresses that have actually been bound to the Gateway. These addresses may differ from the addresses in the Spec, e.g. if the Gateway automatically assigns an address from a reserved pool. These addresses should all be of type “IPAddress”.
conditions []Kubernetes meta/v1.Condition	(Optional) Conditions describe the current conditions of the Gateway. Implementations should prefer to express Gateway conditions using the GatewayConditionType and GatewayConditionReason constants so that operators and tools can converge on a common vocabulary to describe Gateway state. Known condition types are: “Scheduled” “Ready”
listeners []ListenerStatus	(Optional) Listeners provide status for each unique listener port defined in the Spec.

GatewayTLSConfig

(Appears on: Listener)

GatewayTLSConfig describes a TLS configuration.

Field	Description
mode TLSModeType	(Optional) 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 certificateRef to be set. - 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. CertificateRef field is ignored in this mode. Support: Core
certificateRef SecretObjectReference	(Optional) CertificateRef is a reference to a Kubernetes object that contains a TLS certificate and private key. This certificate is used to establish a TLS handshake for requests that match the hostname of the associated listener. References to a resource in different namespace are invalid UNLESS there is a ReferencePolicy in the target namespace that allows the certificate to be attached. If a ReferencePolicy does not allow this reference, the “ResolvedRefs” condition MUST be set to false for this listener with the “InvalidCertificateRef” reason. This field is required when mode is set to “Terminate” (default) and optional otherwise. CertificateRef can reference a standard Kubernetes resource, i.e. Secret, or an implementation-specific custom resource. Support: Core (Kubernetes Secrets) Support: Implementation-specific (Other resource types)
options map[string]string	(Optional) Options are a list of key/value pairs to give extended options to the provider. There variation among providers as to how ciphersuites are expressed. If there is a common subset for expressing ciphers then it will make sense to loft that as a core API construct. Support: Implementation-specific

Group (string alias)

(Appears on: BackendObjectReference, LocalObjectReference, ParametersReference, ParentRef, PolicyTargetReference, ReferencePolicyFrom, ReferencePolicyTo, RouteGroupKind, SecretObjectReference)

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
• “networking.k8s.io”
• “foo.example.com”

Invalid values include:

• “example.com/bar” - “/” is an invalid character

HTTPBackendRef

(Appears on: HTTPRouteRule)

HTTPBackendRef defines how a HTTPRoute should forward an HTTP request.

Field	Description
BackendRef BackendRef	(Members of BackendRef are embedded into this type.) (Optional) BackendRef is a reference to a backend to forward matched requests to. If the referent cannot be found, this HTTPBackendRef is invalid and must be dropped from the Gateway. The controller must ensure the “ResolvedRefs” condition on the Gateway is set to status: true with the “DegradedRoutes” reason, and not configure this backend in the underlying implemenation. If there is a cross-namespace reference to an existing object that is not covered by a ReferencePolicy, the controller must ensure the “ResolvedRefs” condition on the Gateway is set to status: true, with the “RefNotPermitted” reason and not configure this backend in the underlying implementation. In either error case, the Message of the ResolvedRefs Condition should be used to provide more detail about the problem. Support: Custom
filters []HTTPRouteFilter	(Optional) Filters defined at this-level should be executed if and only if the request is being forwarded to the backend defined here. Support: Custom (For broader support of filters, use the Filters field in HTTPRouteRule.)

HTTPHeader

(Appears on: HTTPRequestHeaderFilter)

HTTPHeader represents an HTTP Header name and value as defined by RFC 7230.

Field	Description
name HTTPHeaderName	Name is the name of the HTTP Header to be matched. Name matching MUST be case insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). If multiple entries specify equivalent header names, only the first entry with an equivalent name MUST be considered for a match. Subsequent entries with an equivalent header name MUST be ignored. Due to the case-insensitivity of header names, “foo” and “Foo” are considered equivalent.
value string	Value is the value of HTTP Header to be matched.

HTTPHeaderMatch

(Appears on: HTTPRouteMatch)

HTTPHeaderMatch describes how to select a HTTP route by matching HTTP request headers.

Field	Description
type HeaderMatchType	(Optional) Type specifies how to match against the value of the header. Support: Core (Exact) Support: Custom (RegularExpression, ImplementationSpecific) Since RegularExpression PathType has custom conformance, implementations can support POSIX, PCRE or any other dialects of regular expressions. Please read the implementation’s documentation to determine the supported dialect.
name HTTPHeaderName	Name is the name of the HTTP Header to be matched. Name matching MUST be case insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2). If multiple entries specify equivalent header names, only the first entry with an equivalent name MUST be considered for a match. Subsequent entries with an equivalent header name MUST be ignored. Due to the case-insensitivity of header names, “foo” and “Foo” are considered equivalent. When a header is repeated in an HTTP request, it is implementation-specific behavior as to how this is represented. Generally, proxies should follow the guidance from the RFC: https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2.2 regarding processing a repeated header, with special handling for “Set-Cookie”.
value string	Value is the value of HTTP Header to be matched.

HTTPHeaderName (string alias)

(Appears on: HTTPHeader, HTTPHeaderMatch)

HTTPHeaderName is the name of an HTTP header.

Valid values include:

• “Authorization”
• “Set-Cookie”

Invalid values include:

• ”:method” - “:” is an invalid character. This means that pseudo headers are not currently supported by this type.
• ”/invalid” - “/” is an invalid character

HTTPMethod (string alias)

(Appears on: HTTPRouteMatch)

HTTPMethod describes how to select a HTTP route by matching the HTTP method as defined by RFC 7231 and RFC 5789. The value is expected in upper case.

Value	Description
"CONNECT"
"DELETE"
"GET"
"HEAD"
"OPTIONS"
"PATCH"
"POST"
"PUT"
"TRACE"

HTTPPathMatch

(Appears on: HTTPRouteMatch)

HTTPPathMatch describes how to select a HTTP route by matching the HTTP request path.

Field	Description
type PathMatchType	(Optional) Type specifies how to match against the path Value. Support: Core (Exact, Prefix) Support: Custom (RegularExpression, ImplementationSpecific) Since RegularExpression PathType has custom conformance, implementations can support POSIX, PCRE or any other dialects of regular expressions. Please read the implementation’s documentation to determine the supported dialect.
value string	(Optional) Value of the HTTP path to match against.

HTTPQueryParamMatch

(Appears on: HTTPRouteMatch)

HTTPQueryParamMatch describes how to select a HTTP route by matching HTTP query parameters.

Field	Description
type QueryParamMatchType	(Optional) Type specifies how to match against the value of the query parameter. Support: Extended (Exact) Support: Custom (RegularExpression, ImplementationSpecific) Since RegularExpression QueryParamMatchType has custom conformance, implementations can support POSIX, PCRE or any other dialects of regular expressions. Please read the implementation’s documentation to determine the supported dialect.
name string	Name is the name of the HTTP query param to be matched. This must be an exact string match. (See https://tools.ietf.org/html/rfc7230#section-2.7.3).
value string	Value is the value of HTTP query param to be matched.

HTTPRequestHeaderFilter

(Appears on: HTTPRouteFilter)

HTTPRequestHeaderFilter defines configuration for the RequestHeaderModifier filter.

Field	Description
set []HTTPHeader	(Optional) Set overwrites the request with the given header (name, value) before the action. Input: GET /foo HTTP/1.1 my-header: foo Config: set: {“my-header”: “bar”} Output: GET /foo HTTP/1.1 my-header: bar
add []HTTPHeader	(Optional) Add adds the given header(s) (name, value) to the request before the action. It appends to any existing values associated with the header name. Input: GET /foo HTTP/1.1 my-header: foo Config: add: {“my-header”: “bar”} Output: GET /foo HTTP/1.1 my-header: foo my-header: bar
remove []string	(Optional) Remove the given header(s) from the HTTP request before the action. The value of RemoveHeader is a list of HTTP header names. Note that the header names are case-insensitive (see https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). Input: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz Config: remove: [“my-header1”, “my-header3”] Output: GET /foo HTTP/1.1 my-header2: bar

HTTPRequestMirrorFilter

(Appears on: HTTPRouteFilter)

HTTPRequestMirrorFilter defines configuration for the RequestMirror filter.

Field

Description

backendRef BackendObjectReference

(Optional) BackendRef references a resource where mirrored requests are sent. If the referent cannot be found, this HTTPBackendRef is invalid and must be dropped from the Gateway. The controller must ensure the “ResolvedRefs” condition on the Gateway is set to status: true with the “DegradedRoutes” reason, and not configure this backend in the underlying implemenation. If there is a cross-namespace reference to an existing object that is not allowed by a ReferencePolicy, the controller must ensure the “ResolvedRefs” condition on the Gateway is set to status: true, with the “RefNotPermitted” reason and not configure this backend in the underlying implementation. In either error case, the Message of the ResolvedRefs Condition should be used to provide more detail about the problem. Support: Extended for Kubernetes Service Support: Custom for any other resource

HTTPRequestRedirect

(Appears on: HTTPRouteFilter)

HTTPRequestRedirect defines configuration for the RequestRedirect filter.

Field	Description
protocol string	(Optional) Protocol is the protocol to be used in the value of the Location header in the response. When empty, the protocol of the request is used. Support: Extended
hostname Hostname	(Optional) Hostname is the hostname to be used in the value of the Location header in the response. When empty, the hostname of the request is used. Support: Core
port PortNumber	(Optional) Port is the port to be used in the value of the Location header in the response. When empty, port (if specified) of the request is used. Support: Extended
statusCode int	(Optional) StatusCode is the HTTP status code to be used in response. Support: Core

HTTPRouteFilter

(Appears on: HTTPBackendRef, HTTPRouteRule)

HTTPRouteFilter defines additional processing steps that must be completed during the request or response lifecycle. HTTPRouteFilters are meant as an extension point to express additional processing that may be done in Gateway implementations. Some examples include request or response modification, implementing authentication strategies, rate-limiting, and traffic shaping. API guarantee/conformance is defined based on the type of the filter. TODO(hbagdi): re-render CRDs once controller-tools supports union tags: - https://github.com/kubernetes-sigs/controller-tools/pull/298 - https://github.com/kubernetes-sigs/controller-tools/issues/461

Field	Description
type HTTPRouteFilterType	Type identifies the type of filter to apply. As with other API fields, types are classified into three conformance levels: Core: Filter types and their corresponding configuration defined by “Support: Core” in this package, e.g. “RequestHeaderModifier”. All implementations must support core filters. Extended: Filter types and their corresponding configuration defined by “Support: Extended” in this package, e.g. “RequestMirror”. Implementers are encouraged to support extended filters. Custom: Filters that are defined and supported by specific vendors. In the future, filters showing convergence in behavior across multiple implementations will be considered for inclusion in extended or core conformance levels. Filter-specific configuration for such filters is specified using the ExtensionRef field. Type should be set to “ExtensionRef” for custom filters. Implementers are encouraged to define custom implementation types to extend the core API with implementation-specific behavior.
requestHeaderModifier HTTPRequestHeaderFilter	(Optional) RequestHeaderModifier defines a schema for a filter that modifies request headers. Support: Core
requestMirror HTTPRequestMirrorFilter	(Optional) RequestMirror defines a schema for a filter that mirrors requests. Support: Extended
requestRedirect HTTPRequestRedirect	(Optional) RequestRedirect defines a schema for a filter that redirects request. Support: Core
extensionRef LocalObjectReference	(Optional) ExtensionRef is an optional, implementation-specific extension to the “filter” behavior. For example, resource “myroutefilter” in group “networking.acme.io”). ExtensionRef MUST NOT be used for core and extended filters. Support: Implementation-specific

HTTPRouteFilterType (string alias)

(Appears on: HTTPRouteFilter)

HTTPRouteFilterType identifies a type of HTTPRoute filter.

Value	Description
"ExtensionRef"	HTTPRouteFilterExtensionRef should be used for configuring custom HTTP filters. Support in HTTPRouteRule: Custom Support in HTTPBackendRef: Custom
"RequestHeaderModifier"	HTTPRouteFilterRequestHeaderModifier can be used to add or remove an HTTP header from an HTTP request before it is sent to the upstream target. Support in HTTPRouteRule: Core Support in HTTPBackendRef: Extended
"RequestMirror"	HTTPRouteFilterRequestMirror can be used to mirror HTTP requests to a different backend. The responses from this backend MUST be ignored by the Gateway. Support in HTTPRouteRule: Extended Support in HTTPBackendRef: Extended
"RequestRedirect"	HTTPRouteFilterRequestRedirect can be used to redirect a request to another location. This filter can also be used for HTTP to HTTPS redirects. Support in HTTPRouteRule: Core Support in HTTPBackendRef: Extended

HTTPRouteMatch

(Appears on: HTTPRouteRule)

HTTPRouteMatch defines the predicate used to match requests to a given action. Multiple match types are ANDed together, i.e. the match will evaluate to true only if all conditions are satisfied.

For example, the match below will match a HTTP request only if its path starts with /foo AND it contains the version: "1" header:

match:
path:
value: "/foo"
headers:
values:
version: "1"

Field	Description
path HTTPPathMatch	(Optional) Path specifies a HTTP request path matcher. If this field is not specified, a default prefix match on the “/” path is provided.
headers []HTTPHeaderMatch	(Optional) Headers specifies HTTP request header matchers. Multiple match values are ANDed together, meaning, a request must match all the specified headers to select the route.
queryParams []HTTPQueryParamMatch	(Optional) QueryParams specifies HTTP query parameter matchers. Multiple match values are ANDed together, meaning, a request must match all the specified query parameters to select the route.
method HTTPMethod	(Optional) Method specifies HTTP method matcher. When specified, this route will be matched only if the request has the specified method. Support: Extended
extensionRef LocalObjectReference	(Optional) ExtensionRef is an optional, implementation-specific extension to the “match” behavior. For example, resource “myroutematcher” in group “networking.acme.io”. If the referent cannot be found, the rule is not included in the route. The controller should raise the “ResolvedRefs” condition on the Gateway with the “DegradedRoutes” reason. The gateway status for this route should be updated with a condition that describes the error more specifically. Support: Custom

HTTPRouteRule

(Appears on: HTTPRouteSpec)

HTTPRouteRule defines semantics for matching an HTTP request based on conditions, optionally executing additional processing steps, and forwarding the request to an API object.

Field	Description
matches []HTTPRouteMatch	(Optional) 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. For example, take the following matches configuration: matches: - path: value: "/foo" headers: values: version: "2" - path: value: "/v2/foo" For a request to match against this rule, a request should satisfy EITHER of the two conditions: path prefixed with /foo AND contains the header version: "2" path prefix of /v2/foo See the documentation for HTTPRouteMatch on how to specify multiple match conditions that should be ANDed together. If no matches are specified, the default is a prefix path match on “/”, which has the effect of matching every HTTP request. Each client request MUST map to a maximum of one route rule. If a request matches multiple rules, matching precedence MUST be determined in order of the following criteria, continuing on ties: The longest matching hostname. The longest matching path. The largest number of header matches. If ties still exist across multiple Routes, matching precedence MUST be determined in order of the following criteria, continuing on ties: 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”. The Route appearing first in alphabetical order by “/”. For example, foo/bar is given precedence over foo/baz. If 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.
filters []HTTPRouteFilter	(Optional) Filters define the filters that are applied to requests that match this rule. The effects of ordering of multiple behaviors are currently unspecified. This can change in the future based on feedback during the alpha stage. Conformance-levels at this level are defined based on the type of filter: ALL core filters MUST be supported by all implementations. Implementers are encouraged to support extended filters. Implementation-specific custom filters have no API guarantees across implementations. Specifying a core filter multiple times has unspecified or custom conformance. Support: Core
backendRefs []HTTPBackendRef	(Optional) BackendRefs defines the backend(s) where matching requests should be sent. If unspecified or invalid (refers to a non-existent resource or a Service with no endpoints), the rule performs no forwarding; if no filters are specified that would result in a response being sent, a HTTP 503 status code is returned. 503 responses must be sent so that the overall weight is respected; if an invalid backend is requested to have 80% of requests, then 80% of requests must get a 503 instead. Support: Core for Kubernetes Service Support: Custom for any other resource Support for weight: Core

HTTPRouteSpec

(Appears on: HTTPRoute)

HTTPRouteSpec defines the desired state of HTTPRoute

Field	Description
CommonRouteSpec CommonRouteSpec	(Members of CommonRouteSpec are embedded into this type.)
hostnames []Hostname	(Optional) Hostnames defines a set of hostname that should match against the HTTP Host header to select a HTTPRoute to process the request. Hostname is the fully qualified domain name of a network host, as defined by RFC 3986. Note the following deviations from the “host” part of the URI as defined in the RFC: IPs are not allowed. The : delimiter is not respected because ports are not allowed. Incoming requests are matched against the hostnames before the HTTPRoute rules. If no hostname is specified, traffic is routed based on the HTTPRouteRules. Requests will be matched against the Host field in the following order: If Hostname is precise, the request matches this rule if the HTTP Host header is equal to the Hostname. If Hostname is a wildcard, then the request matches this rule if the HTTP Host header is to equal to the suffix (removing the first label) of the wildcard rule. If Hostname is unspecified, empty, or *, then any request will match this route. If a hostname is specified by the Listener that the HTTPRoute is bound to, at least one hostname specified here must match the Listener specified hostname as per the rules above. Other hostnames will not affect processing of the route in that case. If no hostname is specified by the Listener, then that value will be treated as ‘*’, match any hostname, and so any hostname on this Route will match. If all hostnames do not match, then the HTTPRoute is not admitted, and the implementation must raise an ‘Admitted’ Condition with a status of false for that Listener. Examples: - A Listener with unspecified, empty, or * values for Hostname matches any HTTPRoute hostname. - A HTTPRoute with unspecified, empty, or * values for Hostname matches any Listener hostname. - A Listener with test.foo.com as the hostname matches only test.foo.com or *.foo.com. Any other hostnames present must be ignored. - A Listener with *.foo.com as hostname, all hostnames in the HTTPRoute must have any single label where the star is, and the rest of the hostname must match exactly. So, test.foo.com, *.foo.com or blog.foo.com match. test.blog.foo.com, test.bar.com, or bar.com do not. Hostnames that do not match will be ignored. Support: Core
rules []HTTPRouteRule	(Optional) Rules are a list of HTTP matchers, filters and actions.

HTTPRouteStatus

(Appears on: HTTPRoute)

HTTPRouteStatus defines the observed state of HTTPRoute.

Field	Description
RouteStatus RouteStatus	(Members of RouteStatus are embedded into this type.)

HeaderMatchType (string alias)

(Appears on: HTTPHeaderMatch)

HeaderMatchType specifies the semantics of how HTTP header values should be compared. Valid HeaderMatchType values are:

• “Exact”
• “RegularExpression”
• “ImplementationSpecific”

Value	Description
"Exact"
"ImplementationSpecific"
"RegularExpression"

Hostname (string alias)

(Appears on: HTTPRequestRedirect, HTTPRouteSpec, Listener, TLSRouteSpec)

Hostname is the fully qualified domain name of a network host, as defined by RFC 3986. Note the following deviations from the “host” part of the URI as defined in the RFC:

1. IP literals are not allowed.
2. The : delimiter is not respected because ports are not allowed.

Hostname can be “precise” which is a domain name without the terminating dot of a network host (e.g. “foo.example.com”) or “wildcard”, which is a domain name prefixed with a single wildcard label (e.g. *.example.com). The wildcard character * must appear by itself as the first DNS label and matches only a single label.

Note that as per RFC1035 and RFC1123, a label must consist of lower case alphanumeric characters or ‘-’, and must start and end with an alphanumeric character. No other punctuation is allowed.

Kind (string alias)

(Appears on: BackendObjectReference, LocalObjectReference, ParametersReference, ParentRef, PolicyTargetReference, ReferencePolicyFrom, ReferencePolicyTo, RouteGroupKind, SecretObjectReference)

Kind refers to a Kubernetes Kind.

Valid values include:

• “Service”
• “HTTPRoute”

Invalid values include:

• “invalid/kind” - “/” is an invalid character

Listener

(Appears on: GatewaySpec)

Listener embodies the concept of a logical endpoint where a Gateway can accept network connections. Each listener in a Gateway must have a unique combination of Hostname, Port, and Protocol. This will be enforced by a validating webhook.

Field	Description
name SectionName	Name is the name of the Listener. If more than one Listener is present each Listener MUST specify a name. The names of Listeners MUST be unique within a Gateway. Support: Core
hostname Hostname	(Optional) Hostname specifies the virtual hostname to match for protocol types that define this concept. When unspecified, “”, or *, all hostnames are matched. This field can be omitted for protocols that don’t require hostname based matching. For HTTPRoute objects, 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 admitted. For example, a Gateway with *.example.com would admit a Route that included foo.example.com as a hostname, but not a Route that only included foo.acme.io as a hostname. A Route that included both foo.example.com and foo.acme.io would be admitted, but the foo.acme.io hostname would be silently ignored. Support: Core
port PortNumber	Port is the network port. Multiple listeners may use the same port, subject to the Listener compatibility rules. Support: Core
protocol ProtocolType	Protocol specifies the network protocol this listener expects to receive. The GatewayClass MUST apply the Hostname match appropriately for each protocol: For the “TLS” protocol, the Hostname match MUST be applied to the SNI server name offered by the client. For the “HTTP” protocol, the Hostname match MUST be applied to the host portion of the effective request URI or the :authority pseudo-header For the “HTTPS” protocol, the Hostname match MUST be applied at both the TLS and HTTP protocol layers. Support: Core
tls GatewayTLSConfig	(Optional) TLS is the TLS configuration for the Listener. This field is required if the Protocol field is “HTTPS” or “TLS” and ignored otherwise. 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. Support: Core
routes ListenerRoutes	(Optional) Routes specifies which Routes may be attached to this Listener. Although a client request may technically 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. For example, the most specific HTTPRoute match is determined by the longest matching combination of hostname and path. 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 portions of a Route selected by this field should be supported. Invalid portions of a Route can be ignored (sometimes that will mean the full Route). If a portion of a Route transitions from valid to invalid, support for that portion of the Route should be dropped to ensure consistency. For example, even if a filter specified by a Route is invalid, the rest of the Route should still be supported. Support: Core

ListenerConditionReason (string alias)

ListenerConditionReason defines the set of reasons that explain why a particular Listener condition type has been raised.

Value	Description
"Attached"	This reason is used with the “Detached” condition when the condition is false.
"DegradedRoutes"	This reason is used with the “ResolvedRefs” condition when not all of the routes selected by this Listener could be configured. The specific reason for the degraded route should be indicated in the route’s .Status.Conditions field.
"HostnameConflict"	This reason is used with the “Conflicted” condition when the Listener conflicts with hostnames in other Listeners. For example, this reason would be used when multiple Listeners on the same port use * in the hostname field.
"Invalid"	This reason is used with the “Ready” condition when the Listener is syntactically or semantically invalid.
"InvalidCertificateRef"	This reason is used with the “ResolvedRefs” condition when the Listener has a TLS configuration with a TLS CertificateRef that is invalid or cannot be resolved.
"InvalidRoutesRef"	This reason is used with the “ResolvedRefs” condition when the Listener’s Routes selector or kind is invalid or cannot be resolved. Note that it is not an error for this selector to not resolve any Routes, and the “ResolvedRefs” status condition should not be raised in that case.
"NoConflicts"	This reason is used with the “Conflicted” condition when the condition is false.
"Pending"	This reason is used with the “Ready” condition when the Listener is not yet not online and ready to accept client traffic.
"PortUnavailable"	This reason is used with the “Detached” condition when the Listener requests a port that cannot be used on the Gateway.
"ProtocolConflict"	This reason is used with the “Conflicted” condition when multiple Listeners are specified with the same Listener port number, but have conflicting protocol specifications.
"Ready"	This reason is used with the “Ready” condition when the condition is true.
"RefNotPermitted"	This reason is used with the “ResolvedRefs” condition when one of the Listener’s Routes has a BackendRef to an object in another namespace, where the object in the other namespace does not have a ReferencePolicy explicitly allowing the reference.
"ResolvedRefs"	This reason is used with the “ResolvedRefs” condition when the condition is true.
"RouteConflict"	This reason is used with the “Conflicted” condition when the route resources selected for this Listener conflict with other specified properties of the Listener (e.g. Protocol). For example, a Listener that specifies “UDP” as the protocol but a route selector that resolves “TCPRoute” objects.
"UnsupportedAddress"	This reason is used with the “Detached” condition when the Listener could not be attached to the Gateway because the requested address is not supported.
"UnsupportedExtension"	This reason is used with the “Detached” condition when the controller detects that an implementation-specific Listener extension is being requested, but is not able to support the extension.
"UnsupportedProtocol"	This reason is used with the “Detached” condition when the Listener could not be attached to be Gateway because its protocol type is not supported.

ListenerConditionType (string alias)

ListenerConditionType is a type of condition associated with the listener. This type should be used with the ListenerStatus.Conditions field.

Value	Description
"Conflicted"	This condition indicates that the controller was unable to resolve conflicting specification requirements for this Listener. If a Listener is conflicted, its network port should not be configured on any network elements. Possible reasons for this condition to be true are: “HostnameConflict” “ProtocolConflict” “RouteConflict” Possible reasons for this condition to be false are: “NoConflicts” Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.
"Detached"	This condition indicates that, even though the listener is syntactically and semantically valid, the controller is not able to configure it on the underlying Gateway infrastructure. A Listener is specified as a logical requirement, but needs to be configured on a network endpoint (i.e. address and port) by a controller. The controller may be unable to attach the Listener if it specifies an unsupported requirement, or prerequisite resources are not available. Possible reasons for this condition to be true are: “PortUnavailable” “UnsupportedExtension” “UnsupportedProtocol” “UnsupportedAddress” Possible reasons for this condition to be false are: “Attached” Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.
"Ready"	This condition indicates whether the Listener has been configured on the Gateway. Possible reasons for this condition to be true are: “Ready” Possible reasons for this condition to be false are: “Invalid” “Pending” Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.
"ResolvedRefs"	This condition indicates whether the controller was able to resolve all the object references for the Listener. Possible reasons for this condition to be true are: “ResolvedRefs” Possible reasons for this condition to be false are: “DegradedRoutes” “InvalidCertificateRef” “InvalidRoutesRef” “RefNotPermitted” Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.

ListenerRoutes

(Appears on: Listener)

ListenerRoutes defines which Routes may be attached to this Listener.

Field	Description
namespaces RouteNamespaces	(Optional) Namespaces indicates which namespaces Routes may be attached to this Listener from. This is restricted to the namespace of this Gateway by default. Support: Core
kinds []RouteGroupKind	(Optional) 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 “InvalidRoutesRef” reason. Support: Core

ListenerStatus

(Appears on: GatewayStatus)

ListenerStatus is the status associated with a Listener.

Field	Description
name SectionName	Name is the name of the Listener. If the Gateway has more than one Listener present, each ListenerStatus MUST specify a name. The names of ListenerStatus objects MUST be unique within a Gateway.
supportedKinds []RouteGroupKind	SupportedKinds is the list indicating the Kinds supported by this listener. When this is not specified on the Listener, this MUST represent the kinds an implementation supports for the specified protocol. When there are kinds specified on the Listener, this MUST represent the intersection of those kinds and the kinds supported by the implementation for the specified protocol.
attachedRoutes int32	AttachedRoutes represents the total number of Routes that have been successfully attached to this Listener.
conditions []Kubernetes meta/v1.Condition	Conditions describe the current condition of this listener.

LocalObjectReference

(Appears on: HTTPRouteFilter, HTTPRouteMatch, TCPRouteMatch, TLSRouteMatch, UDPRouteMatch)

LocalObjectReference identifies an API object within the namespace of the referrer.

Field	Description
group Group	Group is the group of the referent. For example, “networking.k8s.io”. When unspecified (empty string), core API group is inferred.
kind Kind	Kind is kind of the referent. For example “HTTPRoute” or “Service”.
name string	Name is the name of the referent.

Namespace (string alias)

(Appears on: BackendObjectReference, ParametersReference, ParentRef, PolicyTargetReference, ReferencePolicyFrom, SecretObjectReference)

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

ParametersReference

(Appears on: GatewayClassSpec)

ParametersReference identifies an API object containing controller-specific configuration resource within the cluster.

Field	Description
group Group	Group is the group of the referent.
kind Kind	Kind is kind of the referent.
name string	Name is the name of the referent.
scope string	(Optional) Scope represents if the referent is a Cluster or Namespace scoped resource. This may be set to “Cluster” or “Namespace”.
namespace Namespace	(Optional) Namespace is the namespace of the referent. This field is required when scope is set to “Namespace” and ignored when scope is set to “Cluster”.

ParentRef

(Appears on: CommonRouteSpec, RouteParentStatus)

ParentRef identifies an API object (usually a Gateway) that can be considered a parent of this resource (usually a route). The only kind of parent resource with “Core” support is Gateway. This API may be extended in the future to support additional kinds of parent resources, such as HTTPRoute.

Field	Description
group Group	(Optional) Group is the group of the referent. Support: Core
kind Kind	(Optional) Kind is kind of the referent. Support: Core (Gateway) Support: Custom (Other Resources)
namespace Namespace	(Optional) Namespace is the namespace of the referent. When unspecified (or empty string), this will either be: local namespace of the route when scope is set to Namespace. no namespace when scope is set to Cluster. Support: Core
scope string	(Optional) Scope represents if this refers to a cluster or namespace scoped resource. This may be set to “Cluster” or “Namespace”. Support: Core (Namespace) Support: Custom (Cluster)
name string	Name is the name of the referent. Support: Core
sectionName SectionName	(Optional) SectionName is the name of a section within the target resource. In the following resources, SectionName is interpreted as the following: Gateway: Listener Name Implementations MAY choose to support attaching Routes to other resources. If that is the case, they MUST clearly document how SectionName is interpreted. When unspecified (empty string), this will reference the entire resource. For the purpose of status, an attachment is considered successful if at least one section in the parent resource accepts it. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway. Support: Core

PathMatchType (string alias)

(Appears on: HTTPPathMatch)

PathMatchType specifies the semantics of how HTTP paths should be compared. Valid PathMatchType values are:

• “Exact”
• “Prefix”
• “RegularExpression”
• “ImplementationSpecific”

Prefix and Exact paths must be syntactically valid:

• Must begin with the ‘/’ character
• Must not contain consecutive ‘/’ characters (e.g. /foo///, //).
• For prefix paths, a trailing ‘/’ character in the Path is ignored, e.g. /abc and /abc/ specify the same match.

Value	Description
"Exact"
"ImplementationSpecific"
"Prefix"
"RegularExpression"

PolicyTargetReference

PolicyTargetReference identifies an API object to apply policy to. This should be used as part of Policy resources that can target Gateway API resources. For more information on how this policy attachment model works, and a sample Policy resource, refer to the policy attachment documentation for Gateway API.

Field	Description
group Group	Group is the group of the target resource.
kind Kind	Kind is kind of the target resource.
name string	Name is the name of the target resource.
namespace Namespace	(Optional) Namespace is the namespace of the referent. When unspecified, the local namespace is inferred. Even when policy targets a resource in a different namespace, it MUST only apply to traffic originating from the same namespace as the policy.
className string	(Optional) ClassName is the name of the class this policy should apply to. When unspecified, the policy will apply to all classes that support it.

PortNumber (int32 alias)

(Appears on: BackendObjectReference, HTTPRequestRedirect, Listener)

PortNumber defines a network port.

ProtocolType (string alias)

(Appears on: Listener)

ProtocolType defines the application protocol accepted by a Listener. Implementations are not required to accept all the defined protocols. If an implementation does not support a specified protocol, it should raise a “Detached” condition for the affected Listener with a reason of “UnsupportedProtocol”.

Core ProtocolType values are listed in the table below.

Implementations can define their own protocols if a core ProtocolType does not exist. Such definitions must use prefixed name, such as mycompany.com/my-custom-protocol. Un-prefixed names are reserved for core protocols. Any protocol defined by implementations will fall under custom conformance.

Value	Description
"HTTP"	Accepts cleartext HTTP/1.1 sessions over TCP.
"HTTPS"	Accepts HTTP/1.1 or HTTP/2 sessions over TLS.
"TCP"	Accepts TCP sessions.
"TLS"	Accepts TLS sessions over TCP.
"UDP"	Accepts UDP packets.

QueryParamMatchType (string alias)

(Appears on: HTTPQueryParamMatch)

QueryParamMatchType specifies the semantics of how HTTP query parameter values should be compared. Valid QueryParamMatchType values are:

• “Exact”
• “RegularExpression”
• “ImplementationSpecific”

Value	Description
"Exact"
"ImplementationSpecific"
"RegularExpression"

ReferencePolicyFrom

(Appears on: ReferencePolicySpec)

ReferencePolicyFrom describes trusted namespaces and kinds.

Field	Description
group Group	Group is the group of the referent. When empty, the “core” API group is inferred. Support: Core
kind Kind	Kind is the kind of the referent. Although implementations may support additional resources, the following Route types are part of the “Core” support level for this field: HTTPRoute TCPRoute TLSRoute UDPRoute
namespace Namespace	Namespace is the namespace of the referent. Support: Core

ReferencePolicySpec

(Appears on: ReferencePolicy)

ReferencePolicySpec identifies a cross namespace relationship that is trusted for Gateway API.

Field	Description
from []ReferencePolicyFrom	From describes the trusted namespaces and kinds that can reference the resources described in “To”. Each entry in this list must be considered to be an additional place that references can be valid from, or to put this another way, entries must be combined using OR. Support: Core
to []ReferencePolicyTo	To describes the resources that may be referenced by the resources described in “From”. Each entry in this list must be considered to be an additional place that references can be valid to, or to put this another way, entries must be combined using OR. Support: Core

ReferencePolicyTo

(Appears on: ReferencePolicySpec)

ReferencePolicyTo describes what Kinds are allowed as targets of the references.

Field	Description
group Group	Group is the group of the referent. When empty, the “core” API group is inferred. Support: Core
kind Kind	Kind is the kind of the referent. Although implementations may support additional resources, the following types are part of the “Core” support level for this field: Service

RouteConditionType (string alias)

RouteConditionType is a type of condition for a route.

Value	Description
"Admitted"	This condition indicates whether the route has been admitted or rejected by a Gateway, and why.

RouteGroupKind

(Appears on: ListenerRoutes, ListenerStatus)

RouteGroupKind indicates the group and kind of a Route resource.

Field	Description
group Group	(Optional) Group is the group of the Route.
kind Kind	Kind is the kind of the Route.

RouteNamespaces

(Appears on: ListenerRoutes)

RouteNamespaces indicate which namespaces Routes should be selected from.

Field	Description
from RouteSelectType	(Optional) From indicates where Routes will be selected for this Gateway. Possible values are: * All: Routes in all namespaces may be used by this Gateway. * Selector: Routes in namespaces selected by the selector may be used by this Gateway. * Same: Only Routes in the same namespace may be used by this Gateway. Support: Core
selector Kubernetes meta/v1.LabelSelector	(Optional) Selector must be specified when From is set to “Selector”. In that case, only Routes in Namespaces matching this Selector will be selected by this Gateway. This field is ignored for other values of “From”. Support: Core

RouteParentStatus

(Appears on: RouteStatus)

RouteParentStatus describes the status of a route with respect to an associated Parent.

Field	Description
parentRef ParentRef	ParentRef corresponds with a ParentRef in the spec that this RouteParentStatus struct describes the status of.
controller GatewayController	Controller is a domain/path string that indicates the controller that wrote this status. This corresponds with the controller field on GatewayClass. Example: “acme.io/gateway-controller”. The format of this field is DOMAIN “/” PATH, where DOMAIN and PATH are valid Kubernetes names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
conditions []Kubernetes meta/v1.Condition	Conditions describes the status of the route with respect to the Gateway. The “Admitted” condition must always be specified by controllers to indicate whether the route has been admitted or rejected by the Gateway, and why. Note that the route’s availability is also subject to the Gateway’s own status conditions and listener status.

RouteSelectType (string alias)

(Appears on: RouteNamespaces)

RouteSelectType specifies where Routes should be selected by a Gateway.

Value	Description
"All"	Routes in all namespaces may be used by this Gateway.
"Same"	Only Routes in the same namespace as the Gateway may be used by this Gateway.
"Selector"	Only Routes in namespaces selected by the selector may be used by this Gateway.

RouteStatus

(Appears on: HTTPRouteStatus, TCPRouteStatus, TLSRouteStatus, UDPRouteStatus)

RouteStatus defines the observed state that is required across all route types.

Field

Description

parents []RouteParentStatus

Parents is a list of parent resources (usually Gateways) that are associated with the route, and the status of the route with respect to each parent. When this route attaches to a parent, the controller that manages the parent must add an entry to this list when the controller first sees the route and should update the entry as appropriate when the route or gateway is modified. A maximum of 32 Gateways will be represented in this list. An empty list means the route has not been attached to any Gateway.

SecretObjectReference

(Appears on: GatewayTLSConfig)

SecretObjectReference identifies an API object including its namespace, defaulting to Secret.

Field	Description
group Group	(Optional) Group is the group of the referent. For example, “networking.k8s.io”. When unspecified (empty string), core API group is inferred.
kind Kind	(Optional) Kind is kind of the referent. For example “HTTPRoute” or “Service”.
name string	Name is the name of the referent.
namespace Namespace	(Optional) Namespace is the namespace of the backend. When unspecified, the local namespace is inferred. Note that when a namespace is specified, a ReferencePolicy object is required in the referent namespace to allow that namespace’s owner to accept the reference. See the ReferencePolicy documentation for details. Support: Core

SectionName (string alias)

(Appears on: Listener, ListenerStatus, ParentRef)

SectionName is the name of a section in a Kubernetes resource. It must be 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:

• “example.com”
• “foo.example.com”

Invalid values include:

• “example.com/bar” - “/” is an invalid character

TCPRouteMatch

(Appears on: TCPRouteRule)

TCPRouteMatch defines the predicate used to match connections to a given action.

Field

Description

extensionRef LocalObjectReference

(Optional) ExtensionRef is an optional, implementation-specific extension to the “match” behavior. For example, resource “mytcproutematcher” in group “networking.acme.io”. If the referent cannot be found, the rule is not included in the route. The controller should raise the “ResolvedRefs” condition on the Gateway with the “DegradedRoutes” reason. The gateway status for this route should be updated with a condition that describes the error more specifically. Support: Custom

TCPRouteRule

(Appears on: TCPRouteSpec)

TCPRouteRule is the configuration for a given rule.

Field	Description
matches []TCPRouteMatch	(Optional) Matches define conditions used for matching the rule against incoming TCP connections. Each match is independent, i.e. this rule will be matched if any one of the matches is satisfied. If unspecified (i.e. empty), this Rule will match all requests for the associated Listener. Each client request MUST map to a maximum of one route rule. If a request matches multiple rules, matching precedence MUST be determined in order of the following criteria, continuing on ties: The most specific match specified by ExtensionRef. Each implementation that supports ExtensionRef may have different ways of determining the specificity of the referenced extension. If ties still exist across multiple Routes, matching precedence MUST be determined in order of the following criteria, continuing on ties: 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”. The Route appearing first in alphabetical order by “/”. For example, foo/bar is given precedence over foo/baz. If 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.
backendRefs []BackendRef	BackendRefs defines the backend(s) where matching requests should be sent. If unspecified or invalid (refers to a non-existent resource or a Service with no endpoints), the rule performs no forwarding; if no filters are specified that would result in a response being sent, the underlying implementation must actively reject connection attempts to this backend. Connection rejections must respect weight; if an invalid backend is requested to have 80% of connections, then 80% of connections must be rejected instead. Support: Core for Kubernetes Service Support: Custom for any other resource Support for weight: Extended

TCPRouteSpec

(Appears on: TCPRoute)

TCPRouteSpec defines the desired state of TCPRoute

Field	Description
CommonRouteSpec CommonRouteSpec	(Members of CommonRouteSpec are embedded into this type.)
rules []TCPRouteRule	Rules are a list of TCP matchers and actions.

TCPRouteStatus

(Appears on: TCPRoute)

TCPRouteStatus defines the observed state of TCPRoute

Field	Description
RouteStatus RouteStatus	(Members of RouteStatus are embedded into this type.)

TLSModeType (string alias)

(Appears on: GatewayTLSConfig)

TLSModeType type defines how a Gateway handles TLS sessions.

Value	Description
"Passthrough"	In this mode, 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.
"Terminate"	In this mode, TLS session between the downstream client and the Gateway is terminated at the Gateway.

TLSRouteMatch

(Appears on: TLSRouteRule)

TLSRouteMatch defines the predicate used to match connections to a given action.

Field

Description

extensionRef LocalObjectReference

(Optional) ExtensionRef is an optional, implementation-specific extension to the “match” behavior. For example, resource “mytlsroutematcher” in group “networking.acme.io”. If the referent cannot be found, the rule is not included in the route. The controller should raise the “ResolvedRefs” condition on the Gateway with the “DegradedRoutes” reason. The gateway status for this route should be updated with a condition that describes the error more specifically. Support: Custom

TLSRouteRule

(Appears on: TLSRouteSpec)

TLSRouteRule is the configuration for a given rule.

Field	Description
matches []TLSRouteMatch	(Optional) Matches define conditions used for matching the rule against incoming TLS connections. Each match is independent, i.e. this rule will be matched if any one of the matches is satisfied. If unspecified (i.e. empty), this Rule will match all requests for the associated Listener. Each client request MUST map to a maximum of one route rule. If a request matches multiple rules, matching precedence MUST be determined in order of the following criteria, continuing on ties: The longest matching SNI. The longest matching precise SNI (without a wildcard). This means that “b.example.com” should be given precedence over “*.example.com”. The most specific match specified by ExtensionRef. Each implementation that supports ExtensionRef may have different ways of determining the specificity of the referenced extension. If ties still exist across multiple Routes, matching precedence MUST be determined in order of the following criteria, continuing on ties: 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”. The Route appearing first in alphabetical order by “/”. For example, foo/bar is given precedence over foo/baz. If 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.
backendRefs []BackendRef	BackendRefs defines the backend(s) where matching requests should be sent. If unspecified or invalid (refers to a non-existent resource or a Service with no endpoints), the rule performs no forwarding; if no filters are specified that would result in a response being sent, the underlying implementation must actively reject request attempts to this backend, by rejecting the connection or returning a 503 status code. Request rejections must respect weight; if an invalid backend is requested to have 80% of requests, then 80% of requests must be rejected instead. Support: Core for Kubernetes Service Support: Custom for any other resource Support for weight: Extended

TLSRouteSpec

(Appears on: TLSRoute)

TLSRouteSpec defines the desired state of a TLSRoute resource.

Field	Description
CommonRouteSpec CommonRouteSpec	(Members of CommonRouteSpec are embedded into this type.)
hostnames []Hostname	(Optional) Hostnames defines a set of SNI names that should match against the SNI attribute of TLS ClientHello message in TLS handshake. SNI can be “precise” which is a domain name without the terminating dot of a network host (e.g. “foo.example.com”) or “wildcard”, which is a domain name prefixed with a single wildcard label (e.g. *.example.com). The wildcard character * must appear by itself as the first DNS label and matches only a single label. You cannot have a wildcard label by itself (e.g. Host == *). Requests will be matched against the Host field in the following order: If SNI is precise, the request matches this rule if the SNI in ClientHello is equal to one of the defined SNIs. If SNI is a wildcard, then the request matches this rule if the SNI is to equal to the suffix (removing the first label) of the wildcard rule. If SNIs is unspecified, all requests associated with the gateway TLS listener will match. This can be used to define a default backend for a TLS listener. Support: Core
rules []TLSRouteRule	Rules are a list of TLS matchers and actions.

TLSRouteStatus

(Appears on: TLSRoute)

TLSRouteStatus defines the observed state of TLSRoute

Field	Description
RouteStatus RouteStatus	(Members of RouteStatus are embedded into this type.)

UDPRouteMatch

(Appears on: UDPRouteRule)

UDPRouteMatch defines the predicate used to match packets to a given action.

Field

Description

extensionRef LocalObjectReference

(Optional) ExtensionRef is an optional, implementation-specific extension to the “match” behavior. For example, resource “myudproutematcher” in group “networking.acme.io”. If the referent cannot be found, the rule is not included in the route. The controller should raise the “ResolvedRefs” condition on the Gateway with the “DegradedRoutes” reason. The gateway status for this route should be updated with a condition that describes the error more specifically. Support: Custom

UDPRouteRule

(Appears on: UDPRouteSpec)

UDPRouteRule is the configuration for a given rule.

Field	Description
matches []UDPRouteMatch	(Optional) Matches define conditions used for matching the rule against incoming UDP connections. Each match is independent, i.e. this rule will be matched if any one of the matches is satisfied. If unspecified (i.e. empty), this Rule will match all requests for the associated Listener. Each client request MUST map to a maximum of one route rule. If a request matches multiple rules, matching precedence MUST be determined in order of the following criteria, continuing on ties: The most specific match specified by ExtensionRef. Each implementation that supports ExtensionRef may have different ways of determining the specificity of the referenced extension. If ties still exist across multiple Routes, matching precedence MUST be determined in order of the following criteria, continuing on ties: 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”. The Route appearing first in alphabetical order by “/”. For example, foo/bar is given precedence over foo/baz. If 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.
backendRefs []BackendRef	BackendRefs defines the backend(s) where matching requests should be sent. If unspecified or invalid (refers to a non-existent resource or a Service with no endpoints), the rule performs no forwarding; if no filters are specified that would result in a response being sent, the underlying implementation must actively reject connection attempts to this backend. Connection rejections must respect weight; if an invalid backend is requested to have 80% of connections, then 80% of connections must be rejected instead. Support: Core for Kubernetes Service Support: Custom for any other resource Support for weight: Extended

UDPRouteSpec

(Appears on: UDPRoute)

UDPRouteSpec defines the desired state of UDPRoute.

Field	Description
CommonRouteSpec CommonRouteSpec	(Members of CommonRouteSpec are embedded into this type.)
rules []UDPRouteRule	Rules are a list of UDP matchers and actions.

UDPRouteStatus

(Appears on: UDPRoute)

UDPRouteStatus defines the observed state of UDPRoute.

Field	Description
RouteStatus RouteStatus	(Members of RouteStatus are embedded into this type.)

---

Generated with gen-crd-api-reference-docs.