Skip to content

Add distinct concept to Listener definition #2436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 12, 2023
Merged

Add distinct concept to Listener definition #2436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
97e9ac1
Add distinct concept to Listener definition
youngnick Sep 27, 2023
16ea07f
Fix PR comments
youngnick Sep 28, 2023
3abcca7
Fix further PR comments
youngnick Oct 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 79 additions & 43 deletions apis/v1beta1/gateway_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,49 +69,38 @@ type GatewaySpec struct {
// logical endpoints that are bound on this Gateway's addresses.
// At least one Listener MUST be specified.
//
// Each listener in a Gateway must have a unique combination of Hostname,
// Port, and Protocol.
// Each Listener in a set of Listeners (for example, in a single Gateway)
// MUST be _distinct_, in that a traffic flow MUST be able to be assigned to
// exactly one listener. (This section uses "set of Listeners" rather than
// "Listeners in a single Gateway" because implementations MAY merge configuration
// from multiple Gateways onto a single data plane, and these rules _also_
// apply in that case).
//
// Within the HTTP Conformance Profile, the below combinations of port and
// protocol are considered Core and MUST be supported:
// Practically, this means that each listener in a set MUST have a unique
// combination of Port, Protocol, and, if supported by the protocol, Hostname.
//
// 1. Port: 80, Protocol: HTTP
// 2. Port: 443, Protocol: HTTPS
// Some combinations of port, protocol, and TLS settings are considered
// Core support and MUST be supported by implementations based on their
// targeted conformance profile:
//
// Within the TLS Conformance Profile, the below combinations of port and
// protocol are considered Core and MUST be supported:
// HTTP Profile
//
// 1. Port: 443, Protocol: TLS
// 1. HTTPRoute, Port: 80, Protocol: HTTP
// 2. HTTPRoute, Port: 443, Protocol: HTTPS, TLS Mode: Terminate, TLS keypair provided
//
// Port and protocol combinations not listed above are considered Extended.
// TLS Profile
//
// A Gateway's Listeners are considered "compatible" if:
// 1. TLSRoute, Port: 443, Protocol: TLS, TLS Mode: Passthrough
//
// 1. The implementation can serve them in compliance with the Addresses
// requirement that all Listeners are available on all assigned
// addresses.
// 2. The implementation can match inbound requests to a single distinct
// Listener. When multiple Listeners share values for fields (for
// example, two Listeners with the same Port value), the implementation
// can can match requests to only one of the Listeners using other
// Listener fields.
// "Distinct" Listeners have the following property:
//
// Compatible combinations in Extended support are expected to vary across
// implementations. A combination that is compatible for one implementation
// may not be compatible for another.
// The implementation can match inbound requests to a single distinct
// Listener. When multiple Listeners share values for fields (for
// example, two Listeners with the same Port value), the implementation
// can match requests to only one of the Listeners using other
// Listener fields.
//
// If this field specifies multiple Listeners that are not compatible, the
// implementation MUST set the "Conflicted" condition in the Listener
// Status to "True".
//
// Implementations MAY choose to still accept a Gateway with conflicted
// Listeners if they accept a partial Listener set that contains no
// incompatible Listeners. They MUST set a "ListenersNotValid" condition
// the Gateway Status when the Gateway contains incompatible Listeners
// whether or not they accept the Gateway.
//
// For example, the following Listener scenarios may be compatible
// depending on implementation capabilities:
// For example, the following Listener scenarios are distinct:
//
// 1. Multiple Listeners with the same Port that all use the "HTTP"
// Protocol that all have unique Hostname values.
Expand All @@ -120,18 +109,68 @@ type GatewaySpec struct {
// 3. A mixture of "TCP" and "UDP" Protocol Listeners, where no Listener
// with the same Protocol has the same Port value.
//
// An implementation that cannot serve both TCP and UDP listeners on the same
// address, or cannot mix HTTPS and generic TLS listens on the same port
// would not consider those cases compatible.
// Some fields in the Listener struct have possible values that affect
// whether the Listener is distinct. Hostname is particularly relevant
// for HTTP or HTTPS protocols.
//
// When using the Hostname value to select between same-Port, same-Protocol
// Listeners, the Hostname value must be different on each Listener for the
// Listener to be distinct.
//
// When the Listeners are distinct based on Hostname, inbound request
// hostnames MUST match from the most specific to least specific Hostname
// values to choose the correct Listener and its associated set of Routes.
//
// Implementations using the Hostname value to select between same-Port
// Listeners MUST match inbound request hostnames from the most specific
// to least specific Hostname values to find the correct set of Routes.
// Exact matches must be processed before wildcard matches, and wildcard
// matches must be processed before fallback (empty Hostname value)
// matches. For example, `"foo.example.com"` takes precedence over
// `"*.example.com"`, and `"*.example.com"` takes precedence over `""`.
//
// Additionally, if there are multiple wildcard entries, more specific
// wildcard entries must be processed before less specific wildcard entries.
// For example, `"*.foo.example.com"` takes precedence over `"*.example.com"`.
// The precise definition here is that the higher the number of dots in the
// hostname to the right of the wildcard character, the higher the precedence.
//
// The wildcard character will match any number of characters _and dots_ to
// the left, however, so `"*.example.com"` will match both
// `"foo.bar.example.com"` _and_ `"bar.example.com"`.
//
// If a set of Listeners contains Listeners that are not distinct, then those
// Listeners are Conflicted, and the implementation MUST set the "Conflicted"
// condition in the Listener Status to "True".
//
// Implementations MAY choose to accept a Gateway with some Conflicted
// Listeners only if they only accept the partial Listener set that contains
// no Conflicted Listeners. To put this another way, implementations may
// accept a partial Listener set only if they throw out *all* the conflicting
// Listeners. No picking one of the conflicting listeners as the winner.
// This also means that the Gateway must have at least one non-conflicting
// Listener in this case, otherwise it violates the requirement that at
// least one Listener must be present.
Comment on lines +143 to +150
Copy link
Member

@robscott robscott Oct 11, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On first read I thought this guidance might be problematic for any implementations that revert to the last known good state. Thinking about it more, this just guards if you can accept a Gateway, but I don't think it prevents implementations from falling back to the last known good state instead of dropping Listeners. No action required here, just writing this thought process out for posterity in case this comes up again.

//
// The implementation MUST set a "ListenersNotValid" condition on the
// Gateway Status when the Gateway contains Conflicted Listeners whether or
// not they accept the Gateway. That Condition SHOULD clearly
// indicate in the Message which Listeners are conflicted, and which are
// Accepted. Additionally, the Listener status for those listeners SHOULD
// indicate which Listeners are conflicted and not Accepted.
//
// A Gateway's Listeners are considered "compatible" if:
//
// 1. They are distinct.
// 2. The implementation can serve them in compliance with the Addresses
// requirement that all Listeners are available on all assigned
// addresses.
//
// Compatible combinations in Extended support are expected to vary across
// implementations. A combination that is compatible for one implementation
// may not be compatible for another.
//
// For example, an implementation that cannot serve both TCP and UDP listeners
// on the same address, or cannot mix HTTPS and generic TLS listens on the same port
// would not consider those cases compatible, even though they are distinct.
//
// Note that requests SHOULD match at most one Listener. For example, if
// Listeners are defined for "foo.example.com" and "*.example.com", a
// request to "foo.example.com" SHOULD only be routed using routes attached
Expand Down Expand Up @@ -166,9 +205,6 @@ type GatewaySpec struct {
// other networking infrastructure, or some other address that traffic will
// be sent to.
//
// The .listener.hostname field is used to route traffic that has already
// arrived at the Gateway to the correct in-cluster destination.
//
Comment on lines -169 to -171
Copy link
Contributor Author

@youngnick youngnick Sep 27, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed this because it's just confusing to talk about hostname here - it's not relevant at all.

// If no Addresses are specified, the implementation MAY schedule the
// Gateway in an implementation-specific manner, assigning an appropriate
// set of Addresses.
Expand Down
Loading