Adding Changelog for v0.4.0

kubernetes-sigs · Oct 14, 2021 · d87c5b2 · d87c5b2
1 parent 01a78e6
commit d87c5b2
Showing 1 changed file with 255 additions and 9 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## Table of Contents
 
+- [v0.4.0](#v040)
 - [v0.4.0-rc2](#v040-rc2)
 - [v0.4.0-rc1](#v040-rc1)
 - [v0.3.0](#v030)
@@ -10,6 +11,251 @@
 - [v0.1.0-rc2](#v010-rc2)
 - [v0.1.0-rc1](#v010-rc1)
 
+## v0.4.0
+
+API version: v1alpha2
+
+This release contains significant breaking changes as we strive for a concise
+API. We anticipate that this API will be very similar to a future v1beta1
+release.
+
+The following changes have been made since v0.3.0:
+
+### Major Changes
+
+* The Gateway API APIGroup has moved from `networking.x-k8s.io` to
+ `gateway.networking.k8s.io`. This means that, as far as the apiserver is
+ concerned, this version is wholly distinct from v1alpha1, and automatic
+ conversion is not possible. As part of this process, Gateway API is now
+ subject to Kubernetes API review, the same as changes made to core API
+ resources. More details in
+ [#780](https://github.com/kubernetes-sigs/gateway-api/pull/780) and
+ [#716](https://github.com/kubernetes-sigs/gateway-api/issues/716).
+
+* Gateway-Route binding changes ([GEP-724](https://gateway-api.sigs.k8s.io/geps/gep-724/)):
+ In v1alpha1, Gateways chose which Routes were attached using a combination of
+ object and namespace selectors, with the option of also specifying object
+ names. This resulted in a very complex config, that's easy to misinterpret. As
+ part of v1alpha2, we're changing to:
+ * Gateways *may* specify what kind of Routes they support (defaults to same
+ protocol if not specified), and where those Routes can be (defaults to same
+ namespace).
+ * Routes *must* directly reference the Gateways the want to attach to, this is
+ a list, so a Route can attach to more than one Gateway.
+ * The Route becomes attached only when the specifications intersect.
+
+ We believe this is quite a bit easier to understand, and still gives good
+ flexibility for most use cases.
+ GEP added in [#725](https://github.com/kubernetes-sigs/gateway-api/pull/725).
+ Implemented in [#754](https://github.com/kubernetes-sigs/gateway-api/pull/754).
+ Further documentation was added in [#762](https://github.com/kubernetes-sigs/gateway-api/pull/762).
+
+* Safer cross-namespace references ([GEP-709](https://gateway-api.sigs.k8s.io/geps/gep-709/)): 
+ This concerns (currently), references from Routes to Backends, and Gateways to
+ Secrets. The new behavior is:
+ * By default, references across namespaces are not permitted; creating a
+ reference across a namespace (like a Route referencing a Service in another
+ namespace) must be rejected by implementations.
+ * These references can be accepted by creating a ReferencePolicy in the
+ referent (target) namespace, that specifies what Kind is allowed to accept
+ incoming references, and from what namespace and Kind the references may be.
+
+ The intent here is that the owner of the referent namespace must explicitly
+ accept incoming references, otherwise we can run into all sorts of bad things
+ from breaking the namespace security model.
+ Implemented in [#741](https://github.com/kubernetes-sigs/gateway-api/pull/741).
+
+* Attaching Policy to objects ([GEP-713](https://gateway-api.sigs.k8s.io/geps/gep-713/)):
+ This has been added so that we have an extensible mechanism for adding a
+ cascading set of policy to Gateway API objects.
+
+ What policy? Well, it's kind of up to the implementations, but the best example
+ to begin with is timeout policy.
+
+ Timeout policy for HTTP connections is highly depedent on how the underlying
+ implementation handles policy - it's very difficult to extract commonalities.
+
+ This is intended to allow things like:
+ * Attach a policy that specifies the default connection timeout for backends
+ to a GatewayClass. All Gateways that are part of that Class will have Routes
+ get that default connection timeout unless they specify differently.
+ * If a Gateway that's a member of the GatewayClass has a different default
+ attached, then that will beat the GatewayClass (for defaults, more specific
+ object beats less specific object).
+ * Alternatively, a Policy that mandates that you can't set the client timeout
+ to "no timeout" can be attached to a GatewayClass as an override. An
+ override will always take effect, with less specific beating more specific.
+
+ This one is a bit complex, but will allow implementations to solve some things
+ that currently require tools like admission control.
+ Implemented in [#736](https://github.com/kubernetes-sigs/gateway-api/pull/736).
+
+* As part of GEP-713, `BackendPolicy` has been removed, as its functionality is
+ now better handled using that mechanism.
+ [#732](https://github.com/kubernetes-sigs/gateway-api/pull/732).
+
+* Removal of certificate references from HTTPRoutes ([GEP-746](https://gateway-api.sigs.k8s.io/geps/gep-746/)):
+ In v1alpha1, HTTPRoute objects have a stanza that allows referencing a TLS
+ keypair, intended to allow people to have a more self-service model, where an
+ app owner can provision a TLS keypair inside their own namespace, attach it to
+ a HTTPRoute they control, and then have that used to secure their app.
+ When implementing this, however, there are a large number of edge cases that
+ are complex, hard to handle, and poorly defined - about checking SNI, hostname,
+ and overrides, that made even writing a spec on how to implement this very
+ difficult, let alone actually implementing it.
+
+ In removing certificate references from HTTPRoute, we're using the
+ ReferencePolicy from GEP-709 to allow Gateways to securely create a
+ cross-namespace reference to TLS keypairs in app namespaces.
+ We're hopeful that this will hit most of the self-service use case, and even
+ if not, provide a basis to build from to meet it eventually.
+ GEP added in [#749](https://github.com/kubernetes-sigs/gateway-api/pull/749).
+ Implemented in [#768](https://github.com/kubernetes-sigs/gateway-api/pull/768).
+
+ [GEP-851](https://github.com/kubernetes-sigs/gateway-api/blob/master/site-src/geps/gep-851.md),
+ was a follow up on this change that allowed multiple Certificate Refs per
+ Gateway Listener. This was implemented in
+ [#852](https://github.com/kubernetes-sigs/gateway-api/pull/852).
+
+* The `RouteForwardTo` (YAML: `routeForwardTo`) struct/stanza has been reworked
+ into the `BackendRef` (YAML: `backendRef`) struct/stanza,
+ [GEP-718](https://gateway-api.sigs.k8s.io/geps/gep-718/). As part of this
+ change, the `ServiceName` (YAML: `serviceName`) field has been removed, and
+ Service references must instead now use the `BackendRef`/`backendRef`
+ struct/stanza.
+
+### Small Changes
+* Extension points within match blocks from all Routes have been removed
+ [#829](https://github.com/kubernetes-sigs/gateway-api/pull/829). Implements
+ [GEP-820](https://github.com/kubernetes-sigs/gateway-api/blob/master/site-src/geps/gep-820.md).
+ These extension points have been removed because they are currently not used,
+ are poorly understood, and we don't have good use cases for them. We may
+ consider re-adding them in the future.
+
+* Controller is now a required field in Gateway references from Route status.
+ [#671](https://github.com/kubernetes-sigs/gateway-api/pull/671).
+
+* Header Matching, Query Param Matching, and HTTPRequestHeaderFilter now use
+ named subobjects instead of maps.
+ [#657](https://github.com/kubernetes-sigs/gateway-api/pull/657) and
+ [#681](https://github.com/kubernetes-sigs/gateway-api/pull/681)
+
+* [#796](https://github.com/kubernetes-sigs/gateway-api/pull/796) API Review
+ suggestions:
+ * listener.routes has been renamed to listener.allowedRoutes
+ * The `NoSuchGatewayClass` has been removed after it was deprecated in
+ v1alpha1
+ * `*` is no longer a valid hostname. Instead, leaving hostname unspecified is
+ interpreted as `*`.
+
+* The `scope` field has been removed from all object references.
+ [#882](https://github.com/kubernetes-sigs/gateway-api/pull/882)
+
+* "Controller" has been renamed to "ControllerName"
+ [#839](https://github.com/kubernetes-sigs/gateway-api/pull/839)
+
+* "Admitted" condition has been renamed to "Accepted" and now defaults to an
+ "Unknown" state instead of "False"
+ [#839](https://github.com/kubernetes-sigs/gateway-api/pull/839)
+
+* HTTPRequestRedirectFilter's Protocol field has been renamed to Scheme.
+ [#863](https://github.com/kubernetes-sigs/gateway-api/pull/863)
+
+* ImplementationSpecific match types in HTTPRoute's path, query, and header
+ matches have been removed.
+ [#850](https://github.com/kubernetes-sigs/gateway-api/pull/850)
+
+* The "Prefix" path match type has been renamed "PathPrefix".
+ [#898](https://github.com/kubernetes-sigs/gateway-api/pull/898)
+
+### Small Additions
+* HTTP Method matching is now added into HTTPRoute, with Extended support:
+ [#733](https://github.com/kubernetes-sigs/gateway-api/pull/733).
+
+* GatewayClass now has a 'Description' field that is printed as a column in
+ `kubectl get` output. You can now end up with output that looks like this:
+ ```shell
+ $> kubectl get gatewayclass
+ NAME CONTROLLER DESCRIPTION
+ internal gateway-controller-internal For non-internet-facing Gateways.
+ external gateway-controller-external For internet-facing Gateways.
+ ```
+ See [#610](https://github.com/kubernetes-sigs/gateway-api/issues/610) and
+ [#653](https://github.com/kubernetes-sigs/gateway-api/pull/653) for the
+ details.
+
+### Validation changes
+* Ensure TLSConfig is empty when the protocol is HTTP, TCP, or UDP
+ [#886](https://github.com/kubernetes-sigs/gateway-api/pull/886)
+* Ensure Hostname is empty when the protocol is TCP or UDP.
+ [#886](https://github.com/kubernetes-sigs/gateway-api/pull/886)
+* Listener ProtocolType now has validation.
+ [#871](https://github.com/kubernetes-sigs/gateway-api/pull/871)
+* HTTP Path match values are now validated for PathMatchExact and
+ PathMatchPrefix match types.
+ [#894](https://github.com/kubernetes-sigs/gateway-api/pull/894)
+* TLS options keys are now subject to the same validation as Kubernetes
+ annotations. [#886](https://github.com/kubernetes-sigs/gateway-api/pull/886)
+* TLS options values now have a max length of 4096 characters.
+ [#886](https://github.com/kubernetes-sigs/gateway-api/pull/886)
+* Make `MirrorFilter.BackendRef` a required field when the mirror filter is used
+ [#837](https://github.com/kubernetes-sigs/gateway-api/pull/837).
+
+### Clarifications
+* Updated guidance on how HTTP and TLS Route status should be populated when
+ hostnames do not match.
+ [#859](https://github.com/kubernetes-sigs/gateway-api/pull/859)
+* Aligned path prefix matching with Ingress by clarifying that it is a prefix of
+ path elements. [#869](https://github.com/kubernetes-sigs/gateway-api/pull/869)
+* HTTP listeners may now be used for Cleartext HTTP/2.
+ [#879](https://github.com/kubernetes-sigs/gateway-api/pull/879)
+* Added clarification that implementation-specific TLS options MUST be
+ domain-prefixed.
+ [#899](https://github.com/kubernetes-sigs/gateway-api/pull/899)
+
+### Documentation Updates
+* [#782](https://github.com/kubernetes-sigs/gateway-api/pull/782) : Restructure docs and split into versioned and unversioned
+* [#777](https://github.com/kubernetes-sigs/gateway-api/pull/777) : Fix typo
+* [#765](https://github.com/kubernetes-sigs/gateway-api/pull/765) : document multi-value headers as undefined
+* [#761](https://github.com/kubernetes-sigs/gateway-api/pull/761) : minor improvements to navigation on docs site
+* [#760](https://github.com/kubernetes-sigs/gateway-api/pull/760) : Remove references of vendor configurations in GatewayTLSConfig
+* [#756](https://github.com/kubernetes-sigs/gateway-api/pull/756) : Clarify docs on invalid serviceName
+* [#755](https://github.com/kubernetes-sigs/gateway-api/pull/755) : Document the supported kubernetes versions
+* [#745](https://github.com/kubernetes-sigs/gateway-api/pull/745) : Remove RouteTLSConfig requirement for gateway TLS passthrough.
+* [#744](https://github.com/kubernetes-sigs/gateway-api/pull/744) : automate nav for GEPs
+* [#743](https://github.com/kubernetes-sigs/gateway-api/pull/743) : Add READY and ADDRESS to gateway printer columns
+* [#742](https://github.com/kubernetes-sigs/gateway-api/pull/742) : Moving method match to v1alpha2 example
+* [#729](https://github.com/kubernetes-sigs/gateway-api/pull/729) : Adding suggested reasons for when conditions are healthy
+* [#728](https://github.com/kubernetes-sigs/gateway-api/pull/728) : Fixing wording in enhancement template
+* [#723](https://github.com/kubernetes-sigs/gateway-api/pull/723) : Clarifying Redirect Support levels
+* [#756](https://github.com/kubernetes-sigs/gateway-api/pull/756) : Clarify docs on invalid serviceName
+* [#880](https://github.com/kubernetes-sigs/gateway-api/pull/880) : Reworking Policy vs. Filter Documentation
+* [#878](https://github.com/kubernetes-sigs/gateway-api/pull/878) : Clarifying the fields that all Route types must include
+* [#875](https://github.com/kubernetes-sigs/gateway-api/pull/875) : Fix HTTP path match documentation.
+* [#864](https://github.com/kubernetes-sigs/gateway-api/pull/864) : Merging v1alpha2 concepts docs into unversioned docs
+* [#858](https://github.com/kubernetes-sigs/gateway-api/pull/858) : Fixing broken link to spec page
+* [#857](https://github.com/kubernetes-sigs/gateway-api/pull/857) : Adding missing references pages to docs navigation
+* [#853](https://github.com/kubernetes-sigs/gateway-api/pull/853) : docs: Use v0.4.0-rc1 in "Getting started with Gateway APIs" for v1alpha2
+* [#845](https://github.com/kubernetes-sigs/gateway-api/pull/845) : Fix markdown list formatting.
+* [#844](https://github.com/kubernetes-sigs/gateway-api/pull/844) : docs: add ssl passthrough note in FAQ
+* [#843](https://github.com/kubernetes-sigs/gateway-api/pull/843) : Add APISIX implementation
+* [#834](https://github.com/kubernetes-sigs/gateway-api/pull/834) : Fixes some broken links
+* [#807](https://github.com/kubernetes-sigs/gateway-api/pull/807) : docs: update multiple-ns guide for v1alpha2
+* [#888](https://github.com/kubernetes-sigs/gateway-api/pull/888) : Corrected broken getting started
+* [#885](https://github.com/kubernetes-sigs/gateway-api/pull/885) : Fix incorrect urls
+* [#890](https://github.com/kubernetes-sigs/gateway-api/pull/890) : Updating HTTPRoute docs for v1alpha2
+* [#870](https://github.com/kubernetes-sigs/gateway-api/pull/870) : Adding guidance on Kind vs. Resource in implementation guidelines
+* [#865](https://github.com/kubernetes-sigs/gateway-api/pull/865) : Route cleanup for v1alpha2 sig-network review
+
+### Tooling and infra updates
+* [#766](https://github.com/kubernetes-sigs/gateway-api/pull/766) : comment out the GEP notice
+* [#758](https://github.com/kubernetes-sigs/gateway-api/pull/758) : bump up mkdocs and deps
+* [#751](https://github.com/kubernetes-sigs/gateway-api/pull/751) : bump up deps to k8s v1.22
+* [#748](https://github.com/kubernetes-sigs/gateway-api/pull/748) : fix kustomize to install v1a2 crds
+* [#747](https://github.com/kubernetes-sigs/gateway-api/pull/747) : Cleaning up GEP Template
+* [#889](https://github.com/kubernetes-sigs/gateway-api/pull/889) : remove outdated version label
+* [#883](https://github.com/kubernetes-sigs/gateway-api/pull/883) : validating webhook cleanup
+* [#872](https://github.com/kubernetes-sigs/gateway-api/pull/872) : Remove duplicate validation from CRD & Webhook
 
 ## v0.4.0-rc2
 
@@ -23,7 +269,7 @@ In general, most of the changes below have been made to reduce the complexity of
 the API for v1alpha2, on the assumption that we can add functionality in later
 in the API's lifecycle, but cannot remove it.
 
-The following changes have been made since v1alpha2-rc1:
+The following changes have been made since v0.4.0-rc1:
 
 ### GEP implementations
 * Replace `CertificateRef` field with `CertificateRefs` in `GatewayTLSConfig`.
@@ -43,7 +289,7 @@ consider re-adding them in the future.
 * ImplementationSpecific match types in HTTPRoute's path, query, and header
 matches have been removed.
 [#850](https://github.com/kubernetes-sigs/gateway-api/pull/850)
-* The "Prefix" path match type has been renamed "PathPrefix". 
+* The "Prefix" path match type has been renamed "PathPrefix".
 * The "ClassName" field in PolicyTargetReference has been removed.
 * A new optional "Name" field has been added to ReferencePolicyTo.
 [#898](https://github.com/kubernetes-sigs/gateway-api/pull/898)
@@ -138,7 +384,7 @@ complex config, that's easy to misinterpret. As part of v1alpha2, we're changing
  * Routes *must* directly reference the Gateways the want to attach to, this is
  a list, so a Route can attach to more than one Gateway.
  * The Route becomes attached only when the specifications intersect.
- 
+
  We believe this is quite a bit easier to understand, and still gives good
  flexibility for most use cases.
  GEP added in [#725](https://github.com/kubernetes-sigs/gateway-api/pull/725).
@@ -169,7 +415,7 @@ Gateway API objects.
 
  What policy? Well, it's kind of up to the implementations, but the best example
  to begin with is timeout policy.
- 
+
  Timeout policy for HTTP connections is highly depedent on how the underlying
  implementation handles policy - it's very difficult to extract commonalities.
 
@@ -187,9 +433,9 @@ Gateway API objects.
  This one is a bit complex, but will allow implementations to solve some things
  that currently require tools like admission control.
  Implemented in [#736](https://github.com/kubernetes-sigs/gateway-api/pull/736).
- 
+
 * As part of GEP-713, `BackendPolicy` has been removed, as its functionality is
-now better handled using that mechanism. [#732](https://github.com/kubernetes-sigs/gateway-api/pull/732). 
+now better handled using that mechanism. [#732](https://github.com/kubernetes-sigs/gateway-api/pull/732).
 
 * Removal of certificate references from HTTPRoutes:
 [GEP-746](https://gateway-api.sigs.k8s.io/geps/gep-746/):
@@ -230,20 +476,20 @@ references must instead now use the `BackendRef`/`backendRef` struct/stanza.
  ```
  See [#610](https://github.com/kubernetes-sigs/gateway-api/issues/610) and
  [#653](https://github.com/kubernetes-sigs/gateway-api/pull/653) for the details.
- 
+
 * [#671](https://github.com/kubernetes-sigs/gateway-api/pull/671): Controller is
 now a required field in Gateway references from Route status. Fixes
 [#669](https://github.com/kubernetes-sigs/gateway-api/pull/671).
 
 * [#657](https://github.com/kubernetes-sigs/gateway-api/pull/657): and
 [#681](https://github.com/kubernetes-sigs/gateway-api/pull/681) Header Matching,
 Query Param Matching, and HTTPRequestHeaderFilter now use named subobjects
-instead of maps. 
+instead of maps.
 
 * [#796](https://github.com/kubernetes-sigs/gateway-api/pull/796) API Review suggestions:
  * listener.routes has been renamed to listener.allowedRoutes
  * The `NoSuchGatewayClass` has been removed after it was deprecated in v1alpha1
- * `*` is no longer a valid hostname. Instead, leaving hostname unspecified is interpreted as `*`. 
+ * `*` is no longer a valid hostname. Instead, leaving hostname unspecified is interpreted as `*`.
 
 ### Documentation Updates
 * [#782](https://github.com/kubernetes-sigs/gateway-api/pull/782) : Restructure docs and split into versioned and unversioned