Repository for the next iteration of composite service (e.g. Ingress) and load balancing APIs.
On behalf of Kubernetes SIG Network, we are pleased to announce the v1.1 release! This release includes the graduation of several features to GA, including both GRPCRoute and Service Mesh. We are also introducing several new experimental features, including Session Persistence and Gateway Client Cert Verification.
The following represents the changes since v1.0.0:
GRPCRoute has graduated to GA (v1) and is now part of the Standard Channel. If you are already using the experimental version GRPCRoute, we recommend holding off on upgrading to the standard channel version of GRPCRoute until the controllers you're using have been updated to support GRPCRoute v1. Until then, it is safe to upgrade to the experimental channel version of GRPCRoute in v1.1 that includes both v1alpha2 and v1 API versions.
Leading Contributor: @gnossen
The standard for using Gateway API for Mesh has formally graduated to GA (v1) and is now part of the Standard Channel.
Service mesh support in Gateway API allows service mesh users to use the same
API to manage ingress traffic and mesh traffic, reusing the same policy and
routing interfaces. In Gateway API v1.1, routes (such as HTTPRoute) can now have
a Service as a parentRef, to control how traffic to specific services
behave. For more information, read the service
mesh documentation or see the list of
implementations.
Leading Contributors: @howardjohn, @keithmattix, @kflynn, @mikemorris
The Conformance Reports API and the corresponding test suite have been graduated
to GA. The Conformance report API has been expanded with the mode field
(intended to specify the working mode of the implementation), and the
gatewayAPIChannel (standard or experimental). The gatewayAPIVersion and
gatewayAPIChannel are now filled in automatically by the suite machinery,
along with a brief description of the testing outcome. The Reports have been
reorganized in a more structured way, and the implementations can now add
information on how the tests have been run and provide reproduction steps.
Leading Contributors: @mlavacca, @shaneutt
The port field in ParentRefs has graduated to GA (v1) and is now part of the
Standard Channel. You can use the port field to attach resources to Gateways,
Services, or other parent resources. For example, you can attach an HTTPRoute to
one or more specific Listeners of a Gateway based on the Listener port,
instead of name field.
Leading Contributor: @frankbu
Session Persistence is being introduced to Gateway API via a new policy (BackendLBPolicy) for Service-level configuration and as fields within HTTPRoute and GRPCRoute for Route-level configuration. The BackendLBPolicy and Route-level APIs provide the same session persistence configuration, including session timeouts, session name, session type, and cookie lifetime type.
Leading Contributors: @gcs278, @ginayeh
Gateways can now configure client cert verification for each Gateway Listener by
introducing a new field frontendValidation field within tls. This field
supports configuring a list of CA Certificates that can be used as a trust
anchor to validate the certificates presented by the client.
Leading Contributors: @arkodg
As part of a broader goal of making our TLS terminology more consistent throughout the API, we've introduced some breaking changes to BackendTLSPolicy. This has resulted in a new API version (v1alpha3) and will require any existing users of this policy to uninstall the v1alpha2 version before installing this newer version.
Any references to v1alpha2 BackendTLSPolicy fields will need to be updated. Specific changes include:
targetRef field is now a targetRefs list and these references no
longer include a namespace field.tls field has been renamed to validation
caCertRefs field has been renamed to caCertificateRefs
wellKnownCACerts field has been renamed to wellKnownCACertificates
Leading Contributors: @candita
Gateways now feature a new field that allows references to implementation-specific parameters, similar to GatewayClass.
Leading Contributors: @howardjohn
get command to support gateways, gatewayclasses, and
namespaces. (#2865, #2782, #2847, @jongwooo)get command now provides more detailed information for httproutes,
policies, and policycrds. (#2805, #2808, #2811, @jongwooo)describe command now supports descriptions of policycrds and namespaces.
(#2872, #2836, @Devaansh-Kumar)-l
flag) with both the get and describe commands. (#2892, #2915, #2934,
@yeedove)Mesh-GRPC profile has been
added (#3019, @mlavacca):
We expect that this release candidate is quite close to the final v1.1.0 release. However, subsequent breaking API changes are still possible.
This release candidate is suitable for implementors, but we do not recommend shipping products based on a release candidate API due to the possibility of incompatible changes prior to the final release. The following represents the changes since v1.1.0-rc1:
We expect that this release candidate is quite close to the final v1.1.0 release. However, subsequent breaking API changes are still possible.
This release candidate is suitable for implementors, but we do not recommend shipping products based on a release candidate API due to the possibility of incompatible changes prior to the final release. The following represents the changes since v1.0.0:
GRPCRoute has graduated to GA (v1) and is now part of the Standard Channel. If you are already using the experimental version GRPCRoute, we recommend holding off on upgrading to the standard channel version of GRPCRoute until the controllers you're using have been updated to support GRPCRoute v1. Until then, it is safe to upgrade to the experimental channel version of GRPCRoute in v1.1 that includes both v1alpha2 and v1 API versions.
Leading Contributor: @gnossen
The standard for using Gateway API for Mesh has formally graduated to GA (v1) and is now part of the Standard Channel.
Service mesh support in Gateway API allows service mesh users to use the same
API to manage ingress traffic and mesh traffic, reusing the same policy and
routing interfaces. In Gateway API v1.1, routes (such as HTTPRoute) can now have
a Service as a parentRef, to control how traffic to specific services
behave. For more information, read the service
mesh documentation or see the list of
implementations.
Leading Contributors: @howardjohn, @keithmattix, @kflynn, @mikemorris
The Conformance Reports API and the corresponding test suite have been graduated
to GA. The Conformance report API has been expanded with the mode field
(intended to specify the working mode of the implementation), and the
gatewayAPIChannel (standard or experimental). The gatewayAPIVersion and
gatewayAPIChannel are now filled in automatically by the suite machinery,
along with a brief description of the testing outcome. The Reports have been
reorganized in a more structured way, and the implementations can now add
information on how the tests have been run and provide reproduction steps.
Leading Contributors: @mlavacca, @shaneutt
The port field in ParentRefs has graduated to GA (v1) and is now part of the
Standard Channel. You can use the port field to attach resources to Gateways,
Services, or other parent resources. For example, you can attach an HTTPRoute to
one or more specific Listeners of a Gateway based on the Listener port,
instead of name field.
Leading Contributor: @frankbu
Session Persistence is being introduced to Gateway API via a new policy (BackendLBPolicy) for Service-level configuration and as fields within HTTPRoute and GRPCRoute for Route-level configuration. The BackendLBPolicy and Route-level APIs provide the same session persistence configuration, including session timeouts, session name, session type, and cookie lifetime type.
Leading Contributors: @gcs278, @ginayeh
Gateways can now configure client cert verification for each Gateway Listener by
introducing a new field frontendValidation field within tls. This field
supports configuring a list of CA Certificates that can be used as a trust
anchor to validate the certificates presented by the client.
Leading Contributors: @arkodg
As part of a broader goal of making our TLS terminology more consistent throughout the API, we've introduced some breaking changes to BackendTLSPolicy. This has resulted in a new API version (v1alpha3) and will require any existing users of this policy to uninstall the v1alpha2 version before installing this newer version.
Any references to v1alpha2 BackendTLSPolicy fields will need to be updated. Specific changes include:
targetRef field is now a targetRefs list and these references no
longer include a namespace field.tls field has been renamed to validation
caCertRefs field has been renamed to caCertificateRefs
wellKnownCACerts field has been renamed to wellKnownCACertificates
Leading Contributors: @candita
Gateways now feature a new field that allows references to implementation-specific parameters, similar to GatewayClass.
Leading Contributors: @howardjohn
get command to support gateways, gatewayclasses, and
namespaces. (#2865, #2782, #2847, @jongwooo)get command now provides more detailed information for httproutes,
policies, and policycrds. (#2805, #2808, #2811, @jongwooo)describe command now supports descriptions of policycrds and namespaces.
(#2872, #2836, @Devaansh-Kumar)-l
flag) with both the get and describe commands. (#2892, #2915, #2934,
@yeedove)Mesh-GRPC profile has been
added (#3019, @mlavacca):
On behalf of Kubernetes SIG Network, we are pleased to announce the v1.0 release! This release marks a huge milestone for this project. Several key APIs are graduating to GA (generally available), while other significant features have been added to the Experimental channel.
It's been four years since this project began, and we would never have gotten here without the support of a dedicated and active community. The maintainers would like to thanks everyone who's contributed to Gateway API, whether in the form of commits to the repo, discussion, ideas, or general support. We literally couldn't have gotten this far without you.
This project is nowhere near finished, as you can see from the large amount of features being added into the Experimental Channel. With such a big set of things still to do, contributors and contributions are more vital than ever. Please feel welcome to join our community!!
Gateway, GatewayClass, and HTTPRoute have all graduated to GA with a v1 API
version. Although these APIs will continue to grow with future additions, the
versions of these resources available via the Standard Channel are stable and
recommended for use in production. Many implementations are fully passing
conformance tests that cover the functionality of each of these resources. These
APIs are graduating to GA with only minor spec clarifications since the v0.8.0
release.
Starting in v0.8.0, Gateway API CRDs now include CEL validation. In this release
the validating webhook is no longer bundled with CRD installation. Instead we
include a separate webhook-install.yaml file as part of the release artifacts.
If you're running Kubernetes 1.25+, we do not recommend installing the webhook and additionally suggest that you uninstall any previously installed versions of the webhook.
If you're still running Kubernetes 1.23 or 1.24, we recommend installing the webhook until you can upgrade to Kubernetes 1.25 or newer.
There are several exciting new experimental features in this release:
A new BackendTLSPolicy resource has been introduced for configuring TLS
connections from Gateways to Backends. This allows you to configure the Gateway
to validate the certificates served by Backends. For more information, refer to
GEP 1897.
Primary Author: @candita
HTTPRoute has a new Timeouts field on Route Rules. This allows you to
configure overall Request Timeouts as well as Backend Request Timeouts. For more
information, refer to GEP 1742.
Primary Authors: @frankbu, @SRodi
Gateway has a new Infrastructure field that allows you to specify Labels or
Annotations that you'd like to be propagated to each resource generated for a
Gateway. For example, these labels and annotations may be copied to Services and
Deployments provisioned for in-cluster Gateways, or to other
implementation-specific resources, such as Cloud Load Balancers. For more
information, refer to GEP 1762.
Primary Author: @howardjohn
Some coordinated work across both Gateway API and upstream Kubernetes has defined 3 new values for the AppProtocol field on Service Ports:
kubernetes.io/h2c - HTTP/2 over cleartext as described in
RFC7540
kubernetes.io/ws - WebSocket over cleartext as described in
RFC6445
kubernetes.io/wss - WebSocket over TLS as described in
RFC6455
These can now be used with Gateway API to describe the protocol to use for connections to Kubernetes Services. For more information, refer to GEP 1911.
An experimental new CLI tool and kubectl plugin, gwctl aims to improve the UX when interacting with Gateway API. Initially it is focused on Policy Attachment, making it easier to understand which policies are available in a cluster, and which have been applied. In future releases, we hope to expand the scope of this tool to provide more detailed responses when getting and describing Gateway API resources. Note that this tool is still in very early stages and it's very likely that future releases will include breaking changes for gwctl. For more information, refer to the gwctl Readme.
Primary Author: @gauravkghildiyal
Of course there's a lot more in this release:
distinct (#2436,
@youngnick)supportedFeatures field has been
added. Implementations should populate this with the features they support.
(#2461, @Liorlieberman, @robscott)GatewayReasonUnsupportedAddress for Accepted now ONLY
applies when an address type is provided for a Gateway which it does not
support.
(#2412 @shaneutt)GatewayReasonAddressNotAssigned for Programmed now
ONLY applies to problems with dynamic address allocation.
(#2412 @shaneutt)GatewayReasonAddressNotUsable for Programmed has been
added to deal with situations where a static address has been provided for a
Gateway which is of a supported type, and is syntactically valid, but for some
reason it can not be used for this Gateway (e.g. the address is already in use
on the network).
(#2412 @shaneutt)Errorf instead of Fatalf. (#2361, @yylt)ReferenceGrant from v1 to v1beta1 in the
GatewaySecretInvalidReferenceGrant conformance test YAML (#2494, @arkodg)ExemptFeatures field for Experimental Conformance Profiles
(#2515, @arkodg)gateway-system
namespace and the gateway-api-admission-server deployment have been removed
from the installation manifests, in favor of CEL based Validations that are
built into the CRD definition. These are still available in
webhook-install.yaml in case you would like to optionally install them.
(#2401, @arkodg)The working group expects that this release candidate is quite close to the final v0.8.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. The following represents the changes since v1.0.0-rc1:
ReferenceGrant from v1 to v1beta1 in the
GatewaySecretInvalidReferenceGrant conformance test YAML (#2494, @arkodg)ExemptFeatures field for Experimental Conformance Profiles
(#2515, @arkodg)The working group expects that this release candidate is quite close to the final v0.8.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. The following represents the changes since v0.8.0-rc1:
Gateway, GatewayClass, and HTTPRoute have all graduated to GA with a v1 API
version. Although these APIs will continue to grow with future additions, the
versions of these resources available via the Standard Channel are stable and
recommended for use in production. Many implementations are fully passing
conformance tests that cover the functionality of each of these resources. These
APIs are graduating to GA with only minor spec clarifications since the v0.8.0
release.
Starting in v0.8.0, Gateway API CRDs now include CEL validation. In this release
the validating webhook is no longer bundled with CRD installation. Instead we
include a separate webhook-install.yaml file as part of the release artifacts.
If you're running Kubernetes 1.25+, we do not recommend installing the webhook and additionally suggest that you uninstall any previously installed versions of the webhook.
If you're still running Kubernetes 1.23 or 1.24, we recommend installing the webhook until you can upgrade to Kubernetes 1.25 or newer.
There are several exciting new experimental features in this release:
A new BackendTLSPolicy resource has been introduced for configuring TLS
connections from Gateways to Backends. This allows you to configure the Gateway
to validate the certificates served by Backends. For more information, refer to
GEP 1897.
Primary Author: @candita
HTTPRoute has a new Timeouts field on Route Rules. This allows you to
configure overall Request Timeouts as well as Backend Request Timeouts. For more
information, refer to GEP 1742.
Primary Authors: @frankbu, @SRodi
Gateway has a new Infrastructure field that allows you to specify Labels or
Annotations that you'd like to be propagated to each resource generated for a
Gateway. For example, these labels and annotations may be copied to Services and
Deployments provisioned for in-cluster Gateways, or to other
implementation-specific resources, such as Cloud Load Balancers. For more
information, refer to GEP 1762.
Primary Author: @howardjohn
Some coordinated work across both Gateway API and upstream Kubernetes has defined 3 new values for the AppProtocol field on Service Ports:
kubernetes.io/h2c - HTTP/2 over cleartext as described in
RFC7540
kubernetes.io/ws - WebSocket over cleartext as described in
RFC6445
kubernetes.io/wss - WebSocket over TLS as described in
RFC6455
These can now be used with Gateway API to describe the protocol to use for connections to Kubernetes Services. For more information, refer to GEP 1911.
An experimental new CLI tool and kubectl plugin, gwctl aims to improve the UX when interacting with Gateway API. Initially it is focused on Policy Attachment, making it easier to understand which policies are available in a cluster, and which have been applied. In future releases, we hope to expand the scope of this tool to provide more detailed responses when getting and describing Gateway API resources. Note that this tool is still in very early stages and it's very likely that future releases will include breaking changes for gwctl. For more information, refer to the gwctl Readme.
Primary Author: @gauravkghildiyal
Of course there's a lot more in this release:
distinct (#2436,
@youngnick)supportedFeatures field has been
added. Implementations should populate this with the features they support.
(#2461, @Liorlieberman, @robscott)GatewayReasonUnsupportedAddress for Accepted now ONLY
applies when an address type is provided for a Gateway which it does not
support.
(#2412 @shaneutt)GatewayReasonAddressNotAssigned for Programmed now
ONLY applies to problems with dynamic address allocation.
(#2412 @shaneutt)GatewayReasonAddressNotUsable for Programmed has been
added to deal with situations where a static address has been provided for a
Gateway which is of a supported type, and is syntatically valid, but for some
reason it can not be used for this Gateway (e.g. the address is already in use
on the network).
(#2412 @shaneutt)Errorf instead of Fatalf. (#2361, @yylt)gateway-system
namespace and the gateway-api-admission-server deployment have been removed
from the installation manifests, in favor of CEL based Validations that are
built into the CRD definition. These are still available in
webhook-install.yaml in case you would like to optionally install them.
(#2401, @arkodg)This is a patch release that includes small bug fixes and a new conformance test as a follow up to the v0.8.0 release.
Service mesh support per the GAMMA initiative has moved to experimental in
v0.8.0. As an experimental API, it is still possible that this will
change; the working group does not recommend shipping products based on any
experimental API.
When using the Gateway API to configure a service mesh, the Gateway and GatewayClass resources are not used (as there will typically only be one mesh in the cluster) and, instead, individual route resources are associated directly with Service resources. This permits configuring mesh routing while preserving the Gateway API's overall semantics.
We encourage service mesh implementers and users to try this new support and we welcome feedback! Once again, though, the working group does not recommend shipping products based on this or any other experimental API. due to the possibility of incompatible changes prior to the final release.
This release marks the beginning of a transition from webhook validation to CEL validation that is built into the CRDs. That will mean different things depending on the version of Kubernetes you're using:
CEL validation is fully supported. Most validation is now covered by the validating webhook, but unfortunately not quite everything.
All but one validation has been translated from the webhook to CEL. Currently the CRDs only have a case-sensitive uniqueness check for header names in header modifier filters. The webhook validation is more thorough, ensuring that the uniqueness is case-insensitive. Unfortunately that is not possible to represent with CEL today. There is more information in #2277.
Installing the validating webhook is still recommended for this release to allow controllers to catch up to cover this gap in CEL validation. We expect this is the last release we will make this recommendation for, for more information, refer to #2319.
CEL validation is not supported, but Gateway API v0.8.0 CRDs can still be installed. When you upgrade to Kubernetes 1.25+, the validation included in these CRDs will automatically take effect. We recommend continuing to install the validating webhook on these Kubernetes versions.
Unfortunately Gateway API v0.8.0 is not supported on these Kubernetes versions. Gateway API v0.8.0 CRDs include CEL validation and cannot be installed on these versions of Kubernetes. Note that Gateway API only commits to providing support for the 5 most recent versions of Kubernetes, and thus these versions are no longer supported by Gateway API.
As we prepare for a v1.0 release that will graduate Gateway, GatewayClass, and
HTTPRoute to the v1 API Version from v1beta1, we are continuing the process
of moving away from v1alpha2 for resources that have graduated to v1beta1.
The following changes are included in this release:
v1alpha2 of Gateway, GatewayClass, and HTTPRoute is no longer servedv1alpha2 of ReferenceGrant is deprecatedv1beta1 is now the storage version for ReferenceGrantThose changes mean that:
v1alpha2 of
Gateway, GatewayClass, or HTTPRoute MUST upgrade to use v1beta1.v1alpha2 of
ReferenceGrant SHOULD upgrade to use v1beta1.For more information, refer to #2069.
Gateway API conformance tests have a concept of "Supported Features". Implementations state which features they support, and then all the tests covering that set of features are run.
Prior to v0.8.0, we had a concept of "StandardCoreFeatures" that represented the set of features we expected every implementation to implement. Support for the Gateway and HTTPRoute resources was included in that list.
Alongside that, Gateway API also has a concept of "Support Levels" such as "Core", "Extended", and "Implementation-Specific". The API had labeled 2 resources as having support levels, but these didn't really make sense with the modular API model of Gateway API.
In this release, we've simplified the concepts here. Individual resources no longer have assigned support levels, instead these are represented as "Supported Features." Implementations can separately claim to support Gateway, ReferenceGrant, or any other resource. This change helps accommodate incoming Mesh implementations, many of which do not support one or both of these resources.
For more information refer to #2323.
--skip-tests flag has been added to the conformance CLI to enable tests
opt-out when using it. (#2170, @mlavacca)go test. (#2066, @mlavacca)Full Changelog: https://github.com/kubernetes-sigs/gateway-api/compare/v0.7.0...v0.8.0
The working group expects that this release candidate is quite close to the final v0.8.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. The following represents the changes since v0.8.0-rc1:
Full Changelog: https://github.com/kubernetes-sigs/gateway-api/compare/v0.8.0-rc1...v0.8.0-rc2
The working group expects that this release candidate is quite close to the final v0.8.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.
Service mesh support per the GAMMA initiative has moved to experimental in
v0.8.0. As an experimental API, it is still possible that this will
change; the working group does not recommend shipping products based on any
experimental API.
When using the Gateway API to configure a service mesh, the Gateway and GatewayClass resources are not used (as there will typically only be one mesh in the cluster) and, instead, individual route resources are associated directly with Service resources. This permits configuring mesh routing while preserving the Gateway API's overall semantics.
We encourage service mesh implementers and users to try this new support and we welcome feedback! Once again, though, the working group does not recommend shipping products based on this or any other experimental API. due to the possibility of incompatible changes prior to the final release.
This release marks the beginning of a transition from webhook validation to CEL validation that is built into the CRDs. That will mean different things depending on the version of Kubernetes you're using:
CEL validation is fully supported. Most validation is now covered by the validating webhook, but unfortunately not quite everything.
Standard Channel: All but one validation has been translated from the webhook to CEL. Currently the CRDs only have a case-sensitive uniqueness check for header names in header modifier filters. The webhook validation is more thorough, ensuring that the uniqueness is case-insensitive. Unfortunately that is not possible to represent with CEL today. There is more information in #2277.
Experimental Channel: TCPRoute, TLSRoute, and UDPRoute are fully covered by CEL validation. GRPCRoute still has some significant gaps in CEL validation that will be covered in a future release.
CEL validation is not supported, but Gateway API v0.8.0 CRDs can still be installed. When you upgrade to Kubernetes 1.25+, the validation included in these CRDs will automatically take effect. We recommend continuing to install the validating webhook on these Kubernetes versions.
Unfortunately Gateway API v0.8.0 is not supported on these Kubernetes versions. Gateway API v0.8.0 CRDs include CEL validation and cannot be installed on these versions of Kubernetes. Note that Gateway API only commits to providing support for the 5 most recent versions of Kubernetes, and thus these versions are no longer supported by Gateway API.
As we prepare for a v1.0 release that will graduate Gateway, GatewayClass, and
HTTPRoute to the v1 API Version from v1beta1, we are continuing the process
of moving away from v1alpha2 for resources that have graduated to v1beta1.
The following changes are included in this release:
v1alpha2 of Gateway, GatewayClass, and HTTPRoute is no longer servedv1alpha2 of ReferenceGrant is deprecratedv1beta1 is now the storage version for ReferenceGrantThose changes mean that:
v1alpha2 of
Gateway, GatewayClass, or HTTPRoute MUST upgrade to use v1beta1.v1alpha2 of
ReferenceGrant SHOULD upgrade to use v1beta1.For more information, refer to #2069.
--skip-tests flag has been added to the conformance CLI to enable tests
opt-out when using it. (#2170, @mlavacca)go test. (#2066, @mlavacca)