You are viewing documentation for Kubernetes version: v1.30
Kubernetes v1.30 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date information, see the latest version.
Gateway API v1.1: Service mesh, GRPCRoute, and a whole lot more
Following the GA release of Gateway API last October, Kubernetes SIG Network is pleased to announce the v1.1 release of Gateway API. In this release, several features are graduating to Standard Channel (GA), notably including support for service mesh and GRPCRoute. We're also introducing some new experimental features, including session persistence and client certificate verification.
What's new
Graduation to Standard
This release includes the graduation to Standard of four eagerly awaited features. This means they are no longer experimental concepts; inclusion in the Standard release channel denotes a high level of confidence in the API surface and provides guarantees of backward compatibility. Of course, as with any other Kubernetes API, Standard Channel features can continue to evolve with backward-compatible additions over time, and we certainly expect further refinements and improvements to these new features in the future. For more information on how all of this works, refer to the Gateway API Versioning Policy.
Service Mesh Support
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
Gateway API service mesh documentation
or see the
list of Gateway API implementations.
As an example, one could do a canary deployment of a workload deep in an application's call graph with an HTTPRoute as follows:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: color-canary
namespace: faces
spec:
parentRefs:
- name: color
kind: Service
group: ""
port: 80
rules:
- backendRefs:
- name: color
port: 80
weight: 50
- name: color2
port: 80
weight: 50
This would split traffic sent to the color Service in the faces namespace
50/50 between the original color Service and the color2 Service, using a
portable configuration that's easy to move from one mesh to another.
GRPCRoute
If you are already using the experimental version of 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.
ParentReference Port
The port field was added to ParentReference, allowing you to attach resources
to Gateway Listeners, Services, or other parent resources
(depending on the implementation). Binding to a port also allows you to attach
to multiple Listeners at once.
For example, you can attach an HTTPRoute to one or more specific Listeners of a
Gateway as specified by the Listener port, instead of the Listener name field.
For more information, see Attaching to Gateways.
Conformance Profiles and Reports
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.
New additions to Experimental channel
Gateway Client Certificate Verification
Gateways can now configure client cert verification for each Gateway Listener by
introducing a new 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.
The following example shows how the CACertificate stored in
the foo-example-com-ca-cert ConfigMap can be used to validate the certificates
presented by clients connecting to the foo-https Gateway Listener.
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: client-validation-basic
spec:
gatewayClassName: acme-lb
listeners:
name: foo-https
protocol: HTTPS
port: 443
hostname: foo.example.com
tls:
certificateRefs:
kind: Secret
group: ""
name: foo-example-com-cert
frontendValidation:
caCertificateRefs:
kind: ConfigMap
group: ""
name: foo-example-com-ca-cert
Session Persistence and 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.
Below is an example configuration of BackendLBPolicy that enables cookie-based
session persistence for the foo service. It sets the session name to
foo-session, defines absolute and idle timeouts, and configures the cookie to
be a session cookie:
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendLBPolicy
metadata:
name: lb-policy
namespace: foo-ns
spec:
targetRefs:
- group: core
kind: service
name: foo
sessionPersistence:
sessionName: foo-session
absoluteTimeout: 1h
idleTimeout: 30m
type: Cookie
cookieConfig:
lifetimeType: Session
Everything else
TLS Terminology Clarifications
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 implementations of this policy to properly handle the version upgrade, e.g. by backing up data and uninstalling the v1alpha2 version before installing this newer version.
Any references to v1alpha2 BackendTLSPolicy fields will need to be updated to v1alpha3. Specific changes to fields include:
targetRefbecomestargetRefsto allow a BackendTLSPolicy to attach to multiple targetstlsbecomesvalidationtls.caCertRefsbecomesvalidation.caCertificateRefstls.wellKnownCACertsbecomesvalidation.wellKnownCACertificates
For a full list of the changes included in this release, please refer to the v1.1.0 release notes.
Gateway API background
The idea of Gateway API was initially proposed at the 2019 KubeCon San Diego as the next generation of Ingress API. Since then, an incredible community has formed to develop what has likely become the most collaborative API in Kubernetes history. Over 200 people have contributed to this API so far, and that number continues to grow.
The maintainers would like to thank 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 the support of this dedicated and active community.
Try it out
Unlike other Kubernetes APIs, you don't need to upgrade to the latest version of Kubernetes to get the latest version of Gateway API. As long as you're running Kubernetes 1.26 or later, you'll be able to get up and running with this version of Gateway API.
To try out the API, follow our Getting Started Guide.
Get involved
There are lots of opportunities to get involved and help define the future of Kubernetes routing APIs for both ingress and service mesh.
- Check out the user guides to see what use-cases can be addressed.
- Try out one of the existing Gateway controllers.
- Or join us in the community and help us build the future of Gateway API together!