gateway api

BackendTLSPolicy

Mon, 01 Jan 0001 00:00:00 +0000

Standard Channel since v1.4.0

The BackendTLSPolicy resource is GA and has been part of the Standard Channel since v1.4.0. For more information on release channels, refer to our versioning guide.

BackendTLSPolicy is a Gateway API type for specifying the TLS configuration of the connection from the Gateway to a backend pod(s) via the Service API object.

Implementations may also decide to support the usage of BackendTLSPolicy for specifying the TLS configuration of the connection from the Gateway to services not connected via HTTPRoute, and any other kind of backend like InferencePool

How to Get Involved

Mon, 01 Jan 0001 00:00:00 +0000

This page contains links to all of the meeting notes, design docs and related discussions around the APIs. If you’re interested in working towards a formal role in the project, refer to the Contributor Ladder.

Feedback and Questions

For general feedback, questions or to share ideas please feel free to create a new discussion.

Bug Reports

Bug reports should be filed as GitHub Issues on this repo.

NOTE: If you’re reporting a bug that applies to a specific implementation of Gateway API and not the API specification itself, please check our implementations page to find links to the repositories where you can get help with your specific implementation.

Implementations

Mon, 01 Jan 0001 00:00:00 +0000

This document tracks downstream implementations and integrations of Gateway API and provides status and resource references for them.

Implementors and integrators of Gateway API are encouraged to update this document with status information about their implementations, the versions they cover, and documentation to help users get started. This status information should be no longer than a few paragraphs.

Conformance levels

There are three levels of Gateway API conformance:

Conformant implementations

These implementations have submitted at least one conformance report that has passes for:

Gateway API for Service Mesh

Mon, 01 Jan 0001 00:00:00 +0000

Standard Channel since v1.1.0

The GAMMA initiative work for supporting service mesh use cases has been part of the Standard Channel since v1.1.0 and is considered GA. For more information refer to our versioning guide.

The “GAMMA initiative” refers to the group that is defining how Gateway API can be used for Service Mesh. To date, this group has been able to define service mesh support in the Gateway API with relatively small changes. The most significant change that GAMMA has introduced to date is that, when configuring a service mesh, individual route resources (such as HTTPRoute) are associated directly with Service resources.

Gateway Enhancement Proposal (GEP)

Mon, 01 Jan 0001 00:00:00 +0000

Gateway Enhancement Proposals (GEPs) serve a similar purpose to the KEP process for the main Kubernetes project:

Ensure that changes to the API follow a known process and discussion in the OSS community.
Make changes and proposals discoverable (current and future).
Document design ideas, tradeoffs, decisions that were made for historical reference.
Record the results of larger community discussions.
Record changes to the GEP process itself.

Process

This diagram shows the state diagram of the GEP process at a high level, but the details are below.

Standard

Mon, 01 Jan 0001 00:00:00 +0000

BackendTrafficPolicy

Mon, 01 Jan 0001 00:00:00 +0000

Experimental Channel since v1.3.0

The BackendTrafficPolicy resource is a part of the Experimental Channel since v1.3.0. For more information on release channels, refer to our versioning guide.

BackendTrafficPolicy is a Gateway API type to configure the behavior of clients when targeting a valid backend resource.

Background

BackendTrafficPolicy is used to configure the behavior of clients when making requests targeting a backend, a grouping of like endpoints. Currently, this policy includes the ability to configure a RetryConstraint, which can dynamically limit the number of active retries targeting the specified backend, by defining a “retry budget”. Additional features may be added in the future.

Developer Guide

Mon, 01 Jan 0001 00:00:00 +0000

Project Management

We are using the GitHub issues and project dashboard to manage the list of TODOs for this project:

Issues labeled good first issue and help wanted are especially good for a first contribution.

We use milestones to track our progress towards releases. These milestones are generally labeled according to the semver release version tag that they represent, meaning that in general we only focus on the next release in the sequence until it is closed and the release is finished. Only Gateway API maintainers are able to create and attach issues to milestones.

The GAMMA Initiative (Gateway API for Service Mesh)

Mon, 01 Jan 0001 00:00:00 +0000

Gateway API was originally designed to manage traffic from clients outside the cluster to services inside the cluster – the ingress or north/south case. Over time, though, interest from service mesh users prompted the creation of the GAMMA (Gateway API for Mesh Management and Administration) initiative in 2022 to define how Gateway API could also be used for inter-service or east/west traffic within the same cluster.

The GAMMA initiative is a dedicated workstream within the Gateway API subproject, shepherded by the GAMMA leads, rather than being a separate subproject. GAMMA’s goal is to define how Gateway API can be used to configure a service mesh, with the intention of making minimal changes to Gateway API and always preserving the role-oriented nature of Gateway API. Additionally, we strive to advocate for consistency between implementations of Gateway API by service mesh projects, regardless of their technology stack or proxy.

Gateway

Mon, 01 Jan 0001 00:00:00 +0000

Standard Channel since v0.5.0

The Gateway resource is GA and has been part of the Standard Channel since v0.5.0. For more information on release channels, refer to our versioning guide.

A Gateway is 1:1 with the lifecycle of the configuration of infrastructure. When a user creates a Gateway, some load balancing infrastructure is provisioned or configured (see below for details) by the GatewayClass controller. Gateway is the resource that triggers actions in this API. Other resources in this API are configuration snippets until a Gateway has been created to link the resources together.

HTTP routing

Mon, 01 Jan 0001 00:00:00 +0000

The HTTPRoute resource allows you to match on HTTP traffic and direct it to Kubernetes backends. This guide shows how the HTTPRoute matches traffic on host, header, and path fields and forwards it to different Kubernetes Services.

The following diagram describes a required traffic flow across three different Services:

