diff --git a/apis/v1beta1/gateway_types.go b/apis/v1beta1/gateway_types.go index 559d6942e5..aa5d13a137 100644 --- a/apis/v1beta1/gateway_types.go +++ b/apis/v1beta1/gateway_types.go @@ -85,38 +85,55 @@ 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 - // 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. + // 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. 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 + // may not be compatible for another. + // + // 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: + // + // 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 listeners 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. For example, `"foo.example.com"` takes precedence over + // `"*.example.com"`, and `"*.example.com"` takes precedence over `""`. + // + // 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 2073c9ec14..5119fbc9a8 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml @@ -140,28 +140,43 @@ 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. 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 + 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 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. @@ -918,28 +933,43 @@ 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. 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 + 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 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 3c85717a14..801bb523b7 100644 --- a/config/crd/standard/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_gateways.yaml @@ -140,28 +140,43 @@ 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. 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 + 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 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. @@ -918,28 +933,43 @@ 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. 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 + 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 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.