Gateway API

Make network services available by using an extensible, role-oriented, protocol-aware configurationmechanism.Gateway API is anadd-oncontaining APIkinds that provide dynamic infrastructureprovisioning and advanced traffic routing.

Design principles

The following principles shaped the design and architecture of Gateway API:

• Role-oriented: Gateway API kinds are modeled after organizational roles that areresponsible for managing Kubernetes service networking:
  • Infrastructure Provider: Manages infrastructure that allows multiple isolated clustersto serve multiple tenants, e.g. a cloud provider.
  • Cluster Operator: Manages clusters and is typically concerned with policies, networkaccess, application permissions, etc.
  • Application Developer: Manages an application running in a cluster and is typicallyconcerned with application-level configuration andServicecomposition.
• Portable: Gateway API specifications are defined ascustom resourcesand are supported by manyimplementations.
• Expressive: Gateway API kinds support functionality for common traffic routing use casessuch as header-based matching, traffic weighting, and others that were only possible inIngress by using custom annotations.
• Extensible: Gateway allows for custom resources to be linked at various layers of the API.This makes granular customization possible at the appropriate places within the API structure.

Resource model

Gateway API has four stable API kinds:

• GatewayClass: Defines a set of gateways with common configuration and managed by a controllerthat implements the class.

• Gateway: Defines an instance of traffic handling infrastructure, such as cloud load balancer.

• HTTPRoute: Defines HTTP-specific rules for mapping traffic from a Gateway listener to arepresentation of backend network endpoints. These endpoints are often represented as aService.

• GRPCRoute: Defines gRPC-specific rules for mapping traffic from a Gateway listener to arepresentation of backend network endpoints. These endpoints are often represented as aService.

Gateway API is organized into different API kinds that have interdependent relationships to supportthe role-oriented nature of organizations. A Gateway object is associated with exactly one GatewayClass;the GatewayClass describes the gateway controller responsible for managing Gateways of this class.One or more route kinds such as HTTPRoute, are then associated to Gateways. A Gateway can filter the routesthat may be attached to itslisteners, forming a bidirectional trust model with routes.

The following figure illustrates the relationships of the three stable Gateway API kinds:

GatewayClass

Gateways can be implemented by different controllers, often with different configurations. A Gatewaymust reference a GatewayClass that contains the name of the controller that implements theclass.

A minimal GatewayClass example:

apiVersion:gateway.networking.k8s.io/v1kind:GatewayClassmetadata:name:example-classspec:controllerName:example.com/gateway-controller

In this example, a controller that has implemented Gateway API is configured to manage GatewayClasseswith the controller nameexample.com/gateway-controller. Gateways of this class will be managed bythe implementation's controller.

See theGatewayClassreference for a full definition of this API kind.

Gateway

A Gateway describes an instance of traffic handling infrastructure. It defines a network endpointthat can be used for processing traffic, i.e. filtering, balancing, splitting, etc. for backendssuch as a Service. For example, a Gateway may represent a cloud load balancer or an in-cluster proxyserver that is configured to accept HTTP traffic.

A typical Gateway resource example:

apiVersion:gateway.networking.k8s.io/v1kind:Gatewaymetadata:name:example-gatewaynamespace:example-namespacespec:gatewayClassName:example-classlisteners:-name:httpprotocol:HTTPport:80hostname:"www.example.com"allowedRoutes:namespaces:from:Same

In this example, an instance of traffic handling infrastructure is programmed to listen for HTTPtraffic on port 80. Since theaddresses field is unspecified, an address or hostname is assignedto the Gateway by the implementation's controller. This address is used as a network endpoint forprocessing traffic of backend network endpoints defined in routes.

See theGatewayreference for a full definition of this API kind.

HTTPRoute

The HTTPRoute kind specifies routing behavior of HTTP requests from a Gateway listener to backend networkendpoints. For a Service backend, an implementation may represent the backend network endpoint as a ServiceIP or the backing EndpointSlices of the Service. An HTTPRoute represents configuration that is applied to theunderlying Gateway implementation. For example, defining a new HTTPRoute may result in configuring additionaltraffic routes in a cloud load balancer or in-cluster proxy server.

A typical HTTPRoute example:

apiVersion:gateway.networking.k8s.io/v1kind:HTTPRoutemetadata:name:example-httproutespec:parentRefs:-name:example-gatewayhostnames:-"www.example.com"rules:-matches:-path:type:PathPrefixvalue:/loginbackendRefs:-name:example-svcport:8080

In this example, HTTP traffic from Gatewayexample-gateway with the Host: header set towww.example.comand the request path specified as/login will be routed to Serviceexample-svc on port8080.

See theHTTPRoutereference for a full definition of this API kind.

GRPCRoute

The GRPCRoute kind specifies routing behavior of gRPC requests from a Gateway listener to backend networkendpoints. For a Service backend, an implementation may represent the backend network endpoint as a ServiceIP or the backing EndpointSlices of the Service. A GRPCRoute represents configuration that is applied to theunderlying Gateway implementation. For example, defining a new GRPCRoute may result in configuring additionaltraffic routes in a cloud load balancer or in-cluster proxy server.

Gateways supporting GRPCRoute are required to support HTTP/2 without an initial upgrade from HTTP/1,so gRPC traffic is guaranteed to flow properly.

A typical GRPCRoute example:

apiVersion:gateway.networking.k8s.io/v1kind:GRPCRoutemetadata:name:example-grpcroutespec:parentRefs:-name:example-gatewayhostnames:-"svc.example.com"rules:-backendRefs:-name:example-svcport:50051

In this example, gRPC traffic from Gatewayexample-gateway with the host set tosvc.example.comwill be directed to the serviceexample-svc on port50051 from the same namespace.

GRPCRoute allows matching specific gRPC services, as per the following example:

apiVersion:gateway.networking.k8s.io/v1kind:GRPCRoutemetadata:name:example-grpcroutespec:parentRefs:-name:example-gatewayhostnames:-"svc.example.com"rules:-matches:-method:service:com.examplemethod:LoginbackendRefs:-name:foo-svcport:50051

In this case, the GRPCRoute will match any traffic for svc.example.com and apply its routing rulesto forward the traffic to the correct backend. Since there is only one match specified,only requestsfor the com.example.User.Login method to svc.example.com will be forwarded.RPCs of any other method` will not be matched by this Route.

See theGRPCRoutereference for a full definition of this API kind.

Request flow

Here is a simple example of HTTP traffic being routed to a Service by using a Gateway and an HTTPRoute:

In this example, the request flow for a Gateway implemented as a reverse proxy is:

1. The client starts to prepare an HTTP request for the URLhttp://www.example.com
2. The client's DNS resolver queries for the destination name and learns a mapping toone or more IP addresses associated with the Gateway.
3. The client sends a request to the Gateway IP address; the reverse proxy receives the HTTPrequest and uses the Host: header to match a configuration that was derived from the Gatewayand attached HTTPRoute.
4. Optionally, the reverse proxy can perform request header and/or path matching basedon match rules of the HTTPRoute.
5. Optionally, the reverse proxy can modify the request; for example, to add or remove headers,based on filter rules of the HTTPRoute.
6. Lastly, the reverse proxy forwards the request to one or more backends.

Conformance

Gateway API covers a broad set of features and is widely implemented. This combination requiresclear conformance definitions and tests to ensure that the API provides a consistent experiencewherever it is used.

See theconformance documentation tounderstand details such as release channels, support levels, and running conformance tests.

Migrating from Ingress

Gateway API is the successor to theIngress API.However, it does not include the Ingress kind. As a result, a one-time conversion from your existingIngress resources to Gateway API resources is necessary.

Refer to theingress migrationguide for details on migrating Ingress resources to Gateway API resources.

What's next

Instead of Gateway API resources being natively implemented by Kubernetes, the specificationsare defined asCustom Resourcessupported by a wide range ofimplementations.Install the Gateway API CRDs orfollow the installation instructions of your selected implementation. After installing animplementation, use theGetting Started guide to helpyou quickly start working with Gateway API.

Refer to theAPI specification for additionaldetails of all Gateway API kinds.