v1.2.0

On behalf of Kubernetes SIG Network, we are excited to announce the release of v1.2!
This release includes the graduation of 3 features to the standard channel and the introduction of 4 new features to the experimental channel, along with several improvements in many project areas.

Breaking Changes

GRPCRoute and ReferenceGrant v1alpha2 removal

As per a previous deprecation notice, in this version, both Experimental
and Standard channel CRDs will no longer serve the v1alpha2 versions
of GRPCRoute and ReferenceGrant.

• Disable v1alpha2 versions for GRPCRoute and ReferenceGrant by @youngnick in
  #3361

Upgrades

Before upgrading to Gateway API v1.2, you'll want to confirm that any
implementations of Gateway API have been upgraded to support the v1 API
version of these resources instead of the v1alpha2 API version. Note that
even if you've been using v1 in your YAML manifests, a controller may still be
using v1alpha2 which would cause it to fail during this upgrade.

Once you've confirmed that the implementations you're relying on have upgraded
to v1, it's time to install the v1.2 CRDs. In most cases, this will work without
any additional effort.

If you ran into issues installing these CRDs, it likely means that you have
v1alpha2 in the storedVersions of one or both of these CRDs. This field is
used to indicate which API versions have ever been used to persist one of these
resources. Unfortunately, this field is not automatically pruned. To check these
values, you can run the following commands:

kubectl get crd grpcroutes.gateway.networking.k8s.io -ojsonpath="{.status.storedVersions}"
kubectl get crd referencegrants.gateway.networking.k8s.io -ojsonpath="{.status.storedVersions}"

If either of these return a list that includes "v1alpha2", it means that we need
to manually remove that version from storedVersions.

Before doing that, it would be good to ensure that all your ReferenceGrants and
GRPCRoutes have been updated to the latest storage version:

crds=("GRPCRoutes" "ReferenceGrants")

for crd in "${crds[@]}"; do
  output=$(kubectl get "${crd}" -A -o json)

  echo "$output" | jq -c '.items[]' | while IFS= read -r resource; do
    namespace=$(echo "$resource" | jq -r '.metadata.namespace')
    name=$(echo "$resource" | jq -r '.metadata.name')
    kubectl patch "${crd}" "${name}" -n "${namespace}" --type='json' -p='[{"op": "replace", "path": "/metadata/annotations/migration-time", "value": "'"$(date +%Y-%m-%dT%H:%M:%S)"'" }]'
  done
done

Now that all your ReferenceGrant and GRPCRoute resources have been updated to
use the latest storage version, you can patch the ReferenceGrant and GRPCRoute
CRDs:

kubectl patch customresourcedefinitions referencegrants.gateway.networking.k8s.io --subresource='status' --type='merge' -p '{"status":{"storedVersions":["v1beta1"]}}'
kubectl patch customresourcedefinitions grpcroutes.gateway.networking.k8s.io --subresource='status' --type='merge' -p '{"status":{"storedVersions":["v1"]}}'

With these steps complete, upgrading to the latest GRPCRoute and ReferenceGrant
should work well now.

Experimental Channel: GatewayClass Supported Features

The Experimental supportedFeatures field in GatewayClass status has changed
from being a list of strings to being a list of objects/structs with a name
field.

This is to allow adding in extra information to each entry at a later date.

Relevant PRs:

• SupportedFeatures field in Gateway Class status are now presented as a list of
  objects by @LiorLieberman in
  #3200

Changes since v1.2.0-rc2

There was one small change since RC2 - the Gateway Infrastructure conformance
test has been marked as provisional as we're not sure that the same-namespace
requirement imposed by this test is necessary. #3373

Release Cycle changes

This was our first release using a new release
cycle that is
meant to make Gateway API releases more frequent and predictable.

There are now four phases:

• Scoping: 4-6 weeks, where the maintainers and community determine the set
  of features we want to include in the release. A key deliverable here is
  ensuring that the Experimental channel does not get any bigger than it already
  is; we want to ensure that features make their way to Standard or are removed.
