Releases: kubernetes-sigs/gateway-api
v0.6.0-rc2
What's Changed
We expect this to be our final release candidate before launching v0.6.0. This
release candidate includes a variety of cleanup and documentation updates. The
changelog below represents the changes since v0.6.0-rc1.
Conformance Tests
- A new test has been added to cover HTTP Redirects (#1556, @LiorLieberman)
- Fix Gateway reference in HTTPRouteInvalidParentRefNotMatchingListenerPort
(#1591, @sayboras)
General Cleanup
- Display the Programmed condition instead of the Ready condition in the output
ofkubectl get gateways
. (#1602, @skriss) - GRPCRoute: Regex validation for Method and Service has been tightened to match
GRPC spec. (#1599, @robscott) - GRPCRoute: Webhook validation of GRPCRoute has been expanded to closely match
HTTPRoute validation. (#1599, @robscott) - HTTPRoute and Gateway: Gaps between webhook validation for v1alpha2 and
v1beta1 have been closed. (#1599, @robscott) - HTTPRoute: Validating webhook now ensures that Exact and Prefix path match
values can now only include valid path values per RFC-3986. (RegularExpression
path matches are not affected by this change). (#1599, @robscott) - The Gateway default conditions list now includes the Programmed condition.
(#1604, @youngnick) RegularExpression
type selectors have been clarified to all be
ImplementationSpecific
conformance. (#1604, @youngnick)
New Contributors
- @mmontes11 made their first contribution in #1577
- @sayboras made their first contribution in #1591
- @LiorLieberman made their first contribution in #1556
- @lucacome made their first contribution in #1597
Full Changelog: v0.6.0-rc1...v0.6.0-rc2
v0.6.0-rc1
Major Changes
ReferenceGrant moves to v1beta1
, ReferencePolicy removed
With more implementations now supporting ReferenceGrant (and more conformance coverage of the resource), we've moved ReferenceGrant to v1beta1
in this release. Note that moving to beta also moves the object to the Standard channel (it was Experimental previously).
We've also removed the already-deprecated ReferencePolicy resource, so please move over to the shiny new ReferenceGrant, which has all the same features.
- Promotes ReferenceGrant to the v1beta1 API and the standard release channel
(#1455, @nathancoleman) - ReferencePolicy has been removed from the API in favor of ReferenceGrant.
(#1406, @robscott)
Introduce GRPCRoute
The GRPCRoute
resource has been introduced in order to simplify the routing of GRPC requests.
Its design is described in GEP-1016.
As it is a new resource, it is introduced in the experimental channel.
Thanks to @gnossen for pushing this ahead.
Status updates
As described in GEP-1364, status conditions have been updated within the Gateway resource to make it more consistent with the rest of the API. These changes, along with some other status changes, are detailed below.
Gateway:
- New
Accepted
andProgrammed
conditions introduced. Scheduled
condition deprecated.- Core Conditions now
Accepted
andProgrammed
. - Moves to Extended:
Ready
.
Gateway Listener:
- New
Accepted
andProgrammed
conditions introduced. Detached
condition deprecated.- Core Conditions now
Accepted
,Programmed
,ResolvedRefs
, andConflicted
. - Moves to Extended:
Ready
.
All Resources:
- The
Accepted
Condition now has aPending
reason, which is the default until
the condition is updated by a controller.
Route resources:
- The
Accepted
Condition now has aNoMatchingParent
reason, to be set on routes
when no matching parent can be found.
The purpose of these changes is to make the status flows more consistent across objects, and to provide a clear pattern for new objects as we evolve the API.
Note: This change will require updates for implementations to be able to pass conformance tests. Implementations may choose to publish both new and old conditions, or only new conditions.
- Adds
Accepted
and deprecatesDetached
Listener conditions and reasons (#1446, @mikemorris) - Adds
Accepted
and deprecatesScheduled
Gateway conditions and reasons (#1447, @mikemorris) - Adds
Pending
reason for use with allAccepted
conditions throughout the API (#1453, @youngnick) - Adds
Programmed
Gateway and Listener conditions, movesReady
to extended
conformance (#1499, @LCaparelli) - Add
RouteReasonNoMatchingParent
reason forAccepted
condition. (#1516, @pmalek)
Other Changes by type
Deprecations
- GatewayClass, Gateway, and HTTPRoute are now only supported with the v1beta1
version of the API. The v1alpha2 API versions of these resources will be fully
removed in a future release. Additionally, v1alpha2 is marked as deprecated
everywhere. (#1348 and #1405, @robscott)
API Changes
- A new field
responseHeaderModifier
is added to.spec.rules.filters
, which
allows for modification of HTTP response headers (#1373, @aryan9600)
Conformance Tests
- ExemptFeatures have been merged into SupportedFeatures providing implementations
a uniform way to specify the features they support.
(#1507, @robscott) (#1394, @gyohuangxin) - To be conformant with the API, if there is no ReferenceGrant that grants a
listener to reference a secret in another namespace, the
ListenerConditionReason for the condition ResolvedRefs must be set to
RefNotPermitted instead of InvalidCertificateRef. (#1305, @mlavacca)
Developer Notes
- Deprecated
v1alpha2
Go types are now aliases to theirv1beta1
versions
(#1390, @howardjohn) - Moved type translation helpers from the
utils
package to a new package named
translator
. (#1337, @carlisia)
Documentation
- Clarify that BackendObjectReference's Port field specifies a service port, not
a target port, for Kubernetes Service backends. (#1332, @Miciah) - HTTPRequestHeaderFilter and HTTPResponseHeaderFilter forbid configuring
multiple actions for the same header. (#1497, @rainest) - Changes "custom" conformance level to "implementation-specific" (#1436,
@LCaparelli) - Clarification that changes to ReferenceGrants MUST be reconciled (#1429,
@robscott)
v0.5.1
API versions: v1beta1, v1alpha2
This release includes a number of bug fixes and clarifications:
API Spec
- The spec has been clarified to state that the port specified in BackendRef
refers to the Service port number, not the target port, when a Service is
referenced. #1332 - The spec has been clarified to state that "Accepted" should be used instead of
"Attached" on HTTPRoute.
#1382
Webhook:
- The duplicate gateway-system namespace definitions have been removed.
#1387 - The webhook has been updated to watch v1beta1.
#1365
Conformance:
- The expected condition for a cross-namespace certificate reference that has
not been allowed by a ReferenceGrant has been changed from
"InvalidCertificateRef" to "RefNotPermitted" to more closely match the spec.
#1351 - A new test has been added to cover when a Gateway references a Secret that
does not exist
#1334
v0.5.1
API versions: v1beta1, v1alpha2
This release includes a number of bug fixes and clarifications:
API Spec
- The spec has been clarified to state that the port specified in BackendRef
refers to the Service port number, not the target port, when a Service is
referenced. #1332 - The spec has been clarified to state that "Accepted" should be used instead of
"Attached" on HTTPRoute.
#1382
Webhook:
- The duplicate gateway-system namespace definitions have been removed.
#1387 - The webhook has been updated to watch v1beta1.
#1365
Conformance:
- The expected condition for a cross-namespace certificate reference that has
not been allowed by a ReferenceGrant has been changed from
"InvalidCertificateRef" to "RefNotPermitted" to more closely match the spec.
#1351 - A new test has been added to cover when a Gateway references a Secret that
does not exist
#1334
v0.5.0
API versions: v1beta1, v1alpha2
This release is all about stability.
Changes in this release can largely be divided into the following categories:
- Release Channels
- Resources graduating to beta
- New experimental features
- Bug Fixes
- General Improvements
- Breaking Changes
- Validation improvements
- Internal type cleanup
Note: This release is largely identical to v0.5.0-rc2, this changelog tracks
the difference between v0.5.0 and v0.4.3.
Release channels
In this release, we've made two release channels available, experimental
and
standard
.
The experimental
channel contains all resources and fields, while standard
contains only resources that mave moved to beta status.
We've also added a way to flag particular fields within a resource as
experimental, and any fields marked in this way are only present in the
experimental
channel. Please see the versioning docs for a more
detailed explanation.
One caveat for the standard channel - due to work on the new ReferenceGrant
resource: conformance tests may not pass with the standard
set of CRDs.
Resources graduating to beta
The following APIs have been promoted to a v1beta1
maturity:
GatewayClass
Gateway
HTTPRoute
New Experimental Features
- Routes can now select
Gateway
listeners by port number
#1002 - Gateway API now includes "Experimental" release channel. Consequently, CRDs now
includegateway.networking.k8s.io/bundle-version
and
gateway.networking.k8s.io/channel
annotations.
#945 - URL Rewrites and Path redirects have been added as new "Experimental" features
#945
Bug Fixes
- Fixes a problem that would cause webhook deployment to fail on Kubernetes
v1.22 and greater.
#991 - Fixes a bug where the
Namespace
could be unspecified inReferencePolicy
#964 - Fixes a bug where v1alpha2 GatewayClass controller names were not being
shown in the output ofkubectl get gatewayclasses
#909
General Improvements
- Conformance tests were introduced with GEP-917 and multiple
conformance tests were added from a variety of contributors under the
conformance/
directory. - The status of the GatewayClass "Accepted" condition for the
GatewayClass
is now present inkubectl get
output.
#1168 - New
RouteConditionReason
typesRouteReasonNotAllowedByListeners
and
RouteReasonNoMatchingListenerHostname
were added.
#1155 - New
RouteConditionReason
type added withRouteReasonAccepted
,
RouteReasonResolvedRefs
andRouteReasonRefNotPermitted
constants.
#1114 - Introduced PreciseHostname which prevents wildcard characters in relevant
Hostname values.
#956
Validation Improvements
- Webhook validation now ensures that a path match exists when required by path
modifier in filter.
#1171 - Webhook validation was added to ensure that only type-appropriate fields are
set inHTTPPathModifier
.
#1124 - The Gateway API webhook is now deployed in a
gateway-system
namespace
instead ofgateway-api
.
#1051 - Adds webhook validation to ensure that no HTTP header or query param is
matched more than once in a given route rule. (#1230, @skriss)
Breaking Changes
- The v1alpha1 API version was deprecated and removed.
#1197
#906 - The
NamedAddress
value forGateway
'sspec.addresses[].type
field has
been deprecated, and support for domain-prefixed values (like
example.com/NamedAddress
) has been added instead to better represent the
custom nature of this support.
#1178 - Implementations are now expected to use
500
instead of503
responses when
the data-plane has no matching route.
#1151,
#1258
UX and Status Improvements
The following are breaking changes related to status updates and end-user
experience changes.
- The
UnsupportedExtension
namedListenerConditionReason
has been removed.
#1146 - The
RouteConflict
namedListenerConditionReason
has been removed.
#1145
Internal Type Cleanup
These changes will only affect implementations. Implementors will need to adjust
for the type changes when updating the Gateway API dependency in their projects.
NOTE: These kinds of changes are not always present in the CHANGELOG so
please be aware that the CHANGELOG is not an exhaustive list of Go
type changes. In this case there were a significant number of changes
in a single release, so we included them for extra visibility for
implementors.
ReferencePolicy
has been renamed toReferenceGrant
.
#1179GatewayTLSConfig
'sCertificateRefs
field is now a slice of pointers to
structs instead of the structs directly.
#1176HTTPPathModifer
fieldAbsolute
renamed toReplaceFullPath
#1124- the
ParentRef
type was renamed toParentReference
#982 - Types
ConditionRouteAccepted
andConditionRouteResolvedRefs
are now
deprecated in favor ofRouteConditionAccepted
&RouteConditionResolvedRefs
#1114
v0.5.0-rc2
API versions: v1beta1, v1alpha2
We expect this to be our final release candidate before launching v0.5.0. This
release candidate includes a variety of cleanup and documentation updates.
Webhook
- Adds webhook validation to ensure that no HTTP header or query param is
matched more than once in a given route rule. (#1230, @skriss)
Documentation
- Add examples and documentation for v1beta1 (#1238, @EmilyShepherd)
- Add policy attachment example (#1233, @keithmattix)
- Add warning headers for experimental resources/concepts (#1234, @keithmattix)
- All Enum API fields have had updates to clarify that we may add values at any
time, and that implementations must handle unknown Enum values. (#1258,
@youngnick) - Spacing has been improved around the documentation of feature-level
core/extended support for better readability and clarity. (#1241, @acnodal-tc) - Update ReferenceGrant docs to include Gateways that reference a Secret in a
different namespace (#1181, @nathancoleman)
Cleanup
- ReferencePolicyList Items is an array of ReferencePolicy again (#1239,
@dprotaso) - This release of experimental-install.yaml will apply successfully. Previous
releases had some extraneous yaml. (#1232, @acnodal-tc) - The NamedAddress type is back to support backwards compatibility but it is
still formally deprecated. (#1252, @robscott)
v0.5.0-rc1
The working group expects that this release candidate is quite close to the final v0.5.0
release. However, breaking API changes are still possible.
This release candidate is suitable for implementors, but the working group does not
recommend shipping products based on a release candidate API due to the possibility
of incompatible changes prior to the final release.
API versions: v1beta1, v1alpha2
Changes in this release can largely be divided into the following categories:
- Release Channels
- Resources graduating to beta
- New experimental features
- Bug Fixes
- General Improvements
- Breaking Changes
- Validation improvements
- Internal type cleanup
Release channels
In this release, we've made two release channels available, experimental
and
standard
.
The experimental
channel contains all resources and fields, while standard
contains only resources that mave moved to beta status.
We've also added a way to flag particular fields within a resource as
experimental, and any fields marked in this way are only present in the
experimental
channel. Please see the versioning docs for a more
detailed explanation.
One caveat for the standard channel - due to work on the new ReferenceGrant
resource: conformance tests may not pass with the standard
set of CRDs.
Resources Graduating to BETA
The following APIs have been promoted to a v1beta1
maturity:
GatewayClass
Gateway
HTTPRoute
New Experimental Features
- Routes can now select
Gateway
listeners by port number
#1002 - Gateway API now includes "Experimental" release channel. Consequently, CRDs now
includegateway.networking.k8s.io/bundle-version
and
gateway.networking.k8s.io/channel
annotations.
#945 - URL Rewrites and Path redirects have been added as new "Experimental" features
#945
Bug Fixes
- Fixes a problem that would cause webhook deployment to fail on Kubernetes
v1.22 and greater.
#991 - Fixes a bug where the
Namespace
could be unspecified inReferencePolicy
#964 - Fixes a bug where v1alpha2 GatewayClass controller names were not being
shown in the output ofkubectl get gatewayclasses
#909
General Improvements
- Conformance tests were introduced with GEP-917 and multiple
conformance tests were added from a variety of contributors under the
conformance/
directory. - The status of the GatewayClass "Accepted" condition for the
GatewayClass
is now present inkubectl get
output.
#1168 - New
RouteConditionReason
typesRouteReasonNotAllowedByListeners
and
RouteReasonNoMatchingListenerHostname
were added.
#1155 - New
RouteConditionReason
type added withRouteReasonAccepted
,
RouteReasonResolvedRefs
andRouteReasonRefNotPermitted
constants.
#1114 - Introduced PreciseHostname which prevents wildcard characters in relevant
Hostname values.
#956
Validation Improvements
- Webhook validation now ensures that a path match exists when required by path
modifier in filter.
#1171 - Webhook validation was added to ensure that only type-appropriate fields are
set inHTTPPathModifier
.
#1124 - The Gateway API webhook is now deployed in a
gateway-system
namespace
instead ofgateway-api
.
#1051
Breaking Changes
- The v1alpha1 API version was deprecated and removed.
#1197
#906 - The
NamedAddress
value forGateway
'sspec.addresses[].type
field has
been deprecated, and support for domain-prefixed values (like
example.com/NamedAddress
) has been added instead to better represent the
custom nature of this support.
#1178 - Implementations are now expected to use
500
instead of503
responses when
the data-plane has no matching route.
#1151
UX and Status Improvements
The following are breaking changes related to status updates and end-user
experience changes.
- The
UnsupportedExtension
namedListenerConditionReason
has been removed.
#1146 - The
RouteConflict
namedListenerConditionReason
has been removed.
#1145
Internal Type Cleanup
These changes will only affect implementations. Implementors will need to adjust
for the type changes when updating the Gateway API dependency in their projects.
NOTE: These kinds of changes are not always present in the CHANGELOG so
please be aware that the CHANGELOG is not an exhaustive list of Go
type changes. In this case there were a significant number of changes
in a single release, so we included them for extra visibility for
implementors.
ReferencePolicy
has been renamed toReferenceGrant
.
#1179GatewayTLSConfig
'sCertificateRefs
field is now a slice of pointers to
structs instead of the structs directly.
#1176HTTPPathModifer
fieldAbsolute
renamed toReplaceFullPath
#1124- the
ParentRef
type was renamed toParentReference
#982 - Types
ConditionRouteAccepted
andConditionRouteResolvedRefs
are now
deprecated in favor ofRouteConditionAccepted
&RouteConditionResolvedRefs
#1114
v0.4.3
v0.4.2
v0.4.1
API version: v1alpha2
This release contains minor bug fixes for v1alpha2.
Bug Fixes
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
togateway.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 and #716. -
Gateway-Route binding changes (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. Implemented in #754. Further documentation was added in #762.
-
Safer cross-namespace references (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.
-
Attaching Policy to objects (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 dependent 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.
-
As part of GEP-713,
BackendPolicy
has been removed, as its functionality is now better handled using that mechanism. #732. -
Removal of certificate references from HTTPRoutes (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. Implemented in #768.
GEP-851, was a follow up on this change that allowed multiple Certificate Refs per Gateway Listener. This was implemented in #852.
-
The
RouteForwardTo
(YAML:routeForwardTo
) struct/stanza has been reworked into theBackendRef
(YAML:backendRef
) struct/stanza, GEP-718. As part of this change, theServiceName
(YAML:serviceName
) field has been removed, and Service references must instead now use theBackendRef
/backendRef
struct/stanza.
Small Changes
-
Extension points within match blocks from all Routes have been removed #829. Implements GEP-820. 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.
-
Header Matching, Query Param Matching, and HTTPRequestHeaderFilter now use named subobjects instead of maps. #657 and #681
-
#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 -
"Controller" has been renamed to "ControllerName" #839
-
"Admitted" condition has been renamed to "Accepted" and now defaults to an "Unknown" state instead of "False". #839
-
HTTPRequestRedirectFilter's Protocol field has been renamed to Scheme. #863
-
ImplementationSpecific match types in HTTPRoute's path, query, and header matches have been removed. #850
-
The "Prefix" path match type has been renamed "PathPrefix". #898
Small Additions
-
HTTP Method matching is now added into HTTPRoute, with Extended support: #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:$> kubectl get gatewayclass NAME CONTROLLER DESCRIPTION internal gateway-controller-internal For non-internet-facing Gateways. external gateway-controller-external For internet-facing Gateways.
Validation changes
- Ensure TLSConfig is empty when the protocol is HTTP, TCP, or UDP #886
- Ensure Hostname is empty when the protocol is TCP or UDP. #886
- Listener ProtocolType now has validation. #871
- HTTP Path match values are now validated for PathMatchExact and PathMatchPrefix match types. #894
- TLS options keys are now subject to the same validation as Kubernetes annotations. #886
- TLS options values now have a max length of 4096 characters. #886
- Make
MirrorFilter.BackendRef
a required field when the mirror filter is used [#837](https://github.com/kubernetes-si...