Skip to content

Commit a74574f

Browse files
danehansdanehans
committed
Adds Gateway API docs
- Adds Gateway API term to the glossary. - Adds Gateway API as reference in the addons page. - Adds a page to the Service networking docs that explains Gateway API. - Updates existing docs to reference the newly added Gateway API docs. Signed-off-by: Daneyon Hansen <[email protected]>
1 parent c265c7d commit a74574f

File tree

8 files changed

+238
-1
lines changed

8 files changed

+238
-1
lines changed

‎content/en/docs/concepts/cluster-administration/addons.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,9 @@ installation instructions. The list does not try to be exhaustive.
5454
and bare metal workloads.
5555
* [Flannel](https://github.com/flannel-io/flannel#deploying-flannel-manually) is
5656
an overlay network provider that can be used with Kubernetes.
57+
* [Gateway API](/docs/concepts/services-networking/gateway/) is an open source project managed by
58+
the [SIG Network](https://github.com/kubernetes/community/tree/master/sig-network) community and
59+
provides an expressive, extensible, and role-oriented API for modeling service networking.
5760
* [Knitter](https://github.com/ZTE/Knitter/) is a plugin to support multiple network
5861
interfaces in a Kubernetes pod.
5962
* [Multus](https://github.com/k8snetworkplumbingwg/multus-cni) is a Multi plugin for

‎content/en/docs/concepts/services-networking/_index.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ Kubernetes networking addresses four concerns:
5454
to be reachable from outside your cluster.
5555
- [Ingress](/docs/concepts/services-networking/ingress/) provides extra functionality
5656
specifically for exposing HTTP applications, websites and APIs.
57+
- [Gateway API](/docs/concepts/services-networking/gateway/) is an {{<glossary_tooltip text="add-on" term_id="addons">}}
58+
that provides an expressive, extensible, and role-oriented family of API kinds for modeling service networking.
5759
- You can also use Services to
5860
[publish services only for consumption inside your cluster](/docs/concepts/services-networking/service-traffic-policy/).
5961

‎content/en/docs/concepts/services-networking/gateway.md

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
title: Gateway API
3+
content_type: concept
4+
description: >-
5+
Gateway API is a family of API kinds that provide dynamic infrastructure provisioning
6+
and advanced traffic routing.
7+
weight: 55
8+
---
9+
10+
<!-- overview -->
11+
12+
Make network services available by using an extensible, role-oriented, protocol-aware configuration
13+
mechanism. [Gateway API](https://gateway-api.sigs.k8s.io/) is an {{<glossary_tooltip text="add-on" term_id="addons">}}
14+
containing API [kinds](https://gateway-api.sigs.k8s.io/references/spec/) that provide dynamic infrastructure
15+
provisioning and advanced traffic routing.
16+
17+
<!-- body -->
18+
19+
## Design principles
20+
21+
The following principles shaped the design and architecture of Gateway API:
22+
23+
* __Role-oriented:__ Gateway API kinds are modeled after organizational roles that are
24+
responsible for managing Kubernetes service networking:
25+
* __Infrastructure Provider:__ Manages infrastructure that allows multiple isolated clusters
26+
to serve multiple tenants, e.g. a cloud provider.
27+
* __Cluster Operator:__ Manages clusters and is typically concerned with policies, network
28+
access, application permissions, etc.
29+
* __Application Developer:__ Manages an application running in a cluster and is typically
30+
concerned with application-level configuration and [Service](/docs/concepts/services-networking/service/)
31+
composition.
32+
* __Portable:__ Gateway API specifications are defined as [custom resources](docs/concepts/extend-kubernetes/api-extension/custom-resources)
33+
and are supported by many [implementations](https://gateway-api.sigs.k8s.io/implementations/).
34+
* __Expressive:__ Gateway API kinds support functionality for common traffic routing use cases
35+
such as header-based matching, traffic weighting, and others that were only possible in
36+
[Ingress](/docs/concepts/services-networking/ingress/) by using custom annotations.
37+
* __Extensible:__ Gateway allows for custom resources to be linked at various layers of the API.
38+
This makes granular customization possible at the appropriate places within the API structure.
39+
40+
## Resource model
41+
42+
Gateway API has three stable API kinds:
43+
44+
* __GatewayClass:__ Defines a set of gateways with common configuration and managed by a controller
45+
that implements the class.
46+
47+
* __Gateway:__ Defines an instance of traffic handling infrastructure, such as cloud load balancer.
48+
49+
* __HTTPRoute:__ Defines HTTP-specific rules for mapping traffic from a Gateway listener to a
50+
representation of backend network endpoints. These endpoints are often represented as a
51+
{{<glossary_tooltip text="Service" term_id="service">}}.
52+
53+
Gateway API is organized into different API kinds that have interdependent relationships to support
54+
the role-oriented nature of organizations. A Gateway object is associated with exactly one GatewayClass;
55+
the GatewayClass describes the gateway controller responsible for managing Gateways of this class.
56+
One or more route kinds such as HTTPRoute, are then associated to Gateways. A Gateway can filter the routes
57+
that may be attached to its `listeners`, forming a bidirectional trust model with routes.
58+
59+
The following figure illustrates the relationships of the three stable Gateway API kinds:
60+
61+
{{< figure src="/docs/images/gateway-kind-relationships.svg" alt="A figure illustrating the relationships of the three stable Gateway API kinds" class="diagram-medium" >}}
62+
63+
### GatewayClass {#api-kind-gateway-class}
64+
65+
Gateways can be implemented by different controllers, often with different configurations. A Gateway
66+
must reference a GatewayClass that contains the name of the controller that implements the
67+
class.
68+
69+
A minimal GatewayClass example:
70+
71+
```yaml
72+
apiVersion: gateway.networking.k8s.io/v1
73+
kind: GatewayClass
74+
metadata:
75+
name: example-class
76+
spec:
77+
controllerName: example.com/gateway-controller
78+
```
79+
80+
In this example, a controller that has implemented Gateway API is configured to manage GatewayClasses
81+
with the controller name `example.com/gateway-controller`. Gateways of this class will be managed by
82+
the implementation's controller.
83+
84+
See the [GatewayClass](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.GatewayClass)
85+
reference for a full definition of this API kind.
86+
87+
### Gateway {#api-kind-gateway}
88+
89+
A Gateway describes an instance of traffic handling infrastructure. It defines a network endpoint
90+
that can be used for processing traffic, i.e. filtering, balancing, splitting, etc. for backends
91+
such as a Service. For example, a Gateway may represent a cloud load balancer or an in-cluster proxy
92+
server that is configured to accept HTTP traffic.
93+
94+
A minimal Gateway resource example:
95+
96+
```yaml
97+
apiVersion: gateway.networking.k8s.io/v1
98+
kind: Gateway
99+
metadata:
100+
name: example-gateway
101+
spec:
102+
gatewayClassName: example-class
103+
listeners:
104+
- name: http
105+
protocol: HTTP
106+
port: 80
107+
```
108+
109+
In this example, an instance of traffic handling infrastructure is programmed to listen for HTTP
110+
traffic on port 80. Since the `addresses` field is unspecified, an address or hostname is assigned
111+
to the Gateway by the implementation's controller. This address is used as a network endpoint for
112+
processing traffic of backend network endpoints defined in routes.
113+
114+
See the [Gateway](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.Gateway)
115+
reference for a full definition of this API kind.
116+
117+
### HTTPRoute {#api-kind-httproute}
118+
119+
The HTTPRoute kind specifies routing behavior of HTTP requests from a Gateway listener to backend network
120+
endpoints. For a Service backend, an implementation may represent the backend network endpoint as a Service
121+
IP or the backing Endpoints of the Service. An HTTPRoute represents configuration that is applied to the
122+
underlying Gateway implementation. For example, defining a new HTTPRoute may result in configuring additional
123+
traffic routes in a cloud load balancer or in-cluster proxy server.
124+
125+
A minimal HTTPRoute example:
126+
127+
```yaml
128+
apiVersion: gateway.networking.k8s.io/v1
129+
kind: HTTPRoute
130+
metadata:
131+
name: example-httproute
132+
spec:
133+
parentRefs:
134+
- name: example-gateway
135+
hostnames:
136+
- "www.example.com"
137+
rules:
138+
- matches:
139+
- path:
140+
type: PathPrefix
141+
value: /login
142+
backendRefs:
143+
- name: example-svc
144+
port: 8080
145+
```
146+
147+
In this example, HTTP traffic from Gateway `example-gateway` with the Host: header set to `www.example.com`
148+
and the request path specified as `/login` will be routed to Service `example-svc` on port `8080`.
149+
150+
See the [HTTPRoute](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.HTTPRoute)
151+
reference for a full definition of this API kind.
152+
153+
## Request flow
154+
155+
Here is a simple example of HTTP traffic being routed to a Service by using a Gateway and an HTTPRoute:
156+
157+
{{< figure src="/docs/images/gateway-request-flow.svg" alt="A diagram that provides an example of HTTP traffic being routed to a Service by using a Gateway and an HTTPRoute" class="diagram-medium" >}}
158+
159+
In this example, the request flow for a Gateway implemented as a reverse proxy is:
160+
161+
1. The client starts to prepare an HTTP request for the URL `http://www.example.com`
162+
2. The client's DNS resolver queries for the destination name and learns a mapping to
163+
one or more IP addresses associated with the Gateway.
164+
3. The client sends a request to the Gateway IP address; the reverse proxy receives the HTTP
165+
request and uses the Host: header to match a configuration that was derived from the Gateway
166+
and attached HTTPRoute.
167+
4. Optionally, the reverse proxy can perform request header and/or path matching based
168+
on match rules of the HTTPRoute.
169+
5. Optionally, the reverse proxy can modify the request; for example, to add or emove headers,
170+
based on filter rules of the HTTPRoute.
171+
6. Lastly, the reverse proxy forwards the request to one or more backends.
172+
173+
## Conformance
174+
175+
Gateway API covers a broad set of features and is widely implemented. This combination requires
176+
clear conformance definitions and tests to ensure that the API provides a consistent experience
177+
wherever it is used.
178+
179+
See the [conformance](https://gateway-api.sigs.k8s.io/concepts/conformance/) documentation to
180+
understand details such as release channels, support levels, and running conformance tests.
181+
182+
## Migrating from Ingress
183+
184+
Gateway API is the successor to the [Ingress](/docs/concepts/services-networking/ingress/) API.
185+
However, it does not include the Ingress kind. As a result, a one-time conversion from your existing
186+
Ingress resources to Gateway API resources is necessary.
187+
188+
Refer to the [ingress migration](https://gateway-api.sigs.k8s.io/guides/migrating-from-ingress/#migrating-from-ingress)
189+
guide for details on migrating Ingress resources to Gateway API resources.
190+
191+
## {{% heading "whatsnext" %}}
192+
193+
Instead of Gateway API resources being natively implemented by Kubernetes, the specifications
194+
are defined as [Custom Resources](docs/concepts/extend-kubernetes/api-extension/custom-resources)
195+
supported by a wide range of [implementations](https://gateway-api.sigs.k8s.io/implementations/).
196+
[Install](https://gateway-api.sigs.k8s.io/guides/#installing-gateway-api) the Gateway API CRDs or
197+
follow the installation instructions of your selected implementation. After installing an
198+
implementation, use the [Getting Started](https://gateway-api.sigs.k8s.io/guides/) guide to help
199+
you quickly start working with Gateway API.
200+
201+
{{< note >}}
202+
Make sure to review the documentation of your selected implementation to understand any caveats.
203+
{{< /note >}}
204+
205+
Refer to the [API specification](https://gateway-api.sigs.k8s.io/reference/spec/) for additional
206+
details of all Gateway API kinds.

‎content/en/docs/concepts/services-networking/ingress.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ weight: 30
1515
{{< feature-state for_k8s_version="v1.19" state="stable" >}}
1616
{{< glossary_definition term_id="ingress" length="all" >}}
1717

18+
{{< note >}}
19+
Ingress is frozen. New features are being added to the [Gateway API](/docs/concepts/services-networking/gateway/).
20+
{{< /note >}}
21+
1822
<!-- body -->
1923

2024
## Terminology

‎content/en/docs/concepts/services-networking/service.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1006,7 +1006,7 @@ Learn more about Services and how they fit into Kubernetes:
10061006
* Read about [Ingress](/docs/concepts/services-networking/ingress/), which
10071007
exposes HTTP and HTTPS routes from outside the cluster to Services within
10081008
your cluster.
1009-
* Read about [Gateway](https://gateway-api.sigs.k8s.io/), an extension to
1009+
* Read about [Gateway](/docs/concepts/services-networking/gateway/), an extension to
10101010
Kubernetes that provides more flexibility than Ingress.
10111011

10121012
For more context, read the following:

‎content/en/docs/images/gateway-kind-relationships.svg

Lines changed: 1 addition & 0 deletions
Loading

‎content/en/docs/images/gateway-request-flow.svg

Lines changed: 1 addition & 0 deletions
Loading

‎content/en/docs/reference/glossary/gateway.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Gateway API
3+
id: gateway-api
4+
date: 2023-10-19
5+
full_link: /docs/concepts/services-networking/gateway/
6+
short_description: >
7+
An API for modeling service networking in Kubernetes.
8+
9+
aka:
10+
tags:
11+
- networking
12+
- architecture
13+
- extension
14+
---
15+
A family of API kinds for modeling service networking in Kubernetes.
16+
17+
<!--more-->
18+
19+
Gateway API provides a family of extensible, role-oriented, protocol-aware
20+
API kinds for modeling service networking in Kubernetes.

0 commit comments

Comments
 (0)