Traffic to foo.example.com/login is forwarded to foo-svc
Traffic to bar.example.com/* with a env: canary header is forwarded to bar-svc-canary
Traffic to bar.example.com/* without the header is forwarded to bar-svc

Getting started with Gateway API

Mon, 01 Jan 0001 00:00:00 +0000

Welcome to the Gateway API! This page is the best place to start, whether you’re a new user or migrating from another ingress solution.

For New Users

If you are new to Gateway API, we recommend the following path:

1. Install Gateway API CRDs and a Controller

You can either install a Gateway controller which often installs the CRDs for you, or install the Gateway API CRDs manually.

2. Try out the guides

Memorandum

Mon, 01 Jan 0001 00:00:00 +0000

Deploying a simple Gateway

Mon, 01 Jan 0001 00:00:00 +0000

This guide is a great place to start if you are new to Gateway API. It shows the simplest possible deployment: a Gateway and Route resource deployed together by the same owner. This represents a similar kind of model used for Ingress. In this guide, a Gateway and HTTPRoute are deployed which match all HTTP traffic and directs it to a single Service named foo-svc.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-web
spec:
  gatewayClassName: example
  listeners:
  - protocol: HTTP
    port: 80
    name: prod-web-gw
    allowedRoutes:
      namespaces:
        from: Same

The Gateway represents the instantiation of a logical load balancer and the GatewayClass defines the load balancer template when users create a Gateway. The example Gateway is templated from a hypothetical example GatewayClass, which is meant to be a placeholder and substituted by users. Here is a list of available Gateway Implementation that can be used to determine the correct GatewayClass based on the specific infrastructure provider.

Documentation Style Guide

Mon, 01 Jan 0001 00:00:00 +0000

Gateway API aims to adhere to the upstream Kubernetes Documentation Style Guide wherever possible. This guide should be considered an extension of that guide. Whenever there is conflicting guidance, the information contained in this guide has precedence for Gateway API documentation.

Name of the Project

This project is named “Gateway API”, not “the Gateway API”. As such, the only time it is acceptable to use “the Gateway API” is when it is part of a broader term, such as “the Gateway API maintainers”.

Experimental

Mon, 01 Jan 0001 00:00:00 +0000

GatewayClass

Mon, 01 Jan 0001 00:00:00 +0000

Standard Channel since v0.5.0

The GatewayClass resource is GA and has been part of the Standard Channel since v0.5.0. For more information on release channels, refer to our versioning guide.

GatewayClass is cluster-scoped resource defined by the infrastructure provider. This resource represents a class of Gateways that can be instantiated.

Note: GatewayClass serves the same function as the networking.IngressClass resource.

kind: GatewayClass
metadata:
  name: cluster-gateway
spec:
  controllerName: "example.net/gateway-controller"

We expect that one or more GatewayClasses will be created by the infrastructure provider for the user. It allows decoupling of which mechanism (e.g. controller) implements the Gateways from the user. For instance, an infrastructure provider may create two GatewayClasses named internet and private to reflect Gateways that define Internet-facing vs private, internal applications.

HTTP path redirects and rewrites

Mon, 01 Jan 0001 00:00:00 +0000

HTTPRoute resources can issue redirects to clients or rewrite paths sent upstream using filters. This guide shows how to use these features.

Note that redirect and rewrite filters are mutually incompatible. Rules cannot use both filter types at once.

Redirects

Redirects return HTTP 3XX responses to a client, instructing it to retrieve a different resource. RequestRedirect rule filters instruct Gateways to emit a redirect response to requests matching a filtered HTTPRoute rule.

The Different Facets of a Service

Mon, 01 Jan 0001 00:00:00 +0000

The Kubernetes Service resource is considerably more complex than people often realize. When you create a Service, typically the cluster machinery will:

Allocate a cluster-wide IP address for the Service itself (its cluster IP);
Allocate a DNS name for the Service, resolving to the cluster IP (its DNS name);
Collect the separate cluster-wide IP addresses assigned to each Pod matched by the Service’s selector (the endpoint IPs) into the Service’s Endpoints or EndpointSlices.
Configure the network such that traffic to the cluster IP will be load-balanced across all the endpoint IPs.

Unfortunately, these implementation details become very important when considering how Gateway API can work for service meshes!

Enhancement Requests

Mon, 01 Jan 0001 00:00:00 +0000

Inspired by Kubernetes enhancements, Gateway API provides a process for introducing new functionality or considerable changes to the project. The enhancement process will evolve over time as the project matures.

Enhancements provides the basis of a community roadmap. Enhancements may be filed by anyone, but require approval from a maintainer to accept the enhancement into the project.

What is Considered an Enhancement?

An enhancement is generally anything that:

Introduces changes to an API.
Needs significant effort to implement.
Requires documentation to utilize.
Impacts how a system is operated including addition or removal of significant capabilities.

It is unlikely to require an enhancement if it:

GRPCRoute

Mon, 01 Jan 0001 00:00:00 +0000

Standard Channel since v1.1.0

The GRPCRoute resource is GA and has been part of the Standard Channel since v1.1.0. For more information on release channels, refer to our versioning guide.

GRPCRoute is a Gateway API type for specifying routing behavior of gRPC requests from a Gateway listener to an API object, i.e. Service.

Background

While it is possible to route gRPC with HTTPRoutes or via custom, out-of-tree CRDs, in the long run, this leads to a fragmented ecosystem.

HTTP Header Modifiers

Mon, 01 Jan 0001 00:00:00 +0000

HTTPRoute resources can modify the headers of HTTP requests and the HTTP responses from clients. There are two types of filters available to meet these requirements: RequestHeaderModifier and ResponseHeaderModifier.

This guide shows how to use these features.

Note that these features are compatible. HTTP headers of the incoming requests and the headers of their responses can both be modified using a single HTTPRoute resource.

HTTP Request Header Modifier

Extended Support Feature: HTTPRouteBackendRequestHeaderModification

This feature is part of extended support. For more information on support levels, refer to our conformance guide.

HTTP header modification is the process of adding, removing, or modifying HTTP headers in incoming requests.

Implementable

Mon, 01 Jan 0001 00:00:00 +0000

Migrating from Ingress

Mon, 01 Jan 0001 00:00:00 +0000

Gateway API is the successor to the Ingress API. This guide provides a general overview for migrating from any Ingress implementation to Gateway API. It focuses on the core concepts, differences, and feature mappings between Ingress and Gateway API, and provides a manual conversion example.

Are you an Ingress-NGINX user?

If you are specifically using Ingress-NGINX, we recommend also checking out the Ingress-NGINX Migration Guide for more tailored advice and resources.

HTTP traffic splitting

Mon, 01 Jan 0001 00:00:00 +0000

The HTTPRoute resource allows you to specify weights to shift traffic between different backends. This is useful for splitting traffic during rollouts, canarying changes, or for emergencies. The HTTPRoutespec.rules.backendRefs accepts a list of backends that a route rule will send traffic to. The relative weights of these backends define the split of traffic between them. The following YAML snippet shows how two Services are listed as backends for a single route rule. This route rule will split traffic 90% to foo-v1 and 10% to foo-v2.

HTTPRoute

Mon, 01 Jan 0001 00:00:00 +0000

Standard Channel since v0.5.0

The HTTPRoute resource is GA and has been part of the Standard Channel since v0.5.0. For more information on release channels, refer to our versioning guide.

HTTPRoute is a Gateway API type for specifying routing behavior of HTTP requests from a Gateway listener to an API object, i.e. Service.

Spec

The specification of an HTTPRoute consists of:

ParentRefs- Define which Gateways this Route wants to be attached to.
Hostnames (optional)- Define a list of hostnames to use for matching the Host header of HTTP requests.
Rules- Define a list of rules to perform actions against matching HTTP requests. Each rule consists of matches, filters (optional), backendRefs (optional), timeouts (optional), and name (optional) fields.

The following illustrates an HTTPRoute that sends all traffic to one Service:

Controller Matching Wizard

Mon, 01 Jan 0001 00:00:00 +0000

A Welcome Guide for Ingress-NGINX Users

Mon, 01 Jan 0001 00:00:00 +0000

Welcome! If you’re an Ingress-NGINX user, you’re in the right place. This page is a central hub of resources for those considering or actively migrating to Gateway API. We aim to continue to build out this page to be more comprehensive over time. If you’re looking for a general overview of migrating from Ingress, please refer to our Migrating from Ingress guide.

We understand that migrations can be complex, and our goal is to provide you with the information and tools you need for a smooth transition.

Release Cycle

Mon, 01 Jan 0001 00:00:00 +0000

In Gateway API 1.2+, we will be following a more structured and predictable release cycle that is inspired by the upstream Kubernetes release cycle.

Goals

Ensure a predictable release schedule that enables 2-3 releases a year
Minimize the amount of time required from upstream API approvers and make it more predictable
Avoid last minute additions to the scope of a release
Prevent experimental channel from growing by requiring GEPs to leave or graduate before new ones can be added
Ensure that SIG-Network TLs are in the loop throughout the process, and have a meaningful opportunity to review changes before a release
Provide more advance notice to everyone (SIG-Network TLs, Docs Reviewers, Implementations, etc)

Phases

1. Scoping

Timeline: 4-6 weeks

Contributor Ladder

Mon, 01 Jan 0001 00:00:00 +0000

Within the Kubernetes community, the concept of a contributor ladder has been developed to define how individuals can earn formal roles within the project. The Gateway API contributor ladder largely follows the roles defined by the broader Kubernetes community, though there are some aspects that are unique to this community.

Goals

We hope that this doc will provide an initial step towards the following goals:

Ensure the long term health of the Gateway API community
Encourage new contributors to work towards formal roles and responsibilities in the project
Clearly define the path towards leadership roles
Develop a strong leadership pipeline so we have great candidates to fill project leadership roles

Scope

The following repositories are covered by this doc:

HTTP request mirroring

Mon, 01 Jan 0001 00:00:00 +0000

Extended Support Feature: HTTPRouteRequestMirror

This feature is part of extended support. For more information on support levels, refer to our conformance guide.

The HTTPRoute resource can be used to mirror requests to multiple backends. This is useful for testing new services with production traffic.

Mirrored requests will only be sent to one single destination endpoint within this backendRef, and responses from this backend MUST be ignored by the Gateway.

Provisional

Mon, 01 Jan 0001 00:00:00 +0000

HTTP query parameter matching

Mon, 01 Jan 0001 00:00:00 +0000

Extended Support Feature: HTTPRouteQueryParamMatching

This feature is part of extended support. For more information on support levels, refer to our conformance guide.

The HTTPRoute resource can be used to match requests based on query parameters. This guide shows how to use this functionality.

Matching requests based on a single query parameter

The following HTTPRoute splits traffic between two backends based on the value of the animal query parameter:

HTTP method matching

Mon, 01 Jan 0001 00:00:00 +0000

Extended Support Feature: HTTPRouteMethodMatching

This feature is part of extended support. For more information on support levels, refer to our conformance guide.

The HTTPRoute resource can be used to match requests based on the HTTP method. This guide shows how to use this functionality.

Matching requests based on the HTTP method

The following HTTPRoute splits traffic between two backends based on the HTTP method of the request:

ReferenceGrant

Mon, 01 Jan 0001 00:00:00 +0000

Standard Channel since v0.6.0

The ReferenceGrant resource is Beta and part of the Standard Channel since v0.6.0. For more information on release channels, refer to our versioning guide.

This resource was originally named “ReferencePolicy”. It was renamed to “ReferenceGrant” to avoid any confusion with policy attachment.

A ReferenceGrant can be used to enable cross namespace references within Gateway API. In particular, Routes may forward traffic to backends in other namespaces, or Gateways may refer to Secrets in another namespace.

HTTP timeouts

Mon, 01 Jan 0001 00:00:00 +0000

Extended Support Feature: HTTPRouteRequestTimeout

This feature is part of extended support. For more information on support levels, refer to our conformance guide.

The HTTPRoute resource can be used to configure timeouts for HTTP requests. This is useful for preventing long-running requests from consuming resources and for providing a better user experience.

The timeouts field in an HTTPRouteRule can be used to specify a request timeout.

Setting a request timeout

The following HTTPRoute sets a request timeout of 500 milliseconds for all requests with a path prefix of /request-timeout:

TLSRoute

Mon, 01 Jan 0001 00:00:00 +0000

Standard Channel since v1.5.0

The TLSRoute resource is GA and has been part of the Standard Channel since v1.5.0. For more information on release channels, refer to our versioning guide.

TLSRoute is a Gateway API type for specifying routing behavior of TLS requests from a client to an API object, i.e. Service. It allows to route traffic to specific backend based on the Server Name Indication (SNI) hostname provided during the TLS handshake.

Cross-Origin Resource Sharing (CORS)

Mon, 01 Jan 0001 00:00:00 +0000

Extended Support Feature: HTTPRouteCORS

This feature is part of extended support, and requires your implementation to support the feature HTTPRouteCORS. For more information on support levels, refer to our conformance guide.

Standard Channel since v1.5.0

The HTTPRouteCORS feature has been part of the Standard Channel since v1.5.0. For more information on release channels, refer to our versioning guide.

The HTTPRoute resource can be used to configure Cross-Origin Resource Sharing (CORS). CORS is a security feature that allows or denies web applications running at one domain to make requests for resources from a different domain.

ListenerSet

Mon, 01 Jan 0001 00:00:00 +0000

Standard Channel since v1.5.0

The ListenerSet resource is GA and has been part of the Standard Channel since v1.5.0. For more information on release channels, refer to our versioning guide.

A ListenerSet is a Gateway API type for specifying additional listeners for a Gateway. It decouples network listener configurations—such as ports, hostnames, and TLS termination—from the central Gateway resource.

Background

ListenerSets allow teams to independently define and attach groups of listeners to a central, shared Gateway. This enables self-service TLS configuration, improves multi-tenancy by allowing decentralized listener management, and allows scaling beyond the 64-listener limit of a single Gateway resource.

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

gateway.networking.k8s.io/v1

Package v1 contains API Schema definitions for the gateway.networking.k8s.io API group.

Resource Types

AbsoluteURI

Underlying type: string

The AbsoluteURI MUST NOT be a relative URI, and it MUST follow the URI syntax and encoding rules specified in RFC3986. The AbsoluteURI MUST include both a scheme (e.g., “http” or “spiffe”) and a scheme-specific-part. URIs that include an authority MUST include a fully qualified domain name or IP address as the host. gateway:util:excludeFromCRD The below regex is taken from the regex section in RFC 3986 with a slight modification to enforce a full URI and not relative. </gateway:util:excludeFromCRD>

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

gateway.networking.k8s.io/v1

Package v1 contains API Schema definitions for the gateway.networking.k8s.io API group.

Resource Types

AbsoluteURI

Underlying type: string

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

gateway.networking.k8s.io/v1

Package v1 contains API Schema definitions for the gateway.networking.k8s.io API group.

Resource Types

AbsoluteURI

Underlying type: string

v1.5

Mon, 01 Jan 0001 00:00:00 +0000

The following tables are populated from the conformance reports uploaded by project implementations. They are separated into the extended features that each project supports listed in their reports. Implementations only appear in this page if they pass Core conformance for the resource type, and the features listed should be Extended features. Implementations that submit conformance reports with skipped tests won’t appear in the tables.

Warning

This page is under active development and is not in its final form, especially for the project name and the names of the features. However, as it is based on submitted conformance reports, the information is correct.

Cross-Namespace routing

Mon, 01 Jan 0001 00:00:00 +0000

Gateway API has core support for cross Namespace routing. This is useful when more than one user or team is sharing the underlying networking infrastructure, yet control and configuration must be segmented to minimize access and fault domains.

Gateways and Routes can be deployed into different Namespaces and Routes can attach to Gateways across Namespace boundaries. This allows user access control to be applied differently across Namespaces for Routes and Gateways, effectively segmenting access and control to different parts of the cluster-wide routing configuration. The ability for Routes to attach to Gateways across Namespace boundaries are governed by Route Attachment. Route attachment is explored in this guide and demonstrates how independent teams can safely share the same Gateway.

TLS Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Gateway API allows for a variety of ways to configure TLS. This document lays out various TLS settings and gives general guidelines on how to use them effectively.

Although this doc covers the most common forms of TLS configuration with Gateway API, some implementations may also offer implementation-specific extensions that allow for different or more advanced forms of TLS configuration. In addition to this documentation, it’s worth reading the TLS documentation for whichever implementation(s) you’re using with Gateway API.

TLS routing

Mon, 01 Jan 0001 00:00:00 +0000

The TLSRoute resource allows you to match on TLS metadata and direct it to Kubernetes backends. This guide shows how the TLSRoute matches traffic on hostname and forwards it to different Kubernetes Services, using either Passthrough or Terminate TLS modes on the Gateway.

In order to receive traffic from a Gateway a TLSRoute resource must be configured with ParentRefs which reference the parent gateway(s) that it should be attached to. The following example shows how the combination of Gateway and TLSRoute would be configured to serve TLS traffic using both Passthrough and Terminate modes (when supported by the Gateway API implementation):

TCP routing

Mon, 01 Jan 0001 00:00:00 +0000

Experimental Channel

The TCPRoute resource described below is currently only included in the “Experimental” channel of Gateway API. For more information on release channels, refer to our versioning guide.

Gateway API is designed to work with multiple protocols and [TCPRoute][tcproute] is one such route which allows for managing [TCP][tcp] traffic.

In this example, we have one Gateway resource and two TCPRoute resources that distribute the traffic with the following rules:

gRPC routing

Mon, 01 Jan 0001 00:00:00 +0000

The GRPCRoute resource allows you to match on gRPC traffic and direct it to Kubernetes backends. This guide shows how the GRPCRoute matches traffic on host, header, and service, and method fields and forwards it to different Kubernetes Services.

The following diagram describes a required traffic flow across three different Services:

Traffic to foo.example.com for the com.Example.Login method is forwarded to foo-svc
Traffic to bar.example.com with an env: canary header is forwarded to bar-svc-canary for all services and methods
Traffic to bar.example.com without the header is forwarded to bar-svc for all services and methods

Backend Protocol

Mon, 01 Jan 0001 00:00:00 +0000

Extended Support Features: HTTPRouteBackendProtocolH2C, HTTPRouteBackendProtocolWebSocket

These features are part of extended support. For more information on support levels, refer to our conformance guide.

Standard Channel since v1.2.0

This concept has been part of the Standard Channel since v1.2.0. For more information on release channels, refer to our versioning guide.

Not all implementations of Gateway API support automatic protocol selection. In some cases protocols are disabled without an explicit opt-in.

Gateway infrastructure labels and annotations

Mon, 01 Jan 0001 00:00:00 +0000

Extended Support Feature: GatewayInfrastructurePropagation

This feature is part of extended support. For more information on support levels, refer to our conformance guide.

Gateway API implementations are responsible for creating the backing infrastructure needed to make each Gateway work. For example, implementations running in a Kubernetes cluster often create Services and Deployments, while cloud-based implementations may create cloud load balancer resources. In many cases, it can be helpful to be able to propagate labels or annotations to these generated resources.

ListenerSet

Mon, 01 Jan 0001 00:00:00 +0000

Extended Support Feature: ListenerSet

This feature is part of extended support. For more information on support levels, refer to our conformance guide.

ListenerSets allow teams to define ports, hostnames, and TLS certificates in separate resources rather than cramming everything into one giant Gateway object which has a limit of 64 listeners. This enables a delegated management model suitable for high-scale, multi-tenant environments.

As such, you might use ListenerSets for the following advantages:

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

gateway.networking.x-k8s.io/v1alpha1

gateway.networking.x-k8s.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the gateway.networking.k8s-x.io API group.

Resource Types

BackendTrafficPolicySpec

BackendTrafficPolicySpec define the desired state of BackendTrafficPolicy Note: there is no Override or Default policy configuration.

Appears in:

XBackendTrafficPolicy

Field	Description	Validation
`targetRefs` LocalPolicyTargetReference array	TargetRefs identifies API object(s) to apply this policy to. Currently, Backends (A grouping of like endpoints such as Service, ServiceImport, or any implementation-specific backendRef) are the only valid API target references. Currently, a TargetRef can not be scoped to a specific port on a Service.	MaxItems: 16 MinItems: 1
`retryConstraint` RetryConstraint :warning: Experimental	RetryConstraint defines the configuration for when to allow or prevent further retries to a target backend, by dynamically calculating a ‘retry budget’. This budget is calculated based on the percentage of incoming traffic composed of retries over a given time interval. Once the budget is exceeded, additional retries will be rejected. For example, if the retry budget interval is 10 seconds, there have been 1000 active requests in the past 10 seconds, and the allowed percentage of requests that can be retried is 20% (the default), then 200 of those requests may be composed of retries. Active requests will only be considered for the duration of the interval when calculating the retry budget. Retrying the same original request multiple times within the retry budget interval will lead to each retry being counted towards calculating the budget. Configuring a RetryConstraint in BackendTrafficPolicy is compatible with HTTPRoute Retry settings for each HTTPRouteRule that targets the same backend. While the HTTPRouteRule Retry stanza can specify whether a request will be retried, and the number of retry attempts each client may perform, RetryConstraint helps prevent cascading failures such as retry storms during periods of consistent failures. After the retry budget has been exceeded, additional retries to the backend MUST return a 503 response to the client. Additional configurations for defining a constraint on retries MAY be defined in the future. Support: Extended gateway:experimental
`sessionPersistence` SessionPersistence	SessionPersistence defines and configures session persistence for the backend. Support: Extended

BudgetDetails

BudgetDetails specifies the details of the budget configuration, like the percentage of requests in the budget, and the interval between checks.

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

gateway.networking.x-k8s.io/v1alpha1

gateway.networking.x-k8s.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the gateway.networking.k8s-x.io API group.

Resource Types

BackendTrafficPolicySpec

BackendTrafficPolicySpec define the desired state of BackendTrafficPolicy Note: there is no Override or Default policy configuration.

Appears in:

XBackendTrafficPolicy

Field	Description	Validation
`targetRefs` LocalPolicyTargetReference array	TargetRefs identifies API object(s) to apply this policy to. Currently, Backends (A grouping of like endpoints such as Service, ServiceImport, or any implementation-specific backendRef) are the only valid API target references. Currently, a TargetRef cannot be scoped to a specific port on a Service.	MaxItems: 16 MinItems: 1
`retryConstraint` RetryConstraint :warning: Experimental	RetryConstraint defines the configuration for when to allow or prevent further retries to a target backend, by dynamically calculating a ‘retry budget’. This budget is calculated based on the percentage of incoming traffic composed of retries over a given time interval. Once the budget is exceeded, additional retries will be rejected. For example, if the retry budget interval is 10 seconds, there have been 1000 active requests in the past 10 seconds, and the allowed percentage of requests that can be retried is 20% (the default), then 200 of those requests may be composed of retries. Active requests will only be considered for the duration of the interval when calculating the retry budget. Retrying the same original request multiple times within the retry budget interval will lead to each retry being counted towards calculating the budget. Configuring a RetryConstraint in BackendTrafficPolicy is compatible with HTTPRoute Retry settings for each HTTPRouteRule that targets the same backend. While the HTTPRouteRule Retry stanza can specify whether a request will be retried, and the number of retry attempts each client may perform, RetryConstraint helps prevent cascading failures such as retry storms during periods of consistent failures. After the retry budget has been exceeded, additional retries to the backend MUST return a 503 response to the client. Additional configurations for defining a constraint on retries MAY be defined in the future. Support: Extended gateway:experimental
`sessionPersistence` SessionPersistence	SessionPersistence defines and configures session persistence for the backend. Support: Extended

BudgetDetails

BudgetDetails specifies the details of the budget configuration, like the percentage of requests in the budget, and the interval between checks.

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

gateway.networking.x-k8s.io/v1alpha1

gateway.networking.x-k8s.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the gateway.networking.k8s-x.io API group.

Resource Types

BackendTrafficPolicySpec

BackendTrafficPolicySpec define the desired state of BackendTrafficPolicy Note: there is no Override or Default policy configuration.

Appears in:

XBackendTrafficPolicy

Field	Description	Validation
`targetRefs` LocalPolicyTargetReference array	TargetRefs identifies API object(s) to apply this policy to. Currently, Backends (A grouping of like endpoints such as Service, ServiceImport, or any implementation-specific backendRef) are the only valid API target references. Currently, a TargetRef cannot be scoped to a specific port on a Service.	MaxItems: 16 MinItems: 1
`retryConstraint` RetryConstraint :warning: Experimental	RetryConstraint defines the configuration for when to allow or prevent further retries to a target backend, by dynamically calculating a ‘retry budget’. This budget is calculated based on the percentage of incoming traffic composed of retries over a given time interval. Once the budget is exceeded, additional retries will be rejected. For example, if the retry budget interval is 10 seconds, there have been 1000 active requests in the past 10 seconds, and the allowed percentage of requests that can be retried is 20% (the default), then 200 of those requests may be composed of retries. Active requests will only be considered for the duration of the interval when calculating the retry budget. Retrying the same original request multiple times within the retry budget interval will lead to each retry being counted towards calculating the budget. Configuring a RetryConstraint in BackendTrafficPolicy is compatible with HTTPRoute Retry settings for each HTTPRouteRule that targets the same backend. While the HTTPRouteRule Retry stanza can specify whether a request will be retried, and the number of retry attempts each client may perform, RetryConstraint helps prevent cascading failures such as retry storms during periods of consistent failures. After the retry budget has been exceeded, additional retries to the backend MUST return a 503 response to the client. Additional configurations for defining a constraint on retries MAY be defined in the future. Support: Extended gateway:experimental
`sessionPersistence` SessionPersistence	SessionPersistence defines and configures session persistence for the backend. Support: Extended

BudgetDetails

BudgetDetails specifies the details of the budget configuration, like the percentage of requests in the budget, and the interval between checks.

v1.4

Mon, 01 Jan 0001 00:00:00 +0000

Warning

API Overview

Mon, 01 Jan 0001 00:00:00 +0000

Gateway API is a complex API, solving a complex problem. The designers of Gateway API have done our best to try to meet the dual demands of configuration flexibility and high usability.

In order to do that, we’ve needed to create a number of new ideas and concepts, while still echoing ideas from the rest of Kubernetes. This page goes through the most important things to learn when you are starting out in Gateway API.

Troubleshooting and Status

Mon, 01 Jan 0001 00:00:00 +0000

One of the biggest problems when using any Kubernetes object is how to know if the state requested by that object (generally encoded in its spec stanza) has been accepted, and when the state has been achieved. The current status of most Kubernetes objects is stored in the status subresource and stanza, but in Gateway API, we’ve needed to lean hard into emphasizing the use of status.

One of the driving rules for Gateway API object design has been to try to ensure that, when a user creates an object, they can see as much as possible of the state of the system in the status of that object. And, if that is not possible, that there is a way to find out what other objects are relevant.

Conformance

Mon, 01 Jan 0001 00:00:00 +0000

This API covers a broad set of features and use cases and has been implemented widely. This combination of both a large feature set and variety of implementations requires clear conformance definitions and tests to ensure the API provides a consistent experience wherever it is used.

When considering Gateway API conformance, there are three important concepts:

1. Release Channels

Within Gateway API, release channels are used to indicate the stability of a field or resource. The “standard” channel of the API includes fields and resources that have graduated to “beta”. The “experimental” channel of the API includes everything in the “standard” channel, along with experimental fields and resources that may still be changed in breaking ways or removed altogether. For more information on this concept, refer to our versioning documentation.

Roles and Personas

Mon, 01 Jan 0001 00:00:00 +0000

Background

In the original design of Kubernetes, Ingress and Service resources were based on a usage model in which the developers who create Services and Ingresses controlled all aspects of defining and exposing their applications to their users.

In practice, though, clusters and their infrastructure tend to be shared, which the original Ingress model doesn’t capture very well. A critical factor is that when infrastructure is shared, not everyone using the infrastructure has the same concerns, and to be successful, an infrastructure project needs to address the needs of all the users.

Security

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Gateway API has been designed to enable granular authorization for each role in a typical organization.

Resources

Gateway API has 3 primary API resources:

GatewayClass defines a set of gateways with a common configuration and behavior.
Gateway requests a point where traffic can be translated to Services within the cluster.
Routes describe how traffic coming via the Gateway maps to the Services.

Roles and personas

There are 3 primary roles in Gateway API, as described in roles and personas:

Tools

Mon, 01 Jan 0001 00:00:00 +0000

Gateway API has tooling to facilitate interacting with the resources.

`ingress2gateway`

Interested in seeing what your ingress resources will look like in Gateway API? ingress2gateway provides an easy manner to translate provider-specific resources to Gateway API resources. Managed by the Gateway API SIG-Network subproject.

Get started with kubernetes-sigs/ingress2gateway: installation!

`gwctl`

A command line tool for managing your Gateway API resources. Explore your policies, xRoutes, and interact with your resources.

Get started with kubernetes-sigs/gwctl: installation!

Use cases

Mon, 01 Jan 0001 00:00:00 +0000

Gateway API covers a very wide range of use cases (which is both a strength and a weakness!). This page is emphatically not meant to be an exhaustive list of these use cases: rather, it is meant to provide some examples that can be helpful to demonstrate how the API can be used.

In all cases, it’s very important to bear in mind the roles and personas used in Gateway API. The use cases presented here are deliberately described in terms of Ana, Chihiro, and Ian: they are the ones for whom the API must be usable. (It’s also important to remember that even though these roles might be filled by the same person, especially in smaller organizations, they all have distinct concerns that we need to consider separately.)

Versioning

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Each new release of Gateway API is defined with a “bundle version” that represents the Git tag of a release, such as v1.0.0. This contains the following:

API Types (Go bindings for the resources)
CRDs (Kubernetes definitions of the resources)

Release Channels

Release channels are used to indicate feature stability within Gateway API. All new features and resources start in the Experimental release channel. From that point, these may graduate to the Standard release channel or be dropped from the API entirely.

Traffic Matching

Mon, 01 Jan 0001 00:00:00 +0000

Listener selection

When Routes attach, the process can be thought of as a negotiation between the Listeners designated by the Route in its parentRef, and the settings on those Listeners that restrict what Routes can attach.

When considering the parentRef of a Route, the set of Listeners that the Route may attach to is called the set of relevant Listeners.

A Route that specifies a parentRef of a Gateway that contains multiple Listeners is effectively attempting to attach to all Listeners on that Gateway, and all Listeners are relevant.

Hostnames in Gateway API

Mon, 01 Jan 0001 00:00:00 +0000

Introduction/Purpose of this document

This document is intended to help both users of Gateway API and integrators who build systems that programmatically interact with Gateway API objects to better understand how Gateway API uses hostnames, and what are the most important things to know about these usages.

Where and how can you configure a hostname?

Hostnames are used to assert whether a Route can attach to a Gateway or Listener via hostname intersection, as well as to choose which Listener and Route should accept a particular request, determined through routing discrimination. Both hostname intersection and routing discrimination are defined later in this document.

v1.3

Mon, 01 Jan 0001 00:00:00 +0000

Warning

v1.2

Mon, 01 Jan 0001 00:00:00 +0000

Warning

v1.1

Mon, 01 Jan 0001 00:00:00 +0000

Warning

v1.0

Mon, 01 Jan 0001 00:00:00 +0000

Warning

Metaresources and Policy Attachment

Mon, 01 Jan 0001 00:00:00 +0000

Gateway API defines a Kubernetes object that augments the behavior of an object in a standard way as a Metaresource. ReferenceGrant is an example of this general type of metaresource, but it is far from the only one.

Gateway API also defines a pattern called Policy Attachment, which augments the behavior of an object to add additional settings that can’t be described within the spec of that object.

A “Policy Attachment” is a specific type of metaresource that can affect specific settings across either one object (this is “Direct Policy Attachment”), or objects in a hierarchy (this is “Inherited Policy Attachment”).

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1016: GRPCRoute

Issue: #1016
Status: Standard

Note: This GEP is exempt from the Probationary Period rules of our GEP overview as it existed before those rules did, and so it has been explicitly grandfathered in.

Goal

Add an idiomatic GRPCRoute for routing gRPC traffic.

Non-Goals

While certain gRPC implementations support multiple transports and multiple interface definition languages (IDLs), this proposal limits itself to HTTP/2 as the transport and Protocol Buffers as the IDL, which makes up the vast majority of gRPC traffic in the wild.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1282: Describing Backend Properties

Issue: #1282
Status: Declined

Explanation for Declined status

This GEP is declined because, after spending a lot of time discussing it, we felt that it was too large, and had too many crosscutting concerns.

It’s superseded for TLS Backend Properties by GEP-1897.

TLDR

End-user feedback of Gateway API has presented a trend: some types of configuration requested by users are more about defining functionality that describes capabilities of the backend more than the route you take to get to the backend.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1294: xRoutes Mesh Binding

Issue: #1294
Status: Standard

Overview

Similar to how xRoutes bind to Gateways and manage North/South traffic flows in Gateway API’s ingress use-case, it would be natural to adopt a similar model for traffic routing concerns in service mesh deployments. The purpose of this GEP is to add a mechanism to the Gateway API spec for the purpose of associating the various xRoute types to a service mesh and offering a model for service owners to manage traffic splitting configurations.

Mon, 01 Jan 0001 00:00:00 +0000

GEP 1323: Response Header Filter

Issue: #1323
Status: Standard

Note: This GEP is exempt from the Probationary Period rules of our GEP overview as it existed before those rules did, and so it has been explicitly grandfathered in.

TLDR

Similar to how we have RequestHeaderModifier in HTTPRouteFilter, which lets users modify request headers before the request is forwarded to a backend (or a group of backends), it’d be helpful to have a ResponseHeaderModifier field which would let users modify response headers before they are returned to the client.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1324: Service Mesh in Gateway API

Issue: #1324
Status: Memorandum

Note: This GEP is exempt from the Probationary Period rules of our GEP overview as it existed before those rules did, and so it has been explicitly grandfathered in.

Overview

Gateway API represents the next generation of traffic routing APIs in Kubernetes. While most of the current work for Gateway API is focused on the ingress use-case, support for service mesh implementations within the spec would be advantageous to the greater community. Therefore, this GEP serves as the genesis for developing common patterns for using Gateway API for east/west traffic within a mesh implementation.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1364: Status and Conditions Update

Issue: #1364
Status: Standard

TLDR

The status, particularly the Conditions, across the whole Gateway API have very much grown organically, and so have many inconsistencies and odd behaviors. This GEP covers doing a review and consolidation to make Condition behavior consistent across the whole API.

Goals

Update Conditions design to be consistent across Gateway API resources
Provide a model and guidelines for Conditions for future new resources
Specify changes to conformance required for Condition updates

Non-Goals

Define the full set of Conditions that will ever be used with Gateway API

Introduction

Gateway API currently has a lot of issues related to status, especially that status is inconsistent (#1111), that names are hard to understand (#1110), and that Reasons aren’t explained properly (#1362).

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1494: HTTP Auth in Gateway API

Issue: #1494
Status: Experimental

(See status definitions.)

TLDR

Provide a method for configuring Gateway API implementations to add HTTP Authentication for north-south traffic. The method may also include Authorization config if practical. At the time of writing, this authentication is only for ingress traffic to the Gateway.

Goals

(Using the Gateway API Personas)

A way for Ana the Application Developer to configure a Gateway API implementation to perform Authentication (at least), with optional Authorization.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1619: Session Persistence via BackendLBPolicy

Issue: #1619
Status: Experimental

(See status definitions.)

Graduation Criteria

Implementable

This GEP was accidentally merged as Provisional before the required approval from 2 maintainers had been received. Before this graduates to implementable, we need to get at least one of @robscott or @youngnick to also approve this GEP.

Before this GEP graduates to Implementable, we must fulfill the following criteria:

Should we leave room in this policy to add additional concepts in the future such as Session Affinity? If so, how would we adjust the naming and overall scope of this policy?
- Answer: Yes. We adjusted the API to use BackendLBPolicy. See API for more details.
Should we leave room for configuring different forms of Session Persistence? If so, what would that look like?
- Answer: Yes. See the BackendLBPolicy API and API Granularity sections for more details.
What name appropriately describe the API responsible for configuring load-balancing options for backend traffic?
- Answer: We decided on BackendLBPolicy since it is aligned with BackendTLSPolicy, describes configuration related to load balancing, and isn’t too long.
Finish designing the Route Rule API and document edge cases in Edge Case Behavior for configuring session persistence on both BackendLBPolicy and route rules.
- Answer: Yes. See Route Rule API and Edge Case Behavior for more details.

Standard

Before this GEP graduates to the Standard channel, we must fulfill the following criteria:

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1651: Gateway Routability

Issue: #1651
Status: Provisional

(See status definitions.)

TLDR

Allow users to configure a Gateway so that it is only routable within a specific scope (ie. public/private/cluster)

Goals

Define a mechanic to set the routability on a Gateway
Provide a default set of routability options
Provide a way for vendors to support custom options

Non-Goals

Per-request/route scope
Not a lightweight service mesh

Introduction

One of the early feature requests for Knative was the ability to deploy an application using Knative’s HTTP routing support, but make it only available within the cluster. I want to be able to specify both the “cluster” (service.namespace.svc) and “external” (service.namespace.example.com). Gateways using the same GatewayClass on the cluster, but ensure that the “cluster” service is only routable within the cluster. This would greatly simplify deployment for users over the instructions we have today.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1686: Mesh conformance testing plan

Issue: #1686
Status: Standard

TLDR

This testing plan specifies a new set of tests to define a “Mesh” conformance profile.

Goals

Define a strategy for segmenting GAMMA tests from the existing conformance test suite
Define a set of test scenarios to capture conformance with the GAMMA spec
Rely on existing tests for non-GAMMA-specific Gateway API conformance

Focus

Currently the GAMMA spec consists of two Gateway API GEPs defining terminology and goals of Gateway API for service meshes and specifically how route resources work in a service mesh context. The goal of the initial conformance testing is to check the essential behavior as defined by GEP-1426, as it differs from the wider Gateway API spec. This GEP focuses on using a Service object as an xRoute parentRef to control how the GAMMA implementation directs traffic to the endpoints specified by the Services in backendRefs and how the traffic is filtered and modified.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1709: Conformance Profiles

Issue: #1709
Status: Standard

Important Notes

Unlike our APIs, CRDs, or gwctl conformance profiles and their reports are not user facing in the traditional sense. As trends in Gateway API utilization grow and change, it may make sense to adjust how profiles work to align better with what implementations are doing. As such conformance profiles (that is, the test suite and the reports) might be subject to backwards incompatible changes at times in ways the rest of the API wouldn’t be (e.g. significant features may need to be added or removed on a profile).

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1713: ListenerSets - Standard Mechanism to Merge Multiple Gateways

Issue: #1713
Status: Standard

(See status definitions.)

Introduction

The Gateway Resource is a point of contention since it is the only place to attach listeners with certificates. We propose a new resource called ListenerSet to allow a shared list of listeners to be attached to a single Gateway.

Goals

Define a mechanism to merge listeners into a single Gateway
Attaching listeners to Gateways in different namespaces
Standardize merging multiple lists of Listeners together (#1863)
Increase the number of Gateway Listeners that are supported (#2869)

Future Potential Goals (Beyond the GEP)

From Gateway Hierarchy Brainstorming:

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1731: HTTPRoute Retries

Issue: #1731
Status: Experimental

(See status definitions.)

TLDR

To allow configuration of a Gateway to retry unsuccessful requests to backends before sending a response to a client request.

Goals

To allow specification of HTTP status codes for which a request should be retried.
To allow specification of the maximum number of times to retry a request.
To allow specification of the minimum backoff interval between retry attempts.
To define any interaction with configured HTTPRoute timeouts.
Retry configuration must be applicable to most known Gateway API implementations.

Future Goals

To allow specification of a retry “budget” to determine whether a request should be retried, and any shared configuration or interaction with max count retry configuration.
Define more precise semantics for retry configuration on “consumer” vs “producer” routes for mesh implementations.

Non-Goals

To allow more granular control of the backoff strategy than many dataplanes allow customizing, such as whether to use an exponential backoff interval between retry attempts, add jitter, or cap the backoff interval to a maximum duration.
To allow specification of a default retry policy for all routes in a given namespace or attached to a particular Gateway.
A standard API for approaches for retry logic other than max count or “budget”, such as interaction with rate limiting headers.
To allow specification of gRPC status codes for which a request should be retried (this should be covered in a separate GEP).
Support for streaming or bidirectional APIs (these could be covered by a future GEP).

Introduction

A Gateway API implementation should be able to retry failed HTTP requests to backends before delivering a response to a client for several reasons:

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1742: HTTPRoute Timeouts

Issue: #1742
Status: Standard

(See status definitions.)

TLDR

Create some sort of design so that Gateway API objects can be used to configure timeouts for different types of connection.

Goals

Create some method to configure some timeouts.
Timeout config must be applicable to most if not all Gateway API implementations.

Non-Goals

A standard API for every possible timeout that implementations may support.

Introduction

In talking about Gateway API objects, particularly HTTPRoute, we’ve mentioned timeout configuration many times in the past as “too hard” to find the common ground necessary to make more generic configuration. This GEP intends firstly to make this process less difficult, then to find common timeouts that we can build into Gateway API.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1748: Gateway API Interaction with Multi-Cluster Services

Issue: #1748
Status: Experimental

Prolonged Experimental Phase

This GEP will be in the “Experimental” channel for a prolonged period of time. This explores the interaction of Gateway API with the Multi-Cluster Services API. Until the MCS API is also GA, it will be impossible for this GEP to graduate beyond “Experimental”.

This GEP is also exempt from the [Probationary Period][expprob] rules as it predated them.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1762: In Cluster Gateway Deployments

Status: Standard

Overview

Gateway API provides a common abstraction over different implementations, whether they are implemented by cloud load balancers, in-cluster deployments, or other mechanisms. However, many in-cluster implementations have solved some of the same problems in different ways.

Related discussions:

Goals

Provide prescriptive guidance for how in-cluster implementations should behave.
Provide requirements for how in-cluster implementations should behave.

Note that some changes will be suggestions, while others will be requirements.

Mon, 01 Jan 0001 00:00:00 +0000

GEP 1767: CORS Filter

Issue: #1767
Status: Standard

TLDR

Cross-origin resource sharing (CORS) is an HTTP-header based mechanism that allows a web page to access restricted resources from a server on an origin (domain, scheme, or port) different than the domain that served the web page. It’s helpful to have a HTTPCorsFilter field in HTTPRouteFilter to handle the cross-origin requests before the response is sent to the client.

Goals

Support CORS filter in a HTTPRoute

Introduction

The CORS protocol is the current specification to support secure cross-origin requests and data transfers between clients and servers.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1867: Per-Gateway Infrastructure

Status: Standard
Issue: #1867

Overview

Gateways represent a piece of infrastructure implemented by cloud load balancers, in-cluster deployments, or other mechanisms. These often need vendor-specific configuration outside the scope of existing APIs (e.g. “size” or “version” of the infrastructure to provision).

Today GatewayClass.spec.parametersRef is available to attach arbitrary configuration to a GatewayClass.

This GEP will explain why that is not sufficient to meet common use cases, and introduce a new field - infrastructure - to address these cases.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1897: BackendTLSPolicy - Explicit Backend TLS Connection Configuration

Issue: #1897
Status: Standard

TLDR

This document specifically addresses the topic of conveying HTTPS from the Gateway dataplane to the backend (backend TLS termination), and intends to satisfy the single use case “As a client implementation of Gateway API, I need to know how to connect to a backend pod that has its own certificate”. TLS configuration can be a nebulous topic, so in order to drive resolution this GEP focuses only on this single piece of functionality.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-1911: Backend Protocol Selection

Issue: #1911
Status: Standard

(See status definitions.)

TLDR

Not all implementations support automatic protocol selection. Even in some cases protocols are disabled without an explicit opt-in (eg. websockets with Contour & NGINX). Thus application developers need the ability to specify the protocol(s) that their application supports.

Goals

Support protocols that can have a Gateway *Route resource as a frontend
Standardize Gateway API implementations on the protocols & constants defined by the Kubernetes Standard Application Protocols (KEP-3726)
Support backends with multiple protocols on the same port (ie. tcp/udp)

Non-Goals

Backend TLS (covered in GEP-1897)
Additional protocol specific configuration
Disabling Protocols

Introduction

Since Kubernetes 1.20 the core/v1.Service and core/v1.EndpointSlice resource has a stable appProtocol field. It’s purpose is to allow end-users to specify an application protocol (L7) for each service port.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-2162: Supported features in GatewayClass Status

Issue: #2162
Status: Standard

TLDR

This GEP proposes to enhance the GatewayClassStatus to include a list of Gateway API features supported by the installed GatewayClass.

Goals

Improve UX by enabling users to easily see what features the implementation (GatewayClass) support.
Standardize features and conformance tests names.
Automatically run conformance tests based on the supported features populated in GatewayClass status.
Provide foundation for tools to block or warn when unsupported features are used.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-2257: Gateway API Duration Format

Issue: #2257
Status: Standard

TL;DR

As we extend the Gateway API to have more functionality, we need a standard way to represent duration values. The first instance is the HTTPRoute Timeouts GEP; doubtless others will arise.

Gateway API Duration Format

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 8174.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-2627: DNS configuration within Gateway API

Issue: #2627
Status: Provisional

TLDR

For gateway infrastructure to be valuable we need to be able to connect clients to these gateways. A common way to achieve this is to use domain names/hostnames and DNS. The guidelines for DNS configuration are a critical piece of service networking, but this is currently not expressible as part of Gateway API. Instead of leaving this unspecified and having implementations likely to do this in different ways, the purpose of this proposal is to provide a standard way to specify DNS for Gateways.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-2643: TLS/SNI based routing / TLSRoute

Issue: #2643
Status: Standard

TLDR

This GEP documents the implementation of a route type that uses the Server Name Indication attribute (aka SNI) of a TLS handshake to chose the route destination.

While this feature is also known sometimes as TLS passthrough, where after the server name is identified, the gateway does a full encrypted passthrough of the communication, this GEP will also cover cases where a TLS communication is terminated on the Gateway before being passed to a backend.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-2648: Direct Policy Attachment

Issue: #2648
Status: Declined

(See status definitions.)

TLDR

This GEP has been merged back into GEP-713 and now it’s now obsolete. Please refer the original specification of Metaresources and Policy Attachment for the current state of the pattern.

Describe and specify a design pattern for a class of metaresource that can affect specific settings across a single target object.

This is a strict subset of all Policy objects that meet a set of criteria designed to be easier to understand for users than Inherited Policy, and so to not require solving the much harder problem of communicating Inherited Policy to users.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-2649: Inherited Policy Attachment

Issue: #2649
Status: Declined

(See status definitions.)

TLDR

This GEP has been merged back into GEP-713 and now it’s now obsolete. Please refer the original specification of Metaresources and Policy Attachment for the current state of the pattern.

Describe and specify a design pattern for a class of metaresource that can affect specific settings across a multiple target objects.

This is a design for a pattern, not an API field or new object.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-2659: Document and improve the GEP process

Issue: #2659
Type: Memorandum
Status: Accepted

(See status definitions.)

TLDR

This GEP clarifies some details about GEPs, and adds relationships and a new status.

Goals

Enumerate how we should use RFC2119 language
Add relationships between GEPs
Add a metadata YAML schema for GEPs, including the new relationships
Add a new status to cover some only recently noticed cases
Update existing documentation outside this GEP to support the new material

Introduction

As part of preparing for work to split up GEP-713, we (the Gateway API and GAMMA maintainers) have noticed a few shortcomings in our GEP process.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-2722: Goals and UX for gwctl

Issue: #2722
Status: Memorandum

TLDR

TLDR: This GEP proposes gwctl, a new command line tool designed to streamline the experience of working with Gateway API resources. It offers a familiar kubectl-like interface for viewing resources while providing more detailed and informative output that is specifically focused on the Gateway API. For advanced filtering and other in-depth features, gwctl can be effectively used alongside kubectl.

Motivations

Limited kubectl customizability for CRDs:
- kubectl’s customization capabilities for CRDs (through additionalPrinterColumns) is constrained, limiting the ability to create optimal views for Gateway API resources.
Complex policy attachment management:
- As described in GEP-713, policies present a valuable mechanism for expanding the capabilities of Gateway API resources. However, discoverability poses a challenge due to the absence of a clear connection between resources and their associated policies. There have been growing questions around suitability of policies as a means to provide extensions.
Challenging multi-resource model navigation:
- Comprehending the relationships between multiple Gateway API resources can be challenging within kubectl.

Goals

Greater control over output formatting and presentation:
- Offer greater control over output formatting and presentation, enhancing visibility and understanding of Gateway API resources.
Improved policy discoverability, increasing adoption and usability:
- Make policies easily discoverable, aiding in the adoption and fostering broader acceptance of policies as an extension mechanism.
Simplified multi-resource model navigation:
- Facilitate navigation of the multi-resource model by making connections between Gateway API resources explicit, aiding in configuration, troubleshooting, and issue identification.
Proactive error detection and reporting:
- Leverage native understanding of resource relationships to proactively detect and report on potential configuration errors, further simplifying issue identification and resolution. This would complement the ability of users to readily pinpoint configuration problems themselves.
Provide incentive for policy implementations that are consistent across cloud providers:
- Encourage the adoption of consistent policy implementations across different Gateway API providers, promoting interoperability and predictability.

Commands Specification

Milestone 1

Supported Commands:

get: Retrieves information about specified resources without including additional information from related resources.
describe: Provides detailed information about specified resources, including augmented information from related resources.

Supported Resources:

gatewayclass
gateways
httproutes
namespaces
backends (not a native k8s resource)
policycrds (not a native k8s resource)
policies (not a native k8s resource)

Filtering Options:

-n Namespace: Filters resources by namespace. Applicable to all resources except cluster-scoped resources.
-l Labels: Filters resources by labels. Applicable to all resources.
-A All Namespaces: Fetches resources across all namespaces (redundant for cluster-scoped resources).
-t Target Resource: Filters policies based on the target resource type they apply to. Applicable only to the policies resource.
- Syntax: -t <key1>=<value1>,<key2>=<value2>,...
- Supported keys:
  - kind: Resource kind (e.g., “httproute”, “gateway”)
  - namespace: Resource namespace
  - name: Resource name
  - group: Resource API group

Output Formats:

describe: Fixed format, not customizable. Shows comprehensive resource information with details from related resources.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-2907: TLS Configuration Placement and Terminology

Issue: #2907
Status: Memorandum

TLDR

This GEP aims to define high level TLS terminology and structure within Gateway API to ensure that all our independent proposals related to TLS result in a coherent set of APIs. This will result in some adjustments to provisional and experimental TLS-related GEPs, specifically BackendTLSPolicy

Goals

Define high-level terminology for how we refer to TLS in Gateway API.
Define top level fields where TLS configuration can live for all below cases:

Client to Gateway (Frontend) TLS configuration.
Gateway to Client TLS configuration (Client Certificate Validation)
Gateway to backend (Gateway Client Certificate)

Document how to use BackendTLSPolicy to support Gateway to Backend TLS configuration.

Non-Goals

Add or change fields directly. (This may inspire changes in other GEPs though).
Commit to including specific parts of TLS configuration in Gateway API. (This is merely to provide space for future configuration, not a commitment that we will add it to the API.)

Out of Scope

There are a variety of related TLS concepts in Gateway API that are not currently in scope for this GEP. In the future, this GEP may be expanded to include:

Mon, 01 Jan 0001 00:00:00 +0000

GEP-3155: Complete Backend mutual TLS Configuration

Issue: #3155
Status: Standard

TLDR

This GEP aims to complete the configuration required for Backend mutual TLS in Gateway API. This includes the following new capabilities:

Configuration for the client certificate Gateways should use when connecting to Backends
Ability to specify SANs on BackendTLSPolicy
Add TLS options to BackendTLSPolicy to mirror TLS config on Gateways

Goals

Add sufficient configuration that basic mutual TLS is possible between Gateways and Backends
Enable the optional use of SPIFFE for Backend mutual TLS

Non-Goals

Define how automatic mTLS should be implemented with Gateway API

Introduction

This is a wide ranging GEP intending to cover three additions to the API that all have a shared goal - enabling backend mutual TLS with Gateway API. Although this specific GEP focuses on manual configuration across the board, the hope is that it will also enable higher level automation to simplify this process for users.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-3171: Percentage-based Request Mirroring

Issue: #3171
Status: Standard

(See status definitions.)

TLDR

Enhance the existing Request Mirroring feature by allowing users to specify a percentage of requests they’d like mirrored.

Goals

Enable percentage-based request mirroring with Gateway and Gateway for mesh APIs.

Scope

The scope of this GEP is to add support for this feature in both HTTPRoute and GRPCRoute

Introduction

Request Mirroring is a feature that allows a user to mirror requests going to some backend A along to some other specified backend B. Right now Request Mirroring is an all or nothing feature – either 100% of request are mirrored, or 0% are. Percentage-based Request Mirroring will allow users to specify a percentage of requests they’d like mirrored as opposed to every single request.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-3388: Retry Budgets

Issue: #3388
Status: Experimental

(See status definitions.)

TLDR

To allow configuration of a “retry budget” across all endpoints of a destination service, preventing additional client-side retries when the percentage of the active request load consisting of retries reaches a certain threshold.

Goals

To allow specification of a retry “budget” to determine whether a request should be retried, and any shared configuration or interaction with configuration of a static retry limit within HTTPRoute.
To allow specification of a percentage of active requests, or recently active requests, that should be able to be retried concurrently.
To allow specification of a minimum number of retries that should be allowed per second or concurrently, such that the budget for retries never goes below this minimum value.
To define a standard for retry budgets that reconciles the known differences in current retry budget functionality between Gateway API data plane implementations.

Non-Goals

To allow specifying a default retry budget policy across a namespace or attached to a specific gateway.
To allow configuration of a back-off strategy or timeout window within the retry budget spec.
To allow specifying inclusion of specific HTTP status codes and responses within the retry budget spec.
To allow specification of more than one retry budget for a given service, or for specific subsets of its traffic.

Introduction

Multiple data plane proxies offer optional configuration for budgeted retries, in order to create a dynamic limit on the amount of a service’s active request load that is comprised of retries from across its clients. In the case of Linkerd, retry budgets are the default retry policy configuration for HTTP retries within the ServiceProfile CRD, with static max retries being a fairly recent addition.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-3567: Gateway TLS Updates for HTTP/2 Connection Coalescing

Issue: #3567
Status: Experimental

TLDR

As described in the previous doc, the current state of TLS configuration on Gateways can lead to confusing behavior when combined with HTTP/2 connection coalescing. This GEP proposes a series of changes to the API to address these problems.

Goals

Take steps that will make it less likely for users to encounter these problems
Warn when users have configuration that is prone to these issues
Provide central source of documentation explaining both the problem and potential solutions

Non-Goals

Breaking or significantly disruptive changes to the existing API surface

Introduction

Gateway API creates situations where clients might be able to send requests through a Listener that, according to the Gateway’s configuration, is not supposed to receive these requests. This can cause requests to be apparently mis-routed.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-3779: Identity Based Authz for East-West Traffic

Issue: #3779
Status: Implementable

(See status definitions.)

TLDR

Provide a method for configuring Gateway API Mesh implementations to enforce east-west identity-based Authorization controls. At the time of writing this we leave Authentication for specific implementation and outside of this proposal scope.

Goals

(Using the Gateway API Personas)

A way for Ana the Application Developer to configure a Gateway API for Mesh implementation to enforce authorization policy that allows identity or multiple identities to talk with some set (could be namespace or more granular) of the workloads she controls.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-3792: Out-of-Cluster Gateways

Issue: #3792
Status: Provisional

(See status definitions.)

User Story

Chihiro and Ian want a way for out-of-cluster Gateways to be able to usefully participate in a GAMMA-compliant in-cluster service mesh.

Historically, API gateways and ingress controllers have often been implemented using a Service of type LoadBalancer fronting a Kubernetes pod running a proxy. This is simple to reason about, easy to manage for sidecar meshes, and will presumably be an important implementation mechanism for the foreseeable future. Some cloud providers, though, are moving the proxy outside of the cluster, for various reasons which are out of the scope of this GEP. Chihiro and Ian want to be able to use these out-of-cluster proxies effectively and safely, though they recognize that this may require additional configuration.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-3793: Default Gateways

Issue: #3793
Status: Implementable

(See status definitions.)

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 (RFC8174) when, and only when, they appear in all capitals, as shown here.

User Story

Ana wants a concept of a default Gateway.

Gateway API currently requires every north/south Route object to explicitly specify its parent Gateway. This is helpful in that it removes ambiguity, but it’s less helpful in that Ana is stuck constantly explicitly configuring a thing that she probably doesn’t care much about: in a great many cases, Ana just wants to create a Route that “works from the outside world” and she really doesn’t care what the Gateway is called.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-3798: Client IP-Based Session Persistence

Issue: #3798
Status: Deferred

(See status definitions.)

Notes and Disclaimers

DEFERRED: This originally targeted release as Experimental in v1.4.0. Notably (in PR#3844) there was concern that it may be difficult to get multiple implementations to support this. During the release cycle, this GEP was not able to meet the timeline requirements to progress, so it is now considered deferred. If anyone is interested in picking this back up, it will need to be re-submitted for consideration in a future release with a written plan about how it will achieve implementation from multiple implementations. If this remains in deferred state for a prolonged period, it may eventually be moved to Withdrawn, or moved into the alternatives considered for GEP-1619.

TLDR

What

This GEP proposes the addition of Client IP-based session persistence to the Gateway API. This feature will allow Gateway API implementations to ensure that requests originating from a specific client IP address (or a subnet defined by an IP mask) are consistently routed to the same backend endpoint for a configurable duration. This aims to provide a standardized and centralized mechanism for client IP persistence across various Gateway API implementations.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-3949: Mesh Resource

Issue: #3949
Status: Implementable

(See status definitions.)

User Story

Chihiro and Ian would like a Mesh resource, parallel to the Gateway resource, that allows them to supply mesh-wide configuration and shows what features a given mesh implementation supports.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-4152: Extending TLS Validation in BackendTLSPolicy

Issue: #4152
Status: Provisional

TLDR

The ability for the BackendTLSPolicy to skip TLS verification or to validate certificates based on their fingerprint or public key hash.

Motivation

The current BackendTLSPolicy follows a secure-by-default approach that requires users to provide a trusted CA certificate bundle or rely on the system’s default certificate store (which typically includes root CAs) to validate backend server certificates. However, real-world deployments include cases where strict certificate validation may not be possible or practical, e.g., Development and testing environments that use self-signed certificates generated dynamically at runtime.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-696: GEP template

Issue: #696
Status: Provisional|Prototyping|Implementable|Experimental|Standard|Completed|Memorandum|Deferred|Declined|Withdrawn

(See status definitions.)

TLDR

(1-2 sentence summary of the proposal)

Goals

(Primary goals of this proposal.)

Longer Term Goals (optional)

(goals that are not covered initially on this proposal but may be considered long term)

Non-Goals

(What is out of scope for this proposal.)

Introduction/Overview

(Can link to external doc – but we should bias towards copying the content into the GEP as online documents are easier to lose – e.g. owner messes up the permissions, accidental deletion)

Mon, 01 Jan 0001 00:00:00 +0000

GEP-709: Cross Namespace References from Routes

Issue: #709
Status: Standard

This resource was originally named “ReferencePolicy”. It was renamed to “ReferenceGrant” to avoid any confusion with policy attachment.

TLDR

This GEP attempts to enable cross namespace forwarding from Routes and provide a way to simplify adding Route inclusion (Routes including other Routes) in the future. These are closely related concepts that can be solved with a new ReferenceGrant resource that enables app admins to describe where they trust references from.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-713: Metaresources and Policy Attachment

Issue: #713
Status: Memorandum

(See status definitions here)

TL;DR

This GEP aims to standardize terminology and processes around “metaresources”, i.e., using one Kubernetes object to modify the functions of one or more other objects.

It lays out guidelines for Gateway API implementations and other stakeholders for the design and/or handling of custom resources in compliance with a pattern known as Policy Attachment.

This GEP specifies a pattern, not an API field or new object. It defines some terms, including Metaresource, Policies and Policy Attachment, and their related concepts.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-718: Rework forwardTo segment in routes

Issue: #718
Status: Standard

Motivation

Complications due to the `serviceName` shortcut

Within RouteForwardTo (and HTTPRouteForwardTo by extension) there exists two mechanisms to specify the upstream network endpoint where the traffic should be forwarded to:

ServiceName: the name of the Kubernetes Service
BackendRef: a LocalObjectReference to a resource, this is an extension point in the API

While working on #685, it came to light that:

BackendRef itself could be used to point to a Kubernetes Service
With GEP-709, there will be a need to introduce a new namespace field which will enable use-cases to forward traffic to a services and backends located in different namespaces

While (1) can be fixed with more validation and documentation, it only solves for the specific case. (2) requires adding two fields: serviceNamespace and BackendRef.Namespace - something we would like to avoid since the serviceName field was introduced only as a shortcut and adding more service-specific fields defeats the original purpose.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-724: Refresh Route-Gateway Binding

Issue: #724
Status: Standard

TLDR

This GEP proposes changes to Route-Gateway binding that will result in Routes attaching to Gateways with direct references. When supporting Routes in multiple namespaces, Gateways will need to specify the namespaces they trust Routes in. These changes will slightly simplify the Route-Gateway relationship and make way for the future addition of Route inclusion (Routes including other Routes).

Goals

Refactor cross-namespace Route-Gateway binding to:

Mon, 01 Jan 0001 00:00:00 +0000

GEP-726: Add Path Redirects and Rewrites

Issue: #726
Status: Standard

TLDR

This GEP proposes adding support for path redirects and rewrites in addition to host rewrites. This would augment the existing host redirection capabilities.

Goals

Implement path redirects.
Implement the most portable and simple forms of path rewrites.
Describe how more advanced rewrite and redirect and redirect capabilities could be added in the future.

API

Although many implementations support very advanced rewrite and redirect capabilities, the following are the most portable concepts that are not already supported by the Gateway API:

Mon, 01 Jan 0001 00:00:00 +0000

GEP-735: TCP and UDP addresses matching

Issue: #735
Status: Declined

Notes about declined status

At one point before the release of v0.5.0 we did have an implementation of this GEP in main, but we decided to pull back on it for multiple reasons:

operated too much like WAF/firewall functionality, which is not in scope
no implementations championing the use case

It should also be noted that the maintainers have at least considered the idea of an IPRoute API which would help differentiate this from firewall functionality, however there haven’t been any strong champions for such a use case for this either.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-746: Replace Cert Refs on HTTPRoute with Cross Namespace Refs from Gateway

Issue: #746
Status: Standard

TLDR

This GEP proposes that we should remove TLS Certificate references from HTTPRoute and replace them with Cross Namespace Certificate references from Gateways. Although that is not a complete replacement on its own, this GEP shows how a controller could provide the rest of the functionality with this approach.

Goals

Remove a confusing and underspecified part of the API - cert refs on HTTPRoute.
Add the ability to reference certificates in other namespaces from Gateways to replace much of the functionality that was enabled by cert refs on HTTPRoute.
Describe how a controller could automate self service cert attachment to Gateway listeners.

Non-Goals

Actually provide a core implementation of a controller that can enable self service cert attachment. This may be worth considering at a later point, but is out of scope for this GEP.

Introduction

TLS Certificate references on HTTPRoute have always been a confusing part of the Gateway API. In the v1alpha2 release, we should consider removing this feature while we still can. This GEP proposes an alternative that is simpler to work with and understand, while also leaving sufficient room to enable all the same capabilities that certificate references on HTTPRoute enabled.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-820: Drop extension points from Route matches

Issue: #820
Status: Standard

TLDR

Drop extension points within Route match block. These extension points are not well understood.

Goals

Drop the extension points within Route match block.

Non-Goals

Figure out a replacement solution for the use-case that these extension points addressed

Introduction

As the API moves towards v1alpha2, the maintainers intend to make the API standard and forward compatible for the foreseeable future. To that end, maintainers intend to minimize (eliminate if possible) breaking changes post v1alpha2. This GEP is part of that initiative.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-851: Allow Multiple Certificate Refs per Gateway Listener

Issue: #851
Status: Standard

TLDR

Replace CertificateRef field with a CertificateRefs field in Gateway Listeners.

Goals

Provide a path for implementations to support:

RSA and ECDSA certs on the same Listener.
Referencing certificates for different hostnames from the same Listener (maybe as part of a self-service TLS approach).
Including new and old certificates as part of renewal process.
Certificate pinning: enable implementations that require certain certificates for legacy clients while exposing a “normal” certificate to non-legacy clients.

Non-Goals

Define how implementations should support these features. Many implementations have limited control as far as how certs are handled. Some implementations just pass certs directly to the dataplane and rely on that implementation specific behavior to determine which certs are used for a given request. That makes it difficult to define any truly portable handling of multiple certificates.

Introduction

As described above, there are a number of potential use cases for attaching multiple certificates to a Gateway Listener. The most straightforward reason for that involves attaching RSA and ECDSA certs. Although this is not a very common use case, it is a clearly understood and broadly supported example of why this change would be helpful. This change will enable implementations to support these more advanced use cases while still providing a portable core.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-91: Client Certificate Validation for TLS terminating at the Gateway

Issue: #91
Status: Standard

(See definitions in GEP States.)

TLDR

This GEP proposes a way to validate the TLS certificate presented by the frontend client to the server (Gateway in this case) during a TLS Handshake Protocol.

Connection coalescing security issue

Gateway API standard defines a Listener as “the concept of a logical endpoint where a Gateway accepts network connections.” This statement is incorrect because once the connection is established (this applies to both HTTP and TLS traffic) it can be reused across multiple listeners sharing the same port. This might lead to bypassing client certificate validation configuration for a given Listener. Those concerns were raised in GEP-3567. To provide the best experience for gateway users and secure their applications, client certificate configuration needs to be introduced with finer granularity per-port (binding to TCP connection).

Mon, 01 Jan 0001 00:00:00 +0000

GEP-917: Gateway API Conformance Testing

Issue: #917
Status: Memorandum

TLDR

This GEP outlines the principles and overarching structure that Gateway API conformance tests will be built with.

Goals

Record why we are doing conformance and what we hope to achieve with it
Record the success criteria for the conformance process and associated artifacts
Provide a set of guidelines for conformance test structure

Non-Goals

Designing the conformance testing framework or implementation
Designing the process for implementations to prove they are conformant

Introduction

What is Conformance

Conformance is the creation of a process that allows everyone, implementors and users alike, to check that an implementation conforms to the defined spec.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-922: Gateway API Versioning

Issue: #922
Status: Memorandum

Although this GEP serves as a reference for how we developed the Gateway API versioning model, it is not meant to be the current source of truth. Instead, please refer to our official Versioning Policy for the most up-to-date guidelines.

TLDR

Each Gateway API release will be represented by a bundle version that represents that specific combination of CRDs, API versions, and validating webhook. To enable experimental fields, future releases of the API will include standard and experimental CRD tracks. Users will be able to access experimental features by installing the experimental CRDs. A cluster can contain either an experimental or standard CRD for any resource at a given time.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-957: Destination Port Matching

Issue: #957
Status: Standard

TLDR

Add a new port field to ParentRef to support port matching in Routes.

Goals

Support port matching in routes based on the destination port number of the request.

Non-Goals

Support port matching based on port name.

Introduction

Port matching is a common service mesh use case where traffic policies/rules need to be applied to traffic to certain destination ports. For ingress, while the API today already supports attaching a route to a specific listener, it may be useful to support attaching routes to listener(s) on a specified port. This allows route authors to apply networking behaviors on a fixed port.

Mon, 01 Jan 0001 00:00:00 +0000

GEP-995: Named route rules

Issue: #995
Status: Standard

TLDR

Add a new optional name field to the route rule types (GRPCRouteRule, HTTPRouteRule, TCPRouteRule, TLSRouteRule and UDPRouteRule) to support referencing individual rules by name.

Goals

Support referencing individual route rules by name from other resources, such as from metaresources (GEP-2648.)
Support referencing individual route rules by name from condition messages propagated in the status stanza of route resources as suggested in https://github.com/kubernetes-sigs/gateway-api/issues/1696#issuecomment-1666258188.
Support referencing individual route rules by name at other observability and networking tools that are part of the ecosystem based on Gateway API.
Provide a rather intuitive API for users of Kubernetes who are familiar with the same pattern employed already by other kinds of resources where lists of complex elements can be declared – e.g. service ports, pod containers and pod volumes.
Provide a guide to the implementations about the expected behavior in cases where the name of the route rule is missing (empty value or nil.)

Non-Goals

Mandate the name field to be a require field.
Limit the usage of the route rule name value for the implementations, such as exclusively for the targetRef section of policies (metaresources.)
Define a patch strategy for the route objects based on rule name.

Introduction

Some kinds of Gateway API types are complex types that support specifying lists of yet other complex object details within them. Examples include the GatewaySpec type, the HTTPRouteSpec type, as well as other kinds of route specification types. Specifically, Gateway objects can declare multiple complex listener details (spec.listeners); similarly, HTTPRoute objects may contain multiple complex routing rule details (spec.rules).