• GEP Iteration and Review: 5-7 weeks, where we work to update GEPs, and
  solidify and meet graduation criteria for in-scope GEPs.
• API Refinement and Documentation: 3-5 weeks, where we translate proposed
  changes from GEPs into changes to both the API specification and
  documentation.
• SIG-Network Review and Release Candidates: 2-4 weeks, where we perform our
  required upstream reviews, get any further required changes in, and release
  our release candidates so that implementations can get started with work on
  the new features asap.

For all the detail about this, please see the Release Cycle
docs.

Relevant PRs:

• Adding Release Cycle Documentation by @robscott in
  #3063

Standard Channel Additions and Changes

The Standard channel is Gateway API's set of maximally-stable install files.
Only features with the best testing and support are added to the standard
channel. This channel should be considered GA or stable, and future changes will
be fully backwards compatible.

Infrastructure Labels and Annotations 🎉

GEP-1867 added an
infrastructure stanza to Gateway objects that is intended to carry
infrastructure configuration specific to that Gateway object.

GEP-1762 adds a section for
labels and annotations to this stanza that specifies labels and annotations
to be annotated to all resources created to fulfill that Gateway request.

This feature can be used to affect the labels and annotations created on
LoadBalancer Services by in-cluster implementations to fulfill the Gateway
contract or by Cloud Load Balancing resources created by Cloud Providers.

This feature has graduated to Standard and is now considered GA or Stable.

This feature's name for conformance tests and GatewayClass status reporting is
GatewayInfrastructurePropagation.

This feature's status is Extended, meaning that it is optional for
implementations to support. If you're using Experimental Channel, you can refer
to the supportedFeatures field in the status of any GatewayClass.

Relevant PRs:

• Remove experimental from gateway infrastructure by @keithmattix in
  #3272
• Validation for label keys and values according to Kubernetes specification by
  @snorwin in #3284

HTTPRoute Timeouts and Durations 🎉

The HTTPRoute Timeouts field on Route Rules has graduated to Standard and is
now considered GA or Stable.

This field allows you to configure overall Request Timeouts as well as Backend
Request Timeouts. For more information, refer to GEP
1742.

The relevant feature names this for conformance tests and GatewayClass status
reporting are:

• HTTPRouteRequestTimeout for httproute.spec.rules[].timeouts.request
• HTTPRouteBackendTimeout for httproute.spec.rules[].timeouts.backendRequest

This feature's status is Extended, meaning that it is optional for
implementations to support. If you're using Experimental Channel, you can refer
to the supportedFeatures field in the status of any GatewayClass.

Relevant PRs:

• Graduate GEP-2257 and GEP-1742 to standard by @kflynn in
  #3210
• GEP2257 Duration parsing by @xtineskim in
  #3271

BackendProtocol Support 🎉

The previous coordinated work across both Gateway API and upstream Kubernetes
which defined 3 new values for the AppProtocol field on Service Ports has
graduated to Standard and is now considered GA or Stable.

The values are:

• 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.

The relevant feature names this for conformance tests and GatewayClass status
reporting are:

• HTTPRouteBackendProtocolH2C for H2C support, when
  service.spec.ports[].appProtocol is kubernetes.io/h2c.
• HTTPRouteBackendProtocolWebSocket for Websocket support, when
  service.spec.ports[].appProtocol is kubernetes.io/ws or
  kubernetes.io/wss.

This feature's status is Extended, meaning that it is optional for
implementations to support. If you're using Experimental Channel, you can refer
to the supportedFeatures field in the status of any GatewayClass.

Relevant PRs:

• Backend Protocol Selection is no longer experimental and is now part of
  HTTPRoute Extended Conformance by @dprotaso in
  #3108...

v1.2.0-rc2

v1.2.0-rc2

This release candidate should be the same as the final v1.2.0 release.

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.2.0-rc1:

Breaking Changes

GRPCRoute and ReferenceGrant v1alpha2 removal

As per a previous deprecation notice, in this version, both Experimental
and Standard channel YAMLs will no longer serve the v1alpha2 versions
of GRPCRoute and ReferenceGrant.

