ListenerSet

gateway.networking.k8s.io / v1

apiVersion: gateway.networking.k8s.io/v1 kind: ListenerSet metadata: name: example

apiVersion string

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

kind string

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

metadata object

spec object required

Spec defines the desired state of ListenerSet.

listeners []object required

Listeners associated with this ListenerSet. Listeners define logical endpoints that are bound on this referenced parent Gateway's addresses. Listeners in a `Gateway` and their attached `ListenerSets` are concatenated as a list when programming the underlying infrastructure. Each listener name does not need to be unique across the Gateway and ListenerSets. See ListenerEntry.Name for more details. Implementations MUST treat the parent Gateway as having the merged list of all listeners from itself and attached ListenerSets using the following precedence: 1. "parent" Gateway 2. ListenerSet ordered by creation time (oldest first) 3. ListenerSet ordered alphabetically by "{namespace}/{name}". An implementation MAY reject listeners by setting the ListenerEntryStatus `Accepted` condition to False with the Reason `TooManyListeners` If a listener has a conflict, this will be reported in the Status.ListenerEntryStatus setting the `Conflicted` condition to True. Implementations SHOULD be cautious about what information from the parent or siblings are reported to avoid accidentally leaking sensitive information that the child would not otherwise have access to. This can include contents of secrets etc.

minItems: 1

maxItems: 64

allowedRoutes object

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.

kinds []object

Kinds specifies the groups and kinds of Routes that are allowed to bind to this Gateway Listener. When unspecified or empty, the kinds of Routes selected are determined using the Listener protocol. A RouteGroupKind MUST correspond to kinds of Routes that are compatible with the application protocol specified in the Listener's Protocol field. If an implementation does not support or recognize this resource type, it MUST set the "ResolvedRefs" condition to False for this Listener with the "InvalidRouteKinds" reason. Support: Core

maxItems: 8

group string

Group is the group of the Route.

pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

maxLength: 253

kind string required

Kind is the kind of the Route.

pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

minLength: 1

maxLength: 63

namespaces object

Namespaces indicates namespaces from which Routes may be attached to this Listener. This is restricted to the namespace of this Gateway by default. Support: Core

from string

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

enum: All, Selector, Same

selector object

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

matchExpressions []object

matchExpressions is a list of label selector requirements. The requirements are ANDed.

key string required

key is the label key that the selector applies to.

operator string required

operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.

values []string

values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.

matchLabels object

matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed.

filters object

Filters groups the pre-routing filter lists that run on every request accepted on this Listener, before route matching is performed. Filters is only valid when Protocol is `HTTP` or `HTTPS`; this constraint is enforced by CEL validation on the enclosing Listener struct. Support: Extended

requests []object

Implementations MUST execute the filters in the exact order they appear here and MUST NOT reorder them. If an implementation can not implement the filters in the order they are specified, the implementation MUST set the "Accepted" Listener condition to "false" with the "InvalidListenerFilterOrder" reason. Requests only apply to connections with a visible HTTP stream and metadata (Protocol=HTTP, or Protocol=HTTPS with TLS terminated at the Gateway). Requests may mutate inputs that route matching consumes (path, request headers, method, computed metadata), with the explicit exception of the `Host` and `:authority` headers. If a ListenerFilter attempts to modify either header, implementations MUST NOT allow that modification to take effect. Implementations SHOULD satisfy this by ignoring the mutation and continuing to process the request with the original value; they MAY instead fail the request with a 5xx response. Implementations MUST evaluate route matching exactly once after the last ListenerFilter has run. Requests MUST NOT be interpreted as changing which Listener handles the request. Listener selection is decided from inputs the client committed to before any pre-routing filter runs: TLS SNI (for HTTPS) or the request's initial Host header (for HTTP). Because filters cannot modify Host or :authority, the input to cleartext-HTTP Listener selection cannot change; Listener selection therefore does not need to be re-evaluated after pre-routing filters run, and MUST NOT be.

maxItems: 16

extensionRef object

LocalObjectReference identifies an API object within the namespace of the referrer. The API object must be valid in the cluster; the Group and Kind must be registered in the cluster for this reference to be valid. References to objects with invalid Group and Kind are not valid, and must be rejected by the implementation, with appropriate Conditions set on the containing object.

group string required

Group is the group of the referent. For example, "gateway.networking.k8s.io". When unspecified or empty string, core API group is inferred.

pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

maxLength: 253

kind string required

Kind is kind of the referent. For example "HTTPRoute" or "Service".

pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

minLength: 1

maxLength: 63

name string required

Name is the name of the referent.

minLength: 1

maxLength: 253

externalAuth object

HTTPExternalAuthFilter defines a filter that modifies requests by sending request details to an external authorization server. Support: Extended Feature Name: HTTPRouteExternalAuth

backendRef object required

BackendRef is a reference to a backend to send authorization requests to. The backend must speak the selected protocol (GRPC or HTTP) on the referenced port. If the backend service requires TLS, use BackendTLSPolicy to tell the implementation to supply the TLS details to be used to connect to that backend.

group string

Group is the group of the referent. For example, "gateway.networking.k8s.io". When unspecified or empty string, core API group is inferred.

pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

maxLength: 253

kind string

Kind is the Kubernetes resource kind of the referent. For example "Service". Defaults to "Service" when not specified. ExternalName services can refer to CNAME DNS records that may live outside of the cluster and as such are difficult to reason about in terms of conformance. They also may not be safe to forward to (see CVE-2021-25740 for more information). Implementations SHOULD NOT support ExternalName Services. Support: Core (Services with a type other than ExternalName) Support: Implementation-specific (Services with type ExternalName)

pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

minLength: 1

maxLength: 63

name string required

Name is the name of the referent.

minLength: 1

maxLength: 253

namespace string

Namespace is the namespace of the backend. When unspecified, the local namespace is inferred. Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. Support: Core

pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

minLength: 1

maxLength: 63

port integer

Port specifies the destination port number to use for this resource. Port is required when the referent is a Kubernetes Service. In this case, the port number is the service port number, not the target port. For other resources, destination port might be derived from the referent resource or this field.

format: int32

minimum: 1

maximum: 65535

forwardBody object

ForwardBody controls if requests to the authorization server should include the body of the client request; and if so, how big that body is allowed to be. It is expected that implementations will buffer the request body up to `forwardBody.maxSize` bytes. Bodies over that size must be rejected with a 4xx series error (413 or 403 are common examples), and fail processing of the filter. If unset, or `forwardBody.maxSize` is set to `0`, then the body will not be forwarded. Feature Name: HTTPRouteExternalAuthForwardBody

maxSize integer

MaxSize specifies how large in bytes the largest body that will be buffered and sent to the authorization server. If the body size is larger than `maxSize`, then the body sent to the authorization server must be truncated to `maxSize` bytes. Experimental note: This behavior needs to be checked against various dataplanes; it may need to be changed. See https://github.com/kubernetes-sigs/gateway-api/pull/4001#discussion_r2291405746 for more. If 0, the body will not be sent to the authorization server.

format: int32

minimum: 0

grpc object

GRPCAuthConfig contains configuration for communication with ext_authz protocol-speaking backends. If unset, implementations must assume the default behavior for each included field is intended.

allowedHeaders []string

AllowedRequestHeaders specifies what headers from the client request will be sent to the authorization server. If this list is empty, then all headers must be sent. If the list has entries, only those entries must be sent.

maxItems: 64

http object

HTTPAuthConfig contains configuration for communication with HTTP-speaking backends. If unset, implementations must assume the default behavior for each included field is intended.

allowedHeaders []string

AllowedRequestHeaders specifies what additional headers from the client request will be sent to the authorization server. The following headers must always be sent to the authorization server, regardless of this setting: * `Host` * `Method` * `Path` * `Content-Length` * `Authorization` If this list is empty, then only those headers must be sent. Note that `Content-Length` has a special behavior, in that the length sent must be correct for the actual request to the external authorization server - that is, it must reflect the actual number of bytes sent in the body of the request to the authorization server. So if the `forwardBody` stanza is unset, or `forwardBody.maxSize` is set to `0`, then `Content-Length` must be `0`. If `forwardBody.maxSize` is set to anything other than `0`, then the `Content-Length` of the authorization request must be set to the actual number of bytes forwarded.

maxItems: 64

allowedResponseHeaders []string

AllowedResponseHeaders specifies what headers from the authorization response will be copied into the request to the backend. If this list is empty, then all headers from the authorization server except Authority or Host must be copied.

maxItems: 64

path string

Path sets the prefix that paths from the client request will have added when forwarded to the authorization server. When empty or unspecified, no prefix is added. Valid values are the same as the "value" regex for path values in the `match` stanza, and the validation regex will screen out invalid paths in the same way. Even with the validation, implementations MUST sanitize this input before using it directly.

pattern: ^(?:[-A-Za-z0-9/._~!$&'()*+,;=:@]|[%][0-9a-fA-F]{2})+$

maxLength: 1024

protocol string required

ExternalAuthProtocol describes which protocol to use when communicating with an ext_authz authorization server. When this is set to GRPC, each backend must use the Envoy ext_authz protocol on the port specified in `backendRefs`. Requests and responses are defined in the protobufs explained at: https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto When this is set to HTTP, each backend must respond with a `200` status code in on a successful authorization. Any other code is considered an authorization failure. Feature Names: GRPC Support - HTTPRouteExternalAuthGRPC HTTP Support - HTTPRouteExternalAuthHTTP

enum: HTTP, GRPC

type string required

Type identifies which variant of the discriminated union below is populated. Uses the same union-discriminator pattern as HTTPRouteFilter and GRPCRouteFilter.

enum: ExternalAuth, ExtensionRef

hostname string

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

pattern: ^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

minLength: 1

maxLength: 253

name string required

Name is the name of the Listener. This name MUST be unique within a ListenerSet. Name is not required to be unique across a Gateway and ListenerSets. Routes can attach to a Listener by having a ListenerSet as a parentRef and setting the SectionName

pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

minLength: 1

maxLength: 253

port integer required

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

format: int32

minimum: 1

maximum: 65535

protocol string required

Protocol specifies the network protocol this listener expects to receive.

pattern: ^[a-zA-Z0-9]([-a-zA-Z0-9]*[a-zA-Z0-9])?$|[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9]+$

minLength: 1

maxLength: 255

tls object

TLS is the TLS configuration for the Listener. This field is required if the Protocol field is "HTTPS" or "TLS". It is invalid to set this field if the Protocol field is "HTTP", "TCP", or "UDP". The association of SNIs to Certificate defined in ListenerTLSConfig is defined based on the Hostname field for this listener. The GatewayClass MUST use the longest matching SNI out of all available certificates for any TLS handshake.

certificateRefs []object

CertificateRefs contains a series of references to Kubernetes objects that contains TLS certificates and private keys. These certificates are used to establish a TLS handshake for requests that match the hostname of the associated listener. A single CertificateRef to a Kubernetes Secret has "Core" support. Implementations MAY choose to support attaching multiple certificates to a Listener, but this behavior is implementation-specific. References to a resource in different namespace are invalid UNLESS there is a ReferenceGrant in the target namespace that allows the certificate to be attached. If a ReferenceGrant does not allow this reference, the "ResolvedRefs" condition MUST be set to False for this listener with the "RefNotPermitted" reason. This field is required to have at least one element when the mode is set to "Terminate" (default) and is optional otherwise. CertificateRefs can reference to standard Kubernetes resources, i.e. Secret, or implementation-specific custom resources. Support: Core - A single reference to a Kubernetes Secret of type kubernetes.io/tls Support: Implementation-specific (More than one reference or other resource types)

maxItems: 64

group string

Group is the group of the referent. For example, "gateway.networking.k8s.io". When unspecified or empty string, core API group is inferred.

pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

maxLength: 253

kind string

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

pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

minLength: 1

maxLength: 63

name string required

Name is the name of the referent.

minLength: 1

maxLength: 253

namespace string

Namespace is the namespace of the referenced object. When unspecified, the local namespace is inferred. Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details. Support: Core

pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

minLength: 1

maxLength: 63

mode string

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

enum: Terminate, Passthrough

options object

Options are a list of key/value pairs to enable extended TLS configuration for each implementation. For example, configuring the minimum TLS version or supported cipher suites. A set of common keys MAY be defined by the API in the future. To avoid any ambiguity, implementation-specific definitions MUST use domain-prefixed names, such as `example.com/my-custom-option`. Un-prefixed names are reserved for key names defined by Gateway API. Support: Implementation-specific

parentRef object required

ParentRef references the Gateway that the listeners are attached to.

group string

Group is the group of the referent.

pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

maxLength: 253

kind string

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

pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

minLength: 1

maxLength: 63

name string required

Name is the name of the referent.

minLength: 1

maxLength: 253

namespace string

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.

pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

minLength: 1

maxLength: 63

status object

Status defines the current state of ListenerSet.

conditions []object

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"

maxItems: 8

lastTransitionTime string required

lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

format: date-time

message string required

message is a human readable message indicating details about the transition. This may be an empty string.

maxLength: 32768

observedGeneration integer

observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

format: int64

minimum: 0

reason string required

reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

minLength: 1

maxLength: 1024

status string required

status of the condition, one of True, False, Unknown.

enum: True, False, Unknown

type string required

type of condition in CamelCase or in foo.example.com/CamelCase.

pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

maxLength: 316

listeners []object

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

maxItems: 64

attachedRoutes integer required

AttachedRoutes represents the total number of Routes that have been successfully attached to this Listener. Successful attachment of a Route to a Listener is based solely on the combination of the AllowedRoutes field on the corresponding Listener and the Route's ParentRefs field. A Route is successfully attached to a Listener when it is selected by the Listener's AllowedRoutes field AND the Route has a valid ParentRef selecting the whole Gateway resource or a specific Listener as a parent resource (more detail on attachment semantics can be found in the documentation on the various Route kinds ParentRefs fields). Listener status does not impact successful attachment, i.e. the AttachedRoutes field count MUST be set for Listeners, even if the Accepted condition of an individual Listener is set to "False". The AttachedRoutes number represents the number of Routes with the Accepted condition set to "True" that have been attached to this Listener. Routes with any other value for the Accepted condition MUST NOT be included in this count. Uses for this field include troubleshooting Route attachment and measuring blast radius/impact of changes to a Listener.

format: int32

conditions []object required

Conditions describe the current condition of this listener.

maxItems: 8

lastTransitionTime string required

format: date-time

message string required

message is a human readable message indicating details about the transition. This may be an empty string.

maxLength: 32768

observedGeneration integer

format: int64

minimum: 0

reason string required

pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

minLength: 1

maxLength: 1024

status string required

status of the condition, one of True, False, Unknown.

enum: True, False, Unknown

type string required

type of condition in CamelCase or in foo.example.com/CamelCase.

pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

maxLength: 316

name string required

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

pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

minLength: 1

maxLength: 253

supportedKinds []object

SupportedKinds is the list indicating the Kinds supported by this listener. This MUST represent the kinds supported by an implementation 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

group string

Group is the group of the Route.

pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

maxLength: 253

kind string required

Kind is the kind of the Route.

pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$

minLength: 1

maxLength: 63

No matches. Try .spec.listeners for an exact path