ListenerSet

gateway.networking.k8s.io/v1

Gateway API Versionv1.6.0

ListenerSet defines a set of additional listeners to attach to an existing Gateway.
This resource provides a mechanism to merge multiple listeners into a single Gateway.

The parent Gateway must explicitly allow ListenerSet attachment through its AllowedListeners configuration. By default, Gateways do not allow ListenerSet attachment.

Routes can attach to a ListenerSet by specifying it as a parentRef, and can optionally target specific listeners using the sectionName field.

Policy Attachment:

  • Policies that attach to a ListenerSet apply to all listeners defined in that resource
  • Policies do not impact listeners in the parent Gateway
  • Different ListenerSets attached to the same Gateway can have different policies
  • If an implementation cannot apply a policy to specific listeners, it should reject the policy
ReferenceGrant Semantics: Gateway Integration:

​
---
config:
  theme: base
  themeVariables:
    secondaryColor: '#ffffff'
---
block
  columns 7

  classDef al_ref_box fill:#F2F2F2,stroke:#555;
  classDef al_mgw_box fill:#70991F,stroke:#555;
  classDef al_gwapi_box fill:#326CE5,stroke:#555;
  classDef al_std_box fill:#808B8F,stroke:#555;
  classDef al_self_box fill:#326CE5,stroke:#777,stroke-width:5px; 

  
  space:2
  block:Targets:3
    columns 3
    Gateway["<a href='../../../gateway-api/gateway/v1'>&nbsp;&nbsp;Gateway&nbsp;&nbsp;</a>"]
    space:2
    class Gateway al_gwapi_box
  end
  class Targets al_ref_box
  space:2
  
  space:7
  
  
  block:RefBy:1
    columns 1
    ReferenceGrant["<a href='../../../gateway-api/reference-grant/v1'>&nbsp;&nbsp;ReferenceGrant&nbsp;&nbsp;</a>"]
    class ReferenceGrant al_gwapi_box
  end
  class RefBy al_ref_box
  space:2
  
  
  ListenerSet["<a href='../../../gateway-api/listener-set/v1'>&nbsp;&nbsp;<b>ListenerSet</b>&nbsp;&nbsp;</a>"]
  class ListenerSet al_self_box
  
  space:3
  
  space:7
  
  space:2
  block:TargetedBy:3
    columns 3
    HTTPRoute["<a href='../../../gateway-api/http-route/v1'>&nbsp;&nbsp;HTTPRoute&nbsp;&nbsp;</a>"]
    space:2
    class HTTPRoute al_gwapi_box
  end
  class TargetedBy al_ref_box
  space:2
  

  ListenerSet -- "<i>attaches to</i>" --> Targets
  RefBy -- "<br><i>references</i>" --> ListenerSet
  TargetedBy -- "<i>attaches to</i>" --> ListenerSet
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: listener-set-example
spec:
  parentRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: gateway
    namespace: gateway-ns
  listeners:
    - name: additional-tls-listener
      port: 443
      hostname: additional-example.com
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: additional-example-cert

ListenerSet

Field Description Type Required Default Allowed Values
metadata defines the resource’s metadata ObjectMeta yes
spec defines the desired state of ListenerSet. object yes
status defines the current state of ListenerSet. object no

ListenerSet.spec

Field Description Type Required Default Allowed Values
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.		 object[] yes
parentRef

ParentRef references the Gateway that the listeners are attached to.

Supported kinds: Gateway

object yes

ListenerSet.spec.listeners[]

Field Description Type Required Default Allowed Values
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.		 object no
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.		 string no
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		 string yes
port is the network port. Multiple listeners may use the same port, subject to the Listener compatibility rules. int32 yes [1, 65535]
protocol

Protocol specifies the network protocol this listener expects to receive.

Supported protocols:

  • HTTP: Accepts cleartext HTTP/1.1 or HTTP/2 (H2C with prior knowledge) sessions over TCP.
  • HTTPS: Accepts HTTP/1.1 or HTTP/2 sessions over TLS.
  • microgateway.airlock.com/http3: Accepts HTTP/3 sessions over QUIC and UDP as well as HTTP/1.1 or HTTP/2 sessions over TLS.

string yes
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.		 object no

ListenerSet.spec.listeners[].allowedRoutes

Field Description Type Required Default Allowed Values
kinds

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.

Supported kinds: HTTPRoute

object[] no
namespaces indicates namespaces from which Routes may be attached to this Listener. This is restricted to the namespace of this Gateway by default. object no

ListenerSet.spec.listeners[].allowedRoutes.kinds[]

Field Description Type Required Default Allowed Values
group

Group is the group of the Route.

Supported groups: gateway.networking.k8s.io

string no gateway.networking.k8s.io
kind

Kind is the kind of the Route.

Supported kinds: HTTPRoute

string yes

ListenerSet.spec.listeners[].allowedRoutes.namespaces

Field Description Type Required Default Allowed Values
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.
string no Same All, Same, Selector
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”. LabelSelector no

ListenerSet.spec.listeners[].tls

Field Description Type Required Default Allowed Values
certificateRefs

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.

Note: Airlock Microgateway only supports a single TLS Secret reference per listener.

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.

Supported kinds: Secret

object[] no
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.
enum no Terminate Passthrough, Terminate
options

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.

Supported options:

  • microgateway.airlock.com/alpn-protocols: defines the application protocols advertised during TLS handshakes.
    The value must be a comma-separated, ordered list of ALPN protocol name preferences, with the most preferred protocol first (e.g., “h2,http/1.1”).
    Possible values are: “h2”, “http/1.1”.
    If not set, the list “h2,http/1.1” is used as a default.
    Note: If exactly one ALPN protocol is configured, all requests using a different protocol are rejected and only requests matching that protocol are accepted.
    Note: If the protocol type is set to microgateway.airlock.com/http3, this option applies only to the TLS listener and not to the QUIC listener.
  • microgateway.airlock.com/ciphers: defines the allowed cipher suites for TLS 1.0–1.2 (this setting has no effect when using TLS 1.3).
    The value must be a comma-separated list of cipher suites (e.g., “ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256”).
    If not set, the Envoy default cipher list is used.
  • microgateway.airlock.com/ecdhCurves: defines the elliptic curves allowed for ECDH key exchange.
    The value must be a comma-separated list of curve names ordered by preference (e.g., “X25519,P-256,P-384”).
    If not set, the list “X25519MLKEM768,X25519,P-256” is used as a default.
  • microgateway.airlock.com/maximumVersion: defines the maximum supported TLS protocol version.
    Possible values are: TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3.
    The maximum version must be greater than or equal to the minimum version.
  • microgateway.airlock.com/minimumVersion: defines the minimum supported TLS protocol version.
    Possible values are: TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3.
    The minimum version must be less than or equal to the maximum version.
  • microgateway.airlock.com/signatureAlgorithms: defines the allowed signature algorithms for TLS handshakes.
    The value must be a comma-separated list of algorithm names (e.g., “ecdsa_secp256r1_sha256,rsa_pss_rsae_sha256”).
    If not set, the Envoy default list of signature algorithms is used.

map[string]string no

ListenerSet.spec.listeners[].tls.certificateRefs[]

Field Description Type Required Default Allowed Values
group

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

Supported groups: ""

string no ""
kind

Kind is kind of the referent. For example “Secret”.

Supported kinds: Secret

string no Secret
name is the name of the referent. string yes
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.		 string no

ListenerSet.spec.parentRef

Field Description Type Required Default Allowed Values
group

Group is the group of the referent.

Supported groups: gateway.networking.k8s.io

string no gateway.networking.k8s.io
kind

Kind is kind of the referent. For example “Gateway”.

Supported kinds: Gateway

string no Gateway
name is the name of the referent. string yes
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. string no

ListenerSet.status

Field Description Type
conditions

describe the current conditions of the ListenerSet.

Possible conditions:

  • Accepted: This condition is true when the controller managing the ListenerSet is syntactically and semantically valid enough to produce some configuration in the underlying data plane. This does not indicate whether or not the configuration has been propagated to the data plane.

    Possible reasons for this condition to be True are:
    • “Accepted”
    Possible reasons for this condition to be False are:
    • “Invalid”
    • “NotAllowed”
    • “ParentNotAccepted”
    • “ListenersNotValid”
    Possible reasons for this condition to be Unknown are:
    • “Pending”
    Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.
  • Programmed: This condition indicates whether a ListenerSet has generated some configuration that is assumed to be ready soon in the underlying data plane.

    It is a positive-polarity summary condition, and so should always be present on the resource with ObservedGeneration set.

    It should be set to Unknown if the controller performs updates to the status before it has all the information it needs to be able to determine if the condition is true.

    Possible reasons for this condition to be True are:
    • “Programmed”
    Possible reasons for this condition to be False are:
    • “Invalid”
    • “ParentNotProgrammed”
    • “ListenersNotValid”
    Additional reasons for this condition to be False are influenced by child ListenerEntry conditions:
    • “PortUnavailable”
    Possible reasons for this condition to be Unknown are:
    • “Pending”
    Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.

Condition[]
listeners provide status for each unique listener port defined in the Spec. object[]

ListenerSet.status.listeners[]

Field Description Type
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.		 int32
conditions

Conditions describe the current condition of this listener.

Possible conditions:

  • Accepted: This condition indicates that the listener is syntactically and semantically valid, and that all features used in the listener’s spec are supported.

    In general, a Listener will be marked as Accepted when the supplied configuration will generate at least some data plane configuration.

    For example, a Listener with an unsupported protocol will never generate any data plane config, and so will have Accepted set to false. Conversely, a Listener that does not have any Routes will be able to generate data plane config, and so will have Accepted set to true.

    Possible reasons for this condition to be True are:
    • “Accepted”
    Possible reasons for this condition to be False are:
    • “PortUnavailable”
    • “UnsupportedProtocol”
    • “NoValidCACertificate”
    • “UnsupportedValue”
    Possible reasons for this condition to be Unknown are:
    • “Pending”
    Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.
  • 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”
    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.
    If this condition is not set, it is assumed that there are no conflicts.
  • OverlappingTLSConfig: This condition indicates that TLS configuration within this Listener conflicts with TLS configuration in another Listener on the same port.
    This could happen for two reasons:

    1) Overlapping Hostnames: Listener A matches *.example.com while Listener B matches foo.example.com.
    B) Overlapping Certificates: Listener A contains a certificate with a SAN for *.example.com, while Listener B contains a certificate with a SAN for foo.example.com.

    This overlapping TLS configuration can be particularly problematic when combined with HTTP connection coalescing. When clients reuse connections using this technique, it can have confusing interactions with Gateway API, such as TLS configuration for one Listener getting used for a request reusing an existing connection that would not be used if the same request was initiating a new connection.

    Controllers MUST detect the presence of overlapping hostnames and MAY detect the presence of overlapping certificates.

    This condition MUST be set on all Listeners with overlapping TLS config.
    For example, consider the following listener - hostname mapping:

    A: foo.example.com B: foo.example.org C: *.example.com

    In the above example, Listeners A and C would have overlapping hostnames and therefore this condition should be set for Listeners A and C, but not B.

    Possible reasons for this condition to be True are:
    • “OverlappingHostnames”
    • “OverlappingCertificates”
    If a controller supports checking for both possible reasons and finds that both are true, it SHOULD set the “OverlappingCertificates” Reason.

    This is a negative polarity condition and MUST NOT be set when it is False.

    Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.
  • Programmed: This condition indicates whether a Listener has generated some configuration that will soon be ready in the underlying data plane.

    It is a positive-polarity summary condition, and so should always be present on the resource with ObservedGeneration set.

    It should be set to Unknown if the controller performs updates to the status before it has all the information it needs to be able to determine if the condition is true.

    Possible reasons for this condition to be True are:
    • “Programmed”
    Possible reasons for this condition to be False are:
    • “Invalid”
    • “Pending”
    Possible reasons for this condition to be Unknown are:
    • “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:
    • “InvalidCertificateRef”
    • “InvalidRouteKinds”
    • “RefNotPermitted”
    • “InvalidCACertificateRef”
    • “InvalidCACertificateKind”
    Controllers may raise this condition with other reasons, but should prefer to use the reasons listed above to improve interoperability.

Condition[]
name is the name of the Listener that this status corresponds to. string
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.		 object[]

ListenerSet.status.listeners[].supportedKinds[]

Field Description Type
group is the group of the Route. string
kind is the kind of the Route. string