For the final release, we will provide pre-upgrade migration instructions
to cover folks who have been using the v1alpha2 versions of these objects.

• Disable v1alpha2 versions for GRPCRoute and ReferenceGrant by @youngnick in
  #3361

Documentation Changes

• Fix a number of GEP stage errors by @youngnick in
  #3359

Testing and Conformance changes

• Add conformance suite client options by @BobyMCbobs in
  #3343
• Fix conformance test race condition by @caboteria in
  #3350

v1.2.0-rc1

v1.2.0-rc1

We expect that this release candidate is quite close to the final v1.2.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:

Release Cycle changes

This was our first release using a new release cycle that is meant to make Gateway API releases more frequent and predictable.

There are now four phases:

• Scoping: 4-6 weeks, where the maintainers and community determine the set of features we want to include in the release. A key deliverable here is ensuring that the Experimental channel does not get any bigger than it already is; we want to ensure that features make their way to Standard or are removed.
• GEP Iteration and Review: 5-7 weeks, where we work to update GEPs, and solidify and meet graduation criteria for in-scope GEPs.
• API Refinement and Documentation: 3-5 weeks, where we translate proposed changes from GEPs into changes to both the API specification and documentation.
• SIG-Network Review and Release Candidates: 2-4 weeks, where we perform our required upstream reviews, get any further required changes in, and release our release candidates so that implementations can get started with work on the new features asap.

For all the detail about this, please see the Release Cycle docs.

Relevant PRs:

• Adding Release Cycle Documentation by @robscott in #3063

Standard Channel Additions and Changes

The Standard channel is Gateway API's set of maximally-stable install files. Only features with the best testing and support are added to the standard channel. This channel should be considered GA or stable, and future changes will be fully backwards compatible.

Infrastructure Labels and Annotations 🎉

GEP-1867 added an infrastructure stanza to Gateway objects that is intended to carry infrastructure configuration specific to that Gateway object.

GEP-1762 adds a section for labels and annotations to this stanza that specifies labels and annotations to be annotated to all resources created to fulfill that Gateway request.

This feature can be used to affect the labels and annotations created on LoadBalancer Services by in-cluster implementations to fulfill the Gateway contract or by Cloud Load Balancing resources created by Cloud Providers.

This feature has graduated to Standard and is now considered GA or Stable.

This feature's name for conformance tests and GatewayClass status reporting is GatewayInfrastructurePropagation.

This feature's status is Extended, meaning that it is optional for implementations to support. If you're using Experimental Channel, you can refer to the supportedFeatures field in the status of any GatewayClass.

Relevant PRs:

• Remove experimental from gateway infrastructure by @keithmattix in #3272
• Validation for label keys and values according to Kubernetes specification by @snorwin in #3284

HTTPRoute Timeouts and Durations 🎉

The HTTPRoute Timeouts field on Route Rules has graduated to Standard and is now considered GA or Stable.

This field allows you to configure overall Request Timeouts as well as Backend Request Timeouts. For more information, refer to GEP 1742.

The relevant feature names this for conformance tests and GatewayClass status reporting are:

• HTTPRouteRequestTimeout for httproute.spec.rules[].timeouts.request
• HTTPRouteBackendTimeout for httproute.spec.rules[].timeouts.backendRequest

This feature's status is Extended, meaning that it is optional for implementations to support. If you're using Experimental Channel, you can refer to the supportedFeatures field in the status of any GatewayClass.

Relevant PRs:

• Graduate GEP-2257 and GEP-1742 to standard by @kflynn in #3210
• GEP2257 Duration parsing by @xtineskim in #3271

BackendProtocol Support 🎉

The previous coordinated work across both Gateway API and upstream Kubernetes which defined 3 new values for the AppProtocol field on Service Ports has graduated to Standard and is now considered GA or Stable.

The values are:

• 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.

The relevant feature names this for conformance tests and GatewayClass status reporting are:

• HTTPRouteBackendProtocolH2C for H2C support, when service.spec.ports[].appProtocol is kubernetes.io/h2c.
• HTTPRouteBackendProtocolWebSocket for Websocket support, when service.spec.ports[].appProtocol is kubernetes.io/ws or
  kubernetes.io/wss.

This feature's status is Extended, meaning that it is optional for implementations to support. If you're using Experimental Channel, you can refer to the supportedFeatures field in the status of any GatewayClass.

Relevant PRs:

• Backend Protocol Selection is no longer experimental and is now part of HTTPRoute Extended Conformance by @dprotaso in
  #3108

Other Standard channel changes

• Increased the limit on HTTPRoute matches from 8 to 64 by @howardjohn in #3205
• Adds the GatewayClassConditionReason "Unsupported" and clarifies when GatewayClassConditionReason "InvalidParameters" should be preferred by @mikemorris in #3048
• HTTPRoute - 503 Status Code MAY be returned for Kubernetes Services who don't have any healthy endpoints by @dprotaso in #3121
• Document the route kinds compatible for each protocolType by @abs007 in #2263
• Move GEP-995 to Implementable by @guicassolato in #3166
• Add policy label to BackendLBPolicy to make it recognizable in gwctl by @gauravkghildiyal in #3195
• remove unnecessary S in ProtocolType validation by @spacewander in #3185

Experimental Channel Additions and Changes

The Experimental Channel is Gateway API's channel for testing out changes and gaining confidence with them before allowing them to go to Standard.

This channel may include features that are changed or removed later!

BREAKING CHANGE

The Experimental supportedFeatures field in GatewayClass status has changed from being a list of strings to being a list of objects/structs with a name field.

This is to allow addding in extra information to each entry at a later date.

Relevant PRs:

• SupportedFeatures field in Gateway Class status are now presented as a list of objects by @LiorLieberman in #3200

HTTPRoute Retry support

GEP-1731 described how to add configuration of retries on HTTPRoute objects, and in this release, this change has moved to Experimental.

Please see the GEP reference document or the API reference for the details.

This feature has graduated to Experimental amd should now be used for testing and verification purposes only. Experimental features may be changed or removed in a future version.

This feature does not currently have a feature name defined.

This feature's status is Extended, meaning that it is optional for implementations to support.

As there is no feature name or conformance tests available for this feature as yet, please see your implementation's documentation to see if it is supported.

Relevant PRs:

• Adds support for configuring retries in HTTPRoute by @mikemorris in #3301
• Adds retry stanza within HTTPRouteRule to configure retrying unsuccessful requests to backends before sending a response to a client by @mikemorris in #3199

Percentage-based request mirroring

The existing Request Mirroring feature has been enhanced by allowing users to specify a percentage of requests they'd like mirrored. These changes are described in GEP-3171.

Please see the GEP reference document or the API reference for the details.

This feature has graduated to Experimental amd should now be used for testing and verification purposes only. Experimental features may be changed or removed in a future version.

This feature does not currently have a feature name defined.

This feature's status is Extended, meaning that it is optional f...

v1.1.0

v1.1.0

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:

Standard Channel

GRPCRoute has Graduated to GA 🎉

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

Service Mesh Support has Graduated to GA 🎉

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

Conformance Profiles and Reports

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

ParentRef Port field Graduated to GA

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

Experimental Channel

Session Persistence + BackendLBPolicy

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

Gateway Client Cert Verification

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

BackendTLSPolicy

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:

• the targetRef field is now a targetRefs list and these references no
  longer include a namespace field.
• the tls field has been renamed to validation
• the caCertRefs field has been renamed to caCertificateRefs
• the wellKnownCACerts field has been renamed to wellKnownCACertificates

Leading Contributors: @candita

Gateway Params

Gateways now feature a new field that allows references to
implementation-specific parameters, similar to GatewayClass.

Leading Contributors: @howardjohn

Everything Else

gwctl

• We've extended the get command to support gateways, gatewayclasses, and
  namespaces. (#2865, #2782, #2847, @jongwooo)
• The 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)
• We've added the ability to filter resources using labels (through the -l
  flag) with both the get and describe commands. (#2892, #2915, #2934,
  @yeedove)
• Bug fix: Prevent panic when describing gatewayclasses with no description
  (#2894, @pmalek)
• Properly handle different API versions (#3001, @gauravkghildiyal)
• Provide more detail in describe output (#2999, @gauravkghildiyal)
• Support JSON and YAML output format in get commands (#2940,
  @yashvardhan-kukreja)

Validation Changes

• TLS Configuration is no longer required on Gateway Listeners to enable more
  flexible TLS configuration. (#2721, @robscott)

Conformance Tests

• Conformance Profiles have been renamed and a new Mesh-GRPC profile has been
  added (#3019, @mlavacca):
  • HTTP -> Gateway-HTTP
  • GRPC -> Gateway-GRPC
  • TLS -> Gateway-TLS
  • Mesh -> Mesh-HTTP
• Fixed GatewayWithAttachedRoutes conformance test to not check that the
  HTTPRoute status includes an "Accepted: False" condition because this is not
  required by the specification. (#2548, @frankbu)
• A new comparison view has been added to our documentation that shows the
  extended features supported by every implementation that has submitted a
  conformance report (#2874, @xtineskim)
• Added SupportMeshConsumerRoute and SupportMeshClusterIPMatching supported
  features to more clearly communicate the purpose of existing Mesh conformance
  tests (#3035, @howardjohn)
• Add conformance test for HTTP listener isolation (#3047, @arkodg, @pleshakov)

Dependencies

• Gateway API has upgraded to Go v1.22 and Kubernetes v1.30 (#2988, @robscott)

Cleanup

• The validating webhook has been removed. CEL validation is now built-in to
  CRDs and replaces the webhook. (#2595, @robscott)
• BackendTLSPolicy WellKnownCACerts field has been updated to
  implementation-specific support (#2741, @sunjayBhatia)
• Clarify policy attachment by two of the same policy types when using section
  names. (#2442, @maleck13)
• Remove v1alpha2 directory from docs: (#2965, @robscott)

v1.1.0-rc2

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:

Conformance Profiles

• Add SupportMeshConsumerRoute and SupportMeshClusterIPMatching supported
  features to more clearly communicate the purpose of existing Mesh conformance
  tests (#3035, @howardjohn)
• Add conformance test for HTTP listener isolation (#3047, @arkodg, @pleshakov)

gwctl

• Properly handle different API versions (#3001, @gauravkghildiyal)
• Provide more detail in describe output (#2999, @gauravkghildiyal)
• Support JSON and YAML output format in get commands (#2940,
  @yashvardhan-kukreja)

Cleanup

• Revert accidental removal of experimental kustomize configuration (#3022,
  @howardjohn)

Dependencies

• sigs.k8s.io/controller-tools from 0.14.0 to 0.15.0 (#3031)
• sigs.k8s.io/controller-runtime from 0.17.0 to 0.18.0 (#3023, @tao12345666333)

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:

Standard Channel

GRPCRoute has Graduated to GA 🎉

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

Service Mesh Support has Graduated to GA 🎉

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

Conformance Profiles and Reports

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

ParentRef Port field Graduated to GA

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

Experimental Channel

Session Persistence + BackendLBPolicy

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

Gateway Client Cert Verification

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

BackendTLSPolicy

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:

• the targetRef field is now a targetRefs list and these references no
  longer include a namespace field.
• the tls field has been renamed to validation
• the caCertRefs field has been renamed to caCertificateRefs
• the wellKnownCACerts field has been renamed to wellKnownCACertificates

Leading Contributors: @candita

Gateway Params

Gateways now feature a new field that allows references to
implementation-specific parameters, similar to GatewayClass.

Leading Contributors: @howardjohn

Everything Else

gwctl

• We've extended the get command to support gateways, gatewayclasses, and
  namespaces. (#2865, #2782, #2847, @jongwooo)
• The 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)
• We've added the ability to filter resources using labels (through the -l
  flag) with both the get and describe commands. (#2892, #2915, #2934,
  @yeedove)
• Bug fix: Prevent panic when describing gatewayclasses with no description
  (#2894, @pmalek)

Validation Changes

• TLS Configuration is no longer required on Gateway Listeners to enable more
  flexible TLS configuration. (#2721, @robscott)

Conformance Tests

• Conformance Profiles have been renamed and a new Mesh-GRPC profile has been
  added (#3019, @mlavacca):
  • HTTP -> Gateway-HTTP
  • GRPC -> Gateway-GRPC
  • TLS -> Gateway-TLS
  • Mesh -> Mesh-HTTP
• Fixed GatewayWithAttachedRoutes conformance test to not check that the
  HTTPRoute status includes an "Accepted: False" condition because this is not
  required by the specification. (#2548, @frankbu)

Dependencies

• Gateway API has upgraded to Go v1.22 and Kubernetes v1.30 (#2988, @robscott)

Cleanup

• The validating webhook has been removed. CEL validation is now built-in to
  CRDs and replaces the webhook. (#2595, @robscott)
• BackendTLSPolicy WellKnownCACerts field has been updated to
  implementation-specific support (#2741, @sunjayBhatia)
• Clarify policy attachment by two of the same policy types when using section
  names. (#2442, @maleck13)
• Remove v1alpha2 directory from docs: (#2965, @robscott)

v1.0.0

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 are GA 🎉

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.

CEL Migration

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.

New Experimental Features

There are several exciting new experimental features in this release:

BackendTLSPolicy

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 Timeouts

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 Infrastructure Labels

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

WebSockets, HTTP/2, and More

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.

A new CLI tool: gwctl

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

Everything Else

Of course there's a lot more in this release:

Spec Clarifications

• Clarify that the Gateway Listener status AttachedRoutes field is a count of
  the number of Routes associated with a Listener regardless of Gateway or Route
  status. (#2396, @sunjayBhatia)
• Gateway: A new concept called "Listener Isolation" has been introduced to
  describe the recommendation that at most one Listener matches a request, and
  only Routes attached to that Listener are used for routing. (#2465, @robscott)
• Experimental Channel: For ParentRefs to be considered distinct, they either
  both need to specify a distinct SectionName, both need to specify a distinct
  Port, or both. (#2433, @robscott)
• Updated rules about Listener uniqueness to use the term distinct (#2436,
  @youngnick)

Status

• GatewayClass Status: A new experimental supportedFeatures field has been
  added. Implementations should populate this with the features they support.
  (#2461, @LiorLieberman, @robscott)
• GatewayClass Status: A new SupportedVersion condition has been added that MUST
  be set when a GatewayClass is accepted. (#2384, @robscott)
• Route Status: A new "PartiallyInvalid" condition has been added for all Route
  types. This condition also includes guidance for how partially invalid states
  should be handled with Gateway API. (#2429, @robscott)
• The condition reason GatewayReasonUnsupportedAddress for Accepted now ONLY
  applies when an address type is provided for a Gateway which it does not
  support.
  (#2412 @shaneutt)
• The condition reason GatewayReasonAddressNotAssigned for Programmed now
  ONLY applies to problems with dynamic address allocation.
  (#2412 @shaneutt)
• The condition reason 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)

Documentation

• A guide for Gateway API implementers is now included in the specification.
  (#2454, @youngnick)
• Gateway API versioning will continue to rely on two release channels -
  Standard and Experimental. New resources will start in the Experimental
  Channel with an alpha API Version and then graduate to the Standard Channel
  with a GA API version. Resources that already have Beta API versions will
  continue to have them, but no additional Gateway API resources will get a Beta
  API version. (#2446, @robscott)

Cleanup

• Validating Webhook logs now use Errorf instead of Fatalf. (#2361, @yylt)

Bug Fixes

• CEL validation for BackendTLSPolicy was fixed with corresponding tests added
  (#2491, @Ygnas)
• Fixes the API version for ReferenceGrant from v1 to v1beta1 in the
  GatewaySecretInvalidReferenceGrant conformance test YAML (#2494, @arkodg)
• Gateway infrastructure field is now a pointer (#2508, @danehans)

Conformance Tests

• h2c Backend Protocol conformance tests were added (#2456, @dprotaso)
• WebSocket Backend Protocol conformance tests were added (#2495, @dprotaso)
• New conformance test for Gateway Status AttachedRoutes (#2477, @danehans)
• Implemented the ExemptFeatures field for Experimental Conformance Profiles
  (#2515, @arkodg)

Other (Cleanup or Flake)

• Resources related to the validating webhook such as the 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)

v1.0.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. The following
represents the changes since v1.0.0-rc1:

Bug Fixes

• CEL validation for BackendTLSPolicy was fixed with corresponding tests added
  (#2491, @Ygnas)
• Fixes the API version for ReferenceGrant from v1 to v1beta1 in the
  GatewaySecretInvalidReferenceGrant conformance test YAML (#2494, @arkodg)
• Gateway infrastructure field is now a pointer (#2508, @danehans)

Conformance Tests

• h2c Backend Protocol conformance tests were added (#2456, @dprotaso)
• WebSocket Backend Protocol conformance tests were added (#2495, @dprotaso)
• New conformance test for Gateway Status AttachedRoutes (#2477, @danehans)
• Implemented the ExemptFeatures field for Experimental Conformance Profiles
  (#2515, @arkodg)

v1.0.0-rc1

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 are GA 🎉

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.

CEL Migration

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.

New Experimental Features

There are several exciting new experimental features in this release:

BackendTLSPolicy

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 Timeouts

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 Infrastructure Labels

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

WebSockets, HTTP/2, and More

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.

A new CLI tool: gwctl

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

Everything Else

Of course there's a lot more in this release:

Spec Clarifications

• Clarify that the Gateway Listener status AttachedRoutes field is a count of
  the number of Routes associated with a Listener regardless of Gateway or Route
  status. (#2396, @sunjayBhatia)
• Gateway: A new concept called "Listener Isolation" has been introduced to
  describe the recommendation that at most one Listener matches a request, and
  only Routes attached to that Listener are used for routing. (#2465, @robscott)
• Experimental Channel: For ParentRefs to be considered distinct, they either
  both need to specify a distinct SectionName, both need to specify a distinct
  Port, or both. (#2433, @robscott)
• Updated rules about Listener uniqueness to use the term distinct (#2436,
  @youngnick)

Status

• GatewayClass Status: A new experimental supportedFeatures field has been
  added. Implementations should populate this with the features they support.
  (#2461, @LiorLieberman, @robscott)
• GatewayClass Status: A new SupportedVersion condition has been added that MUST
  be set when a GatewayClass is accepted. (#2384, @robscott)
• Route Status: A new "PartiallyInvalid" condition has been added for all Route
  types. This condition also includes guidance for how partially invalid states
  should be handled with Gateway API. (#2429, @robscott)
• The condition reason GatewayReasonUnsupportedAddress for Accepted now ONLY
  applies when an address type is provided for a Gateway which it does not
  support.
  (#2412 @shaneutt)
• The condition reason GatewayReasonAddressNotAssigned for Programmed now
  ONLY applies to problems with dynamic address allocation.
  (#2412 @shaneutt)
• The condition reason 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)

Documentation

• A guide for Gateway API implementers is now included in the specification.
  (#2454, @youngnick)
• Gateway API versioning will continue to rely on two release channels -
  Standard and Experimental. New resources will start in the Experimental
  Channel with an alpha API Version and then graduate to the Standard Channel
  with a GA API version. Resources that already have Beta API versions will
  continue to have them, but no additional Gateway API resources will get a Beta
  API version. (#2446, @robscott)

Cleanup

• Validating Webhook logs now use Errorf instead of Fatalf. (#2361, @yylt)

Other (Cleanup or Flake)

• Resources related to the validating webhook such as the 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)

v0.8.1

v0.8.1

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.

Changes by Kind

Bug Fixes

• Fix CEL validation not handling missing listener hostname correctly. (#2370, @frankbu)
• Fix IPv6 parsing in conformance tests (#2375, @keithmattix)

Conformance Tests

• Add conformance test for multiple mirror filters. (#2359, @levikobi)