From 4f7706c79e93dc81a36a99eab1bdbf2ab5dbc5be Mon Sep 17 00:00:00 2001 From: Travis Raines <571832+rainest@users.noreply.github.com> Date: Tue, 8 Aug 2023 16:03:28 -0700 Subject: [PATCH 1/9] Expand and clarify Listeners definition Explicitly define Listener compatibility as definitively routable and allowed on the same address by the implementation. Narrow language about collapsing compatible Listeners to mean assigning multiple Gateways the same addresses if their Listeners are compatible, Expand Listeners examples to include mixed TCP and UDP and indicate that they are not compatible if an implementation does not support that combination. Add language about Gateway-level conditions for incompatible Listeners. --- apis/v1beta1/gateway_types.go | 74 +++++++++++++++++++++-------------- 1 file changed, 44 insertions(+), 30 deletions(-) diff --git a/apis/v1beta1/gateway_types.go b/apis/v1beta1/gateway_types.go index 559d6942e5..f01449ca71 100644 --- a/apis/v1beta1/gateway_types.go +++ b/apis/v1beta1/gateway_types.go @@ -85,38 +85,52 @@ type GatewaySpec struct { // // Port and protocol combinations not listed above are considered Extended. // - // 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: - // - // 1. Either each Listener within the group specifies the "HTTP" - // Protocol or each Listener within the group specifies either - // the "HTTPS" or "TLS" Protocol. - // - // 2. Each Listener within the group specifies a Hostname that is unique - // within the group. - // - // 3. 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 + // A Gateway's Listeners are considered "compatible" if: + // + // 1. The implementation can serve them in compliance with the Addresses + // requirement that all Listeners are available on all assigned + // addresses. + // 2. No Listeners sharing the same Port share the same Hostname value, + // including the empty value, if this would prevent the implementation + // from matching an inbound request to a specific Listener. + // + // 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. + // + // If this field specifies multiple Listeners that are not compatible, the + // implementation MUST raise a true "Conflicted" condition in the Listener + // Status. + // + // 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: + // + // 1. Multiple Listeners with the same Port that all use the "HTTP" + // Protocol that all have unique Hostname values. + // 2. Multiple Listeners with the same Port that use either the "HTTPS" or + // "TLS" Protocol that all have unique Hostname values. + // 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 listens on the same + // address, or cannot mix HTTPS and generic TLS listens on the same port + // would not consider those cases compatible. + // + // 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. // - // 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. + // Implementations MAY collapse separate Gateways onto a single set of + // Addresses if the Listeners across all Gateways are compatible. // // Support: Core // From 9e00746972adb42fb2965e85786e36507b75fc8e Mon Sep 17 00:00:00 2001 From: Travis Raines <571832+rainest@users.noreply.github.com> Date: Fri, 11 Aug 2023 13:54:21 -0700 Subject: [PATCH 2/9] chore: run make generate --- .../gateway.networking.k8s.io_gateways.yaml | 112 +++++++++++------- .../gateway.networking.k8s.io_gateways.yaml | 112 +++++++++++------- 2 files changed, 136 insertions(+), 88 deletions(-) diff --git a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml index 2073c9ec14..1975c13d57 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml @@ -140,28 +140,40 @@ spec: the TLS Conformance Profile, the below combinations of port and protocol are considered Core and MUST be supported: \n 1. Port: 443, Protocol: TLS \n Port and protocol combinations not listed - above are considered Extended. \n 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. - \n For example, an implementation might consider Listeners to be - compatible with each other if all of the following conditions are - met: \n 1. Either each Listener within the group specifies the \"HTTP\" - Protocol or each Listener within the group specifies either the - \"HTTPS\" or \"TLS\" Protocol. \n 2. Each Listener within the group - specifies a Hostname that is unique within the group. \n 3. As a - special case, one Listener within a group may omit Hostname, in - which case this Listener matches when no other Listener matches. - \n 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. \n 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. \n - Support: Core" + above are considered Extended. \n A Gateway's Listeners are considered + \"compatible\" if: \n 1. The implementation can serve them in compliance + with the Addresses requirement that all Listeners are available + on all assigned addresses. 2. No Listeners sharing the same Port + share the same Hostname value, including the empty value, if this + would prevent the implementation from matching an inbound request + to a specific Listener. \n 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. + \n If this field specifies multiple Listeners that are not compatible, + the implementation MUST raise a true \"Conflicted\" condition in + the Listener Status. \n 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. \n For example, + the following Listener scenarios may be compatible depending on + implementation capabilities: \n 1. Multiple Listeners with the same + Port that all use the \"HTTP\" Protocol that all have unique Hostname + values. 2. Multiple Listeners with the same Port that use either + the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname + values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, + where no Listener with the same Protocol has the same Port value. + \n An implementation that cannot serve both TCP and UDP listens + on the same address, or cannot mix HTTPS and generic TLS listens + on the same port would not consider those cases compatible. \n 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. \n Implementations MAY collapse separate Gateways onto + a single set of Addresses if the Listeners across all Gateways are + compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. @@ -918,28 +930,40 @@ spec: the TLS Conformance Profile, the below combinations of port and protocol are considered Core and MUST be supported: \n 1. Port: 443, Protocol: TLS \n Port and protocol combinations not listed - above are considered Extended. \n 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. - \n For example, an implementation might consider Listeners to be - compatible with each other if all of the following conditions are - met: \n 1. Either each Listener within the group specifies the \"HTTP\" - Protocol or each Listener within the group specifies either the - \"HTTPS\" or \"TLS\" Protocol. \n 2. Each Listener within the group - specifies a Hostname that is unique within the group. \n 3. As a - special case, one Listener within a group may omit Hostname, in - which case this Listener matches when no other Listener matches. - \n 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. \n 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. \n - Support: Core" + above are considered Extended. \n A Gateway's Listeners are considered + \"compatible\" if: \n 1. The implementation can serve them in compliance + with the Addresses requirement that all Listeners are available + on all assigned addresses. 2. No Listeners sharing the same Port + share the same Hostname value, including the empty value, if this + would prevent the implementation from matching an inbound request + to a specific Listener. \n 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. + \n If this field specifies multiple Listeners that are not compatible, + the implementation MUST raise a true \"Conflicted\" condition in + the Listener Status. \n 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. \n For example, + the following Listener scenarios may be compatible depending on + implementation capabilities: \n 1. Multiple Listeners with the same + Port that all use the \"HTTP\" Protocol that all have unique Hostname + values. 2. Multiple Listeners with the same Port that use either + the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname + values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, + where no Listener with the same Protocol has the same Port value. + \n An implementation that cannot serve both TCP and UDP listens + on the same address, or cannot mix HTTPS and generic TLS listens + on the same port would not consider those cases compatible. \n 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. \n Implementations MAY collapse separate Gateways onto + a single set of Addresses if the Listeners across all Gateways are + compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. diff --git a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml index 3c85717a14..cbe9f5bf09 100644 --- a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml @@ -140,28 +140,40 @@ spec: the TLS Conformance Profile, the below combinations of port and protocol are considered Core and MUST be supported: \n 1. Port: 443, Protocol: TLS \n Port and protocol combinations not listed - above are considered Extended. \n 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. - \n For example, an implementation might consider Listeners to be - compatible with each other if all of the following conditions are - met: \n 1. Either each Listener within the group specifies the \"HTTP\" - Protocol or each Listener within the group specifies either the - \"HTTPS\" or \"TLS\" Protocol. \n 2. Each Listener within the group - specifies a Hostname that is unique within the group. \n 3. As a - special case, one Listener within a group may omit Hostname, in - which case this Listener matches when no other Listener matches. - \n 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. \n 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. \n - Support: Core" + above are considered Extended. \n A Gateway's Listeners are considered + \"compatible\" if: \n 1. The implementation can serve them in compliance + with the Addresses requirement that all Listeners are available + on all assigned addresses. 2. No Listeners sharing the same Port + share the same Hostname value, including the empty value, if this + would prevent the implementation from matching an inbound request + to a specific Listener. \n 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. + \n If this field specifies multiple Listeners that are not compatible, + the implementation MUST raise a true \"Conflicted\" condition in + the Listener Status. \n 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. \n For example, + the following Listener scenarios may be compatible depending on + implementation capabilities: \n 1. Multiple Listeners with the same + Port that all use the \"HTTP\" Protocol that all have unique Hostname + values. 2. Multiple Listeners with the same Port that use either + the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname + values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, + where no Listener with the same Protocol has the same Port value. + \n An implementation that cannot serve both TCP and UDP listens + on the same address, or cannot mix HTTPS and generic TLS listens + on the same port would not consider those cases compatible. \n 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. \n Implementations MAY collapse separate Gateways onto + a single set of Addresses if the Listeners across all Gateways are + compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. @@ -918,28 +930,40 @@ spec: the TLS Conformance Profile, the below combinations of port and protocol are considered Core and MUST be supported: \n 1. Port: 443, Protocol: TLS \n Port and protocol combinations not listed - above are considered Extended. \n 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. - \n For example, an implementation might consider Listeners to be - compatible with each other if all of the following conditions are - met: \n 1. Either each Listener within the group specifies the \"HTTP\" - Protocol or each Listener within the group specifies either the - \"HTTPS\" or \"TLS\" Protocol. \n 2. Each Listener within the group - specifies a Hostname that is unique within the group. \n 3. As a - special case, one Listener within a group may omit Hostname, in - which case this Listener matches when no other Listener matches. - \n 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. \n 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. \n - Support: Core" + above are considered Extended. \n A Gateway's Listeners are considered + \"compatible\" if: \n 1. The implementation can serve them in compliance + with the Addresses requirement that all Listeners are available + on all assigned addresses. 2. No Listeners sharing the same Port + share the same Hostname value, including the empty value, if this + would prevent the implementation from matching an inbound request + to a specific Listener. \n 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. + \n If this field specifies multiple Listeners that are not compatible, + the implementation MUST raise a true \"Conflicted\" condition in + the Listener Status. \n 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. \n For example, + the following Listener scenarios may be compatible depending on + implementation capabilities: \n 1. Multiple Listeners with the same + Port that all use the \"HTTP\" Protocol that all have unique Hostname + values. 2. Multiple Listeners with the same Port that use either + the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname + values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, + where no Listener with the same Protocol has the same Port value. + \n An implementation that cannot serve both TCP and UDP listens + on the same address, or cannot mix HTTPS and generic TLS listens + on the same port would not consider those cases compatible. \n 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. \n Implementations MAY collapse separate Gateways onto + a single set of Addresses if the Listeners across all Gateways are + compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. From 3bf6c14bc5c491fbdd750840adc09c50c99993f6 Mon Sep 17 00:00:00 2001 From: Travis Raines <571832+rainest@users.noreply.github.com> Date: Tue, 15 Aug 2023 15:06:26 -0700 Subject: [PATCH 3/9] Apply suggestions from code review Co-authored-by: Rob Scott --- apis/v1beta1/gateway_types.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apis/v1beta1/gateway_types.go b/apis/v1beta1/gateway_types.go index f01449ca71..546f794d0c 100644 --- a/apis/v1beta1/gateway_types.go +++ b/apis/v1beta1/gateway_types.go @@ -99,8 +99,8 @@ type GatewaySpec struct { // may not be compatible for another. // // If this field specifies multiple Listeners that are not compatible, the - // implementation MUST raise a true "Conflicted" condition in the Listener - // Status. + // 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 @@ -118,7 +118,7 @@ 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 listens on the same + // 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. // From 8a9acfbae0b9ec9bc494d94327dd6c915a85076a Mon Sep 17 00:00:00 2001 From: Travis Raines <571832+rainest@users.noreply.github.com> Date: Tue, 15 Aug 2023 16:02:06 -0700 Subject: [PATCH 4/9] pr: add hostname precedence example --- apis/v1beta1/gateway_types.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/apis/v1beta1/gateway_types.go b/apis/v1beta1/gateway_types.go index 546f794d0c..dee118aa7d 100644 --- a/apis/v1beta1/gateway_types.go +++ b/apis/v1beta1/gateway_types.go @@ -127,7 +127,8 @@ type GatewaySpec struct { // 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. + // matches. For example, `"foo.example.com"` takes precedence over + // `"*.example.com"`, and `"*.example.com"` takes precedence over `""`. // // Implementations MAY collapse separate Gateways onto a single set of // Addresses if the Listeners across all Gateways are compatible. From c390381239ff60c4df7f6456fae2b9f4e2cbac8f Mon Sep 17 00:00:00 2001 From: Travis Raines <571832+rainest@users.noreply.github.com> Date: Tue, 15 Aug 2023 16:18:01 -0700 Subject: [PATCH 5/9] chore: make generate --- .../gateway.networking.k8s.io_gateways.yaml | 100 +++++++++--------- .../gateway.networking.k8s.io_gateways.yaml | 100 +++++++++--------- 2 files changed, 104 insertions(+), 96 deletions(-) diff --git a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml index 1975c13d57..8dda8108ca 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml @@ -150,30 +150,32 @@ spec: are expected to vary across implementations. A combination that is compatible for one implementation may not be compatible for another. \n If this field specifies multiple Listeners that are not compatible, - the implementation MUST raise a true \"Conflicted\" condition in - the Listener Status. \n 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. \n For example, - the following Listener scenarios may be compatible depending on - implementation capabilities: \n 1. Multiple Listeners with the same - Port that all use the \"HTTP\" Protocol that all have unique Hostname - values. 2. Multiple Listeners with the same Port that use either - the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname - values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, - where no Listener with the same Protocol has the same Port value. - \n An implementation that cannot serve both TCP and UDP listens - on the same address, or cannot mix HTTPS and generic TLS listens - on the same port would not consider those cases compatible. \n 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. \n Implementations MAY collapse separate Gateways onto - a single set of Addresses if the Listeners across all Gateways are - compatible. \n Support: Core" + the implementation MUST set the \"Conflicted\" condition in the + Listener Status to \"True\". \n 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. \n For example, the following Listener scenarios may + be compatible depending on implementation capabilities: \n 1. Multiple + Listeners with the same Port that all use the \"HTTP\" Protocol + that all have unique Hostname values. 2. Multiple Listeners with + the same Port that use either the \"HTTPS\" or \"TLS\" Protocol + that all have unique Hostname values. 3. A mixture of \"TCP\" and + \"UDP\" Protocol Listeners, where no Listener with the same Protocol + has the same Port value. \n 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. \n 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 `\"\"`. \n Implementations MAY collapse separate + Gateways onto a single set of Addresses if the Listeners across + all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. @@ -940,30 +942,32 @@ spec: are expected to vary across implementations. A combination that is compatible for one implementation may not be compatible for another. \n If this field specifies multiple Listeners that are not compatible, - the implementation MUST raise a true \"Conflicted\" condition in - the Listener Status. \n 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. \n For example, - the following Listener scenarios may be compatible depending on - implementation capabilities: \n 1. Multiple Listeners with the same - Port that all use the \"HTTP\" Protocol that all have unique Hostname - values. 2. Multiple Listeners with the same Port that use either - the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname - values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, - where no Listener with the same Protocol has the same Port value. - \n An implementation that cannot serve both TCP and UDP listens - on the same address, or cannot mix HTTPS and generic TLS listens - on the same port would not consider those cases compatible. \n 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. \n Implementations MAY collapse separate Gateways onto - a single set of Addresses if the Listeners across all Gateways are - compatible. \n Support: Core" + the implementation MUST set the \"Conflicted\" condition in the + Listener Status to \"True\". \n 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. \n For example, the following Listener scenarios may + be compatible depending on implementation capabilities: \n 1. Multiple + Listeners with the same Port that all use the \"HTTP\" Protocol + that all have unique Hostname values. 2. Multiple Listeners with + the same Port that use either the \"HTTPS\" or \"TLS\" Protocol + that all have unique Hostname values. 3. A mixture of \"TCP\" and + \"UDP\" Protocol Listeners, where no Listener with the same Protocol + has the same Port value. \n 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. \n 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 `\"\"`. \n Implementations MAY collapse separate + Gateways onto a single set of Addresses if the Listeners across + all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. diff --git a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml index cbe9f5bf09..67026abcdd 100644 --- a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml @@ -150,30 +150,32 @@ spec: are expected to vary across implementations. A combination that is compatible for one implementation may not be compatible for another. \n If this field specifies multiple Listeners that are not compatible, - the implementation MUST raise a true \"Conflicted\" condition in - the Listener Status. \n 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. \n For example, - the following Listener scenarios may be compatible depending on - implementation capabilities: \n 1. Multiple Listeners with the same - Port that all use the \"HTTP\" Protocol that all have unique Hostname - values. 2. Multiple Listeners with the same Port that use either - the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname - values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, - where no Listener with the same Protocol has the same Port value. - \n An implementation that cannot serve both TCP and UDP listens - on the same address, or cannot mix HTTPS and generic TLS listens - on the same port would not consider those cases compatible. \n 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. \n Implementations MAY collapse separate Gateways onto - a single set of Addresses if the Listeners across all Gateways are - compatible. \n Support: Core" + the implementation MUST set the \"Conflicted\" condition in the + Listener Status to \"True\". \n 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. \n For example, the following Listener scenarios may + be compatible depending on implementation capabilities: \n 1. Multiple + Listeners with the same Port that all use the \"HTTP\" Protocol + that all have unique Hostname values. 2. Multiple Listeners with + the same Port that use either the \"HTTPS\" or \"TLS\" Protocol + that all have unique Hostname values. 3. A mixture of \"TCP\" and + \"UDP\" Protocol Listeners, where no Listener with the same Protocol + has the same Port value. \n 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. \n 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 `\"\"`. \n Implementations MAY collapse separate + Gateways onto a single set of Addresses if the Listeners across + all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. @@ -940,30 +942,32 @@ spec: are expected to vary across implementations. A combination that is compatible for one implementation may not be compatible for another. \n If this field specifies multiple Listeners that are not compatible, - the implementation MUST raise a true \"Conflicted\" condition in - the Listener Status. \n 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. \n For example, - the following Listener scenarios may be compatible depending on - implementation capabilities: \n 1. Multiple Listeners with the same - Port that all use the \"HTTP\" Protocol that all have unique Hostname - values. 2. Multiple Listeners with the same Port that use either - the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname - values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, - where no Listener with the same Protocol has the same Port value. - \n An implementation that cannot serve both TCP and UDP listens - on the same address, or cannot mix HTTPS and generic TLS listens - on the same port would not consider those cases compatible. \n 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. \n Implementations MAY collapse separate Gateways onto - a single set of Addresses if the Listeners across all Gateways are - compatible. \n Support: Core" + the implementation MUST set the \"Conflicted\" condition in the + Listener Status to \"True\". \n 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. \n For example, the following Listener scenarios may + be compatible depending on implementation capabilities: \n 1. Multiple + Listeners with the same Port that all use the \"HTTP\" Protocol + that all have unique Hostname values. 2. Multiple Listeners with + the same Port that use either the \"HTTPS\" or \"TLS\" Protocol + that all have unique Hostname values. 3. A mixture of \"TCP\" and + \"UDP\" Protocol Listeners, where no Listener with the same Protocol + has the same Port value. \n 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. \n 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 `\"\"`. \n Implementations MAY collapse separate + Gateways onto a single set of Addresses if the Listeners across + all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. From 3208a1fe9d92ad38dc1f9d5f73aa08a4ac0e881e Mon Sep 17 00:00:00 2001 From: Travis Raines <571832+rainest@users.noreply.github.com> Date: Mon, 21 Aug 2023 12:40:31 -0700 Subject: [PATCH 6/9] pr: rename collapse to merge --- apis/v1beta1/gateway_types.go | 4 ++-- .../experimental/gateway.networking.k8s.io_gateways.yaml | 8 ++++---- .../crd/standard/gateway.networking.k8s.io_gateways.yaml | 8 ++++---- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/apis/v1beta1/gateway_types.go b/apis/v1beta1/gateway_types.go index dee118aa7d..5e3c742608 100644 --- a/apis/v1beta1/gateway_types.go +++ b/apis/v1beta1/gateway_types.go @@ -130,8 +130,8 @@ type GatewaySpec struct { // matches. For example, `"foo.example.com"` takes precedence over // `"*.example.com"`, and `"*.example.com"` takes precedence over `""`. // - // Implementations MAY collapse separate Gateways onto a single set of - // Addresses if the Listeners across all Gateways are compatible. + // Implementations MAY merge separate Gateways onto a single set of + // Addresses if all Listeners across all Gateways are compatible. // // Support: Core // diff --git a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml index 8dda8108ca..682c4e1348 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml @@ -173,8 +173,8 @@ spec: 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 `\"\"`. \n Implementations MAY collapse separate - Gateways onto a single set of Addresses if the Listeners across + takes precedence over `\"\"`. \n Implementations MAY merge separate + Gateways onto a single set of Addresses if all Listeners across all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint @@ -965,8 +965,8 @@ spec: 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 `\"\"`. \n Implementations MAY collapse separate - Gateways onto a single set of Addresses if the Listeners across + takes precedence over `\"\"`. \n Implementations MAY merge separate + Gateways onto a single set of Addresses if all Listeners across all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint diff --git a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml index 67026abcdd..718dc5017b 100644 --- a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml @@ -173,8 +173,8 @@ spec: 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 `\"\"`. \n Implementations MAY collapse separate - Gateways onto a single set of Addresses if the Listeners across + takes precedence over `\"\"`. \n Implementations MAY merge separate + Gateways onto a single set of Addresses if all Listeners across all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint @@ -965,8 +965,8 @@ spec: 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 `\"\"`. \n Implementations MAY collapse separate - Gateways onto a single set of Addresses if the Listeners across + takes precedence over `\"\"`. \n Implementations MAY merge separate + Gateways onto a single set of Addresses if all Listeners across all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint From dd27869b7d4daa83f470ca9b11b88cbc229aeb03 Mon Sep 17 00:00:00 2001 From: Travis Raines <571832+rainest@users.noreply.github.com> Date: Mon, 28 Aug 2023 18:16:47 -0700 Subject: [PATCH 7/9] Use more generic rule for distinct Listeners --- apis/v1beta1/gateway_types.go | 8 +- .../gateway.networking.k8s.io_gateways.yaml | 74 ++++++++++--------- .../gateway.networking.k8s.io_gateways.yaml | 74 ++++++++++--------- 3 files changed, 81 insertions(+), 75 deletions(-) diff --git a/apis/v1beta1/gateway_types.go b/apis/v1beta1/gateway_types.go index 5e3c742608..aa5d13a137 100644 --- a/apis/v1beta1/gateway_types.go +++ b/apis/v1beta1/gateway_types.go @@ -90,9 +90,11 @@ type GatewaySpec struct { // 1. The implementation can serve them in compliance with the Addresses // requirement that all Listeners are available on all assigned // addresses. - // 2. No Listeners sharing the same Port share the same Hostname value, - // including the empty value, if this would prevent the implementation - // from matching an inbound request to a specific Listener. + // 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. // // Compatible combinations in Extended support are expected to vary across // implementations. A combination that is compatible for one implementation diff --git a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml index 682c4e1348..5119fbc9a8 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml @@ -143,24 +143,25 @@ spec: above are considered Extended. \n A Gateway's Listeners are considered \"compatible\" if: \n 1. The implementation can serve them in compliance with the Addresses requirement that all Listeners are available - on all assigned addresses. 2. No Listeners sharing the same Port - share the same Hostname value, including the empty value, if this - would prevent the implementation from matching an inbound request - to a specific Listener. \n 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. - \n If this field specifies multiple Listeners that are not compatible, - the implementation MUST set the \"Conflicted\" condition in the - Listener Status to \"True\". \n 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. \n For example, the following Listener scenarios may - be compatible depending on implementation capabilities: \n 1. Multiple - Listeners with the same Port that all use the \"HTTP\" Protocol - that all have unique Hostname values. 2. Multiple Listeners with - the same Port that use either the \"HTTPS\" or \"TLS\" Protocol + 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. \n 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. \n If this field specifies multiple Listeners + that are not compatible, the implementation MUST set the \"Conflicted\" + condition in the Listener Status to \"True\". \n 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. \n For example, the following Listener + scenarios may be compatible depending on implementation capabilities: + \n 1. Multiple Listeners with the same Port that all use the \"HTTP\" + Protocol that all have unique Hostname values. 2. Multiple Listeners + with the same Port that use either the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, where no Listener with the same Protocol has the same Port value. \n An implementation that cannot serve @@ -935,24 +936,25 @@ spec: above are considered Extended. \n A Gateway's Listeners are considered \"compatible\" if: \n 1. The implementation can serve them in compliance with the Addresses requirement that all Listeners are available - on all assigned addresses. 2. No Listeners sharing the same Port - share the same Hostname value, including the empty value, if this - would prevent the implementation from matching an inbound request - to a specific Listener. \n 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. - \n If this field specifies multiple Listeners that are not compatible, - the implementation MUST set the \"Conflicted\" condition in the - Listener Status to \"True\". \n 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. \n For example, the following Listener scenarios may - be compatible depending on implementation capabilities: \n 1. Multiple - Listeners with the same Port that all use the \"HTTP\" Protocol - that all have unique Hostname values. 2. Multiple Listeners with - the same Port that use either the \"HTTPS\" or \"TLS\" Protocol + 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. \n 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. \n If this field specifies multiple Listeners + that are not compatible, the implementation MUST set the \"Conflicted\" + condition in the Listener Status to \"True\". \n 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. \n For example, the following Listener + scenarios may be compatible depending on implementation capabilities: + \n 1. Multiple Listeners with the same Port that all use the \"HTTP\" + Protocol that all have unique Hostname values. 2. Multiple Listeners + with the same Port that use either the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, where no Listener with the same Protocol has the same Port value. \n An implementation that cannot serve diff --git a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml index 718dc5017b..801bb523b7 100644 --- a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml @@ -143,24 +143,25 @@ spec: above are considered Extended. \n A Gateway's Listeners are considered \"compatible\" if: \n 1. The implementation can serve them in compliance with the Addresses requirement that all Listeners are available - on all assigned addresses. 2. No Listeners sharing the same Port - share the same Hostname value, including the empty value, if this - would prevent the implementation from matching an inbound request - to a specific Listener. \n 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. - \n If this field specifies multiple Listeners that are not compatible, - the implementation MUST set the \"Conflicted\" condition in the - Listener Status to \"True\". \n 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. \n For example, the following Listener scenarios may - be compatible depending on implementation capabilities: \n 1. Multiple - Listeners with the same Port that all use the \"HTTP\" Protocol - that all have unique Hostname values. 2. Multiple Listeners with - the same Port that use either the \"HTTPS\" or \"TLS\" Protocol + 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. \n 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. \n If this field specifies multiple Listeners + that are not compatible, the implementation MUST set the \"Conflicted\" + condition in the Listener Status to \"True\". \n 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. \n For example, the following Listener + scenarios may be compatible depending on implementation capabilities: + \n 1. Multiple Listeners with the same Port that all use the \"HTTP\" + Protocol that all have unique Hostname values. 2. Multiple Listeners + with the same Port that use either the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, where no Listener with the same Protocol has the same Port value. \n An implementation that cannot serve @@ -935,24 +936,25 @@ spec: above are considered Extended. \n A Gateway's Listeners are considered \"compatible\" if: \n 1. The implementation can serve them in compliance with the Addresses requirement that all Listeners are available - on all assigned addresses. 2. No Listeners sharing the same Port - share the same Hostname value, including the empty value, if this - would prevent the implementation from matching an inbound request - to a specific Listener. \n 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. - \n If this field specifies multiple Listeners that are not compatible, - the implementation MUST set the \"Conflicted\" condition in the - Listener Status to \"True\". \n 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. \n For example, the following Listener scenarios may - be compatible depending on implementation capabilities: \n 1. Multiple - Listeners with the same Port that all use the \"HTTP\" Protocol - that all have unique Hostname values. 2. Multiple Listeners with - the same Port that use either the \"HTTPS\" or \"TLS\" Protocol + 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. \n 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. \n If this field specifies multiple Listeners + that are not compatible, the implementation MUST set the \"Conflicted\" + condition in the Listener Status to \"True\". \n 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. \n For example, the following Listener + scenarios may be compatible depending on implementation capabilities: + \n 1. Multiple Listeners with the same Port that all use the \"HTTP\" + Protocol that all have unique Hostname values. 2. Multiple Listeners + with the same Port that use either the \"HTTPS\" or \"TLS\" Protocol that all have unique Hostname values. 3. A mixture of \"TCP\" and \"UDP\" Protocol Listeners, where no Listener with the same Protocol has the same Port value. \n An implementation that cannot serve From 5af8b651f8a868fc76736038883311cd88d7c6f5 Mon Sep 17 00:00:00 2001 From: Travis Raines <571832+rainest@users.noreply.github.com> Date: Mon, 28 Aug 2023 18:35:21 -0700 Subject: [PATCH 8/9] Add advice for cascading matches --- apis/v1beta1/gateway_types.go | 7 ++++++ .../gateway.networking.k8s.io_gateways.yaml | 22 ++++++++++++++----- .../gateway.networking.k8s.io_gateways.yaml | 22 ++++++++++++++----- 3 files changed, 39 insertions(+), 12 deletions(-) diff --git a/apis/v1beta1/gateway_types.go b/apis/v1beta1/gateway_types.go index aa5d13a137..dcc9170efc 100644 --- a/apis/v1beta1/gateway_types.go +++ b/apis/v1beta1/gateway_types.go @@ -132,6 +132,13 @@ type GatewaySpec struct { // matches. For example, `"foo.example.com"` takes precedence over // `"*.example.com"`, and `"*.example.com"` takes precedence over `""`. // + // Implementations SHOULD NOT match requests to less specific Listeners if + // they exhaust attached routes on a more specific Listener. For example, a + // request for `subdomain.example.com/path` SHOULD NOT match an HTTPRoute + // attached to a Listener with Hostname `*.example.com` if there is a + // Listener with with Hostname `subdomain.example.com`, even if no routes + // on the second Listener match. + // // Implementations MAY merge separate Gateways onto a single set of // Addresses if all Listeners across all Gateways are compatible. // diff --git a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml index 5119fbc9a8..f04f1bb4e5 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml @@ -174,9 +174,14 @@ spec: 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 `\"\"`. \n Implementations MAY merge separate - Gateways onto a single set of Addresses if all Listeners across - all Gateways are compatible. \n Support: Core" + takes precedence over `\"\"`. \n Implementations SHOULD NOT match + requests to less specific Listeners if they exhaust attached routes + on a more specific Listener. For example, a request for `subdomain.example.com/path` + SHOULD NOT match an HTTPRoute attached to a Listener with Hostname + `*.example.com` if there is a Listener with with Hostname `subdomain.example.com`, + even if no routes on the second Listener match. \n Implementations + MAY merge separate Gateways onto a single set of Addresses if all + Listeners across all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. @@ -967,9 +972,14 @@ spec: 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 `\"\"`. \n Implementations MAY merge separate - Gateways onto a single set of Addresses if all Listeners across - all Gateways are compatible. \n Support: Core" + takes precedence over `\"\"`. \n Implementations SHOULD NOT match + requests to less specific Listeners if they exhaust attached routes + on a more specific Listener. For example, a request for `subdomain.example.com/path` + SHOULD NOT match an HTTPRoute attached to a Listener with Hostname + `*.example.com` if there is a Listener with with Hostname `subdomain.example.com`, + even if no routes on the second Listener match. \n Implementations + MAY merge separate Gateways onto a single set of Addresses if all + Listeners across all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. diff --git a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml index 801bb523b7..d710832d84 100644 --- a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml @@ -174,9 +174,14 @@ spec: 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 `\"\"`. \n Implementations MAY merge separate - Gateways onto a single set of Addresses if all Listeners across - all Gateways are compatible. \n Support: Core" + takes precedence over `\"\"`. \n Implementations SHOULD NOT match + requests to less specific Listeners if they exhaust attached routes + on a more specific Listener. For example, a request for `subdomain.example.com/path` + SHOULD NOT match an HTTPRoute attached to a Listener with Hostname + `*.example.com` if there is a Listener with with Hostname `subdomain.example.com`, + even if no routes on the second Listener match. \n Implementations + MAY merge separate Gateways onto a single set of Addresses if all + Listeners across all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. @@ -967,9 +972,14 @@ spec: 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 `\"\"`. \n Implementations MAY merge separate - Gateways onto a single set of Addresses if all Listeners across - all Gateways are compatible. \n Support: Core" + takes precedence over `\"\"`. \n Implementations SHOULD NOT match + requests to less specific Listeners if they exhaust attached routes + on a more specific Listener. For example, a request for `subdomain.example.com/path` + SHOULD NOT match an HTTPRoute attached to a Listener with Hostname + `*.example.com` if there is a Listener with with Hostname `subdomain.example.com`, + even if no routes on the second Listener match. \n Implementations + MAY merge separate Gateways onto a single set of Addresses if all + Listeners across all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. From c6912a51faa2ea4bdfcc88d442097d3890f4ad2c Mon Sep 17 00:00:00 2001 From: Travis Raines <571832+rainest@users.noreply.github.com> Date: Tue, 19 Sep 2023 15:44:46 -0700 Subject: [PATCH 9/9] Revert "Add advice for cascading matches" This reverts commit 5af8b651f8a868fc76736038883311cd88d7c6f5. --- apis/v1beta1/gateway_types.go | 7 ------ .../gateway.networking.k8s.io_gateways.yaml | 22 +++++-------------- .../gateway.networking.k8s.io_gateways.yaml | 22 +++++-------------- 3 files changed, 12 insertions(+), 39 deletions(-) diff --git a/apis/v1beta1/gateway_types.go b/apis/v1beta1/gateway_types.go index dcc9170efc..aa5d13a137 100644 --- a/apis/v1beta1/gateway_types.go +++ b/apis/v1beta1/gateway_types.go @@ -132,13 +132,6 @@ type GatewaySpec struct { // matches. For example, `"foo.example.com"` takes precedence over // `"*.example.com"`, and `"*.example.com"` takes precedence over `""`. // - // Implementations SHOULD NOT match requests to less specific Listeners if - // they exhaust attached routes on a more specific Listener. For example, a - // request for `subdomain.example.com/path` SHOULD NOT match an HTTPRoute - // attached to a Listener with Hostname `*.example.com` if there is a - // Listener with with Hostname `subdomain.example.com`, even if no routes - // on the second Listener match. - // // Implementations MAY merge separate Gateways onto a single set of // Addresses if all Listeners across all Gateways are compatible. // diff --git a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml index f04f1bb4e5..5119fbc9a8 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml @@ -174,14 +174,9 @@ spec: 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 `\"\"`. \n Implementations SHOULD NOT match - requests to less specific Listeners if they exhaust attached routes - on a more specific Listener. For example, a request for `subdomain.example.com/path` - SHOULD NOT match an HTTPRoute attached to a Listener with Hostname - `*.example.com` if there is a Listener with with Hostname `subdomain.example.com`, - even if no routes on the second Listener match. \n Implementations - MAY merge separate Gateways onto a single set of Addresses if all - Listeners across all Gateways are compatible. \n Support: Core" + takes precedence over `\"\"`. \n Implementations MAY merge separate + Gateways onto a single set of Addresses if all Listeners across + all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. @@ -972,14 +967,9 @@ spec: 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 `\"\"`. \n Implementations SHOULD NOT match - requests to less specific Listeners if they exhaust attached routes - on a more specific Listener. For example, a request for `subdomain.example.com/path` - SHOULD NOT match an HTTPRoute attached to a Listener with Hostname - `*.example.com` if there is a Listener with with Hostname `subdomain.example.com`, - even if no routes on the second Listener match. \n Implementations - MAY merge separate Gateways onto a single set of Addresses if all - Listeners across all Gateways are compatible. \n Support: Core" + takes precedence over `\"\"`. \n Implementations MAY merge separate + Gateways onto a single set of Addresses if all Listeners across + all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. diff --git a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml index d710832d84..801bb523b7 100644 --- a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml @@ -174,14 +174,9 @@ spec: 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 `\"\"`. \n Implementations SHOULD NOT match - requests to less specific Listeners if they exhaust attached routes - on a more specific Listener. For example, a request for `subdomain.example.com/path` - SHOULD NOT match an HTTPRoute attached to a Listener with Hostname - `*.example.com` if there is a Listener with with Hostname `subdomain.example.com`, - even if no routes on the second Listener match. \n Implementations - MAY merge separate Gateways onto a single set of Addresses if all - Listeners across all Gateways are compatible. \n Support: Core" + takes precedence over `\"\"`. \n Implementations MAY merge separate + Gateways onto a single set of Addresses if all Listeners across + all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections. @@ -972,14 +967,9 @@ spec: 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 `\"\"`. \n Implementations SHOULD NOT match - requests to less specific Listeners if they exhaust attached routes - on a more specific Listener. For example, a request for `subdomain.example.com/path` - SHOULD NOT match an HTTPRoute attached to a Listener with Hostname - `*.example.com` if there is a Listener with with Hostname `subdomain.example.com`, - even if no routes on the second Listener match. \n Implementations - MAY merge separate Gateways onto a single set of Addresses if all - Listeners across all Gateways are compatible. \n Support: Core" + takes precedence over `\"\"`. \n Implementations MAY merge separate + Gateways onto a single set of Addresses if all Listeners across + all Gateways are compatible. \n Support: Core" items: description: Listener embodies the concept of a logical endpoint where a Gateway accepts network connections.