11# API Overview
22
3- This document provides an overview of Service APIs .
3+ This document provides an overview of Gateway API .
44
55## Roles and personas.
66
7- There are 3 primary roles in Service APIs :
7+ There are 3 primary roles in Gateway API :
88
99- Infrastructure Provider
1010- Cluster Operator
1111- Application Developer
1212
1313There could be a fourth role of Application Admin in some use cases.
1414
15- Please refer to the [ roles and personas] ( security-model.md#roles-and-personas )
15+ Please refer to the [ roles and personas] ( security-model.md#roles-and-personas )
1616section in the Security model for details.
1717
1818## Resource model
@@ -23,10 +23,10 @@ section in the Security model for details.
2323
2424There are three main types of objects in our resource model:
2525
26- * GatewayClass* defines a set of gateways with a common configuration and
26+ * GatewayClass* defines a set of gateways with a common configuration and
2727behavior.
2828
29- * Gateway* requests a point where traffic can be translated to Services within
29+ * Gateway* requests a point where traffic can be translated to Services within
3030the cluster.
3131
3232* Routes* describe how traffic coming via the Gateway maps to the Services.
@@ -56,8 +56,8 @@ A Gateway describes how traffic can be translated to Services within the
5656cluster. That is, it defines a request for a way to translate traffic from
5757somewhere that does not know about Kubernetes to somewhere that does. For
5858example, traffic sent to a Kubernetes Service by a cloud load balancer, an
59- in-cluster proxy, or an external hardware load balancer. While many use cases
60- have client traffic originating “outside” the cluster, this is not a
59+ in-cluster proxy, or an external hardware load balancer. While many use cases
60+ have client traffic originating “outside” the cluster, this is not a
6161requirement.
6262
6363It defines a request for a specific load balancer config that implements the
@@ -95,7 +95,7 @@ Some backend configuration may vary depending on the Route that is targeting the
9595backend. In those cases, configuration fields will be placed on Routes and not
9696BackendPolicy. For more information on what may be configured with this resource
9797in the future, refer to the related [ GitHub
98- issue] ( https://github.com/kubernetes-sigs/service-apis /issues/196 ) .
98+ issue] ( https://github.com/kubernetes-sigs/gateway-api /issues/196 ) .
9999
100100### Route binding
101101
@@ -113,23 +113,23 @@ are exposed and on which Gateways. Consider the following example:
113113> and as long as their Route rules do not conflict with each other they can
114114> continue operating in isolation. Team C has special networking needs (perhaps
115115> performance, security, or criticality) and they need a dedicated Gateway to
116- > proxy their application to the outside world. Team C deploys their own Gateway
117- > “dedicated-gw” in the “C” Namespace that can only be used by apps in the "C"
116+ > proxy their application to the outside world. Team C deploys their own Gateway
117+ > “dedicated-gw” in the “C” Namespace that can only be used by apps in the "C"
118118> Namespace.
119119
120120<!-- source: https://docs.google.com/presentation/d/1neBkFDTZ__vRoDXIWvAcxk2Pb7-evdBT6ykw_frf9QQ/edit?usp=sharing -->
121121![ route binding] ( images/gateway-route-binding.png )
122122
123123There is a lot of flexibility in how Routes can bind to Gateways to achieve
124- different organizational policies and scopes of responsibility. These are
124+ different organizational policies and scopes of responsibility. These are
125125different relationships that Gateways and Routes can have:
126126
127- - ** One-to-one** - A Gateway and Route may be deployed and used by a single
128- owner and have a one-to-one relationship. Team C is an example of this.
127+ - ** One-to-one** - A Gateway and Route may be deployed and used by a single
128+ owner and have a one-to-one relationship. Team C is an example of this.
129129- ** One-to-many** - A Gateway can have many Routes bound to it that are owned by
130- different teams from across different Namespaces. Teams A and B are an example
130+ different teams from across different Namespaces. Teams A and B are an example
131131 of this.
132- - ** Many-to-one** - Routes can also be bound to more than one Gateway, allowing
132+ - ** Many-to-one** - Routes can also be bound to more than one Gateway, allowing
133133 a single Route to control application exposure simultaneously across different
134134 IPs, load balancers, or networks.
135135
@@ -148,19 +148,19 @@ namespace, and labels of Route resources. Routes are actually bound to specific
148148listeners within the Gateway so each listener has a ` listener.routes ` field
149149which selects Routes by one or more of the following criterea:
150150
151- - ** Label** - A Gateway can select Routes via labels that exist on the
151+ - ** Label** - A Gateway can select Routes via labels that exist on the
152152resource (similar to how Services select Pods via Pod labels).
153- - ** Kind** - A Gateway listener can only select a single type of Route
153+ - ** Kind** - A Gateway listener can only select a single type of Route
154154resource. This could be an HTTPRoute, TCPRoute, or a custom Route type.
155155- ** Namespace** - A Gateway can also control from which Namespaces Routes can be
156156selected via the ` namespaces.from ` field. It supports three possible values:
157- - ` SameNamespace ` is the default option. Only Routes in the same namespace
158- as this Gateway will be selected.
157+ - ` SameNamespace ` is the default option. Only Routes in the same namespace
158+ as this Gateway will be selected.
159159 - ` All ` will select Routes from all Namespaces.
160- - ` Selector ` means that Routes from a subset of Namespaces selected by a
161- Namespace label selector will be selected by this Gateway. When ` Selector `
162- is used then the ` listeners.routes.namespaces.selector ` field can be used
163- to specify label selectors. This field is not supported with ` All ` or
160+ - ` Selector ` means that Routes from a subset of Namespaces selected by a
161+ Namespace label selector will be selected by this Gateway. When ` Selector `
162+ is used then the ` listeners.routes.namespaces.selector ` field can be used
163+ to specify label selectors. This field is not supported with ` All ` or
164164 ` SameNamespace ` .
165165
166166The below Gateway will select all HTTPRoute resources with the `expose:
@@ -170,12 +170,12 @@ prod-web-gw` across all Namespaces in the cluster.
170170kind: Gateway
171171...
172172spec:
173- listeners:
173+ listeners:
174174 - routes:
175175 kind: HTTPRoute
176176 selector:
177177 matchLabels:
178- expose: prod-web-gw
178+ expose: prod-web-gw
179179 namespaces:
180180 from: All
181181```
@@ -185,18 +185,18 @@ spec:
185185Routes can determine how they are exposed through Gateways. The ` gateways.allow `
186186field supports three values:
187187
188- - ` All ` is the default value if none is specified. This leaves all binding
189- to the Route label and Namespace selectors on the Gateway.
190- - ` SameNamespace ` only allows this Route to bind with Gateways from the
188+ - ` All ` is the default value if none is specified. This leaves all binding
189+ to the Route label and Namespace selectors on the Gateway.
190+ - ` SameNamespace ` only allows this Route to bind with Gateways from the
191191same Namespace.
192- - ` FromList ` allows an explicit list of Gateways to be specifiied that a
193- Route will bind with. ` gateways.gatewayRefs ` is only supported with this option.
192+ - ` FromList ` allows an explicit list of Gateways to be specifiied that a
193+ Route will bind with. ` gateways.gatewayRefs ` is only supported with this option.
194194
195195The following ` my-route ` Route selects only the ` foo-gateway ` in the
196196` foo-namespace ` and will not be able to bind with any other Gateways. Note that
197197` foo-gateway ` is in a different Namespace. If the ` foo-gateway ` allows
198198cross-Namespace binding and also selects this Route then ` my-route ` will bind to
199- it.
199+ it.
200200
201201``` yaml
202202kind : HTTPRoute
@@ -246,7 +246,7 @@ reverse proxy is:
246246 5. Optionally, the reverse proxy can perform request header and/or path
247247 matching based on `match` rules of the `HTTPRoute`.
248248 6. Optionally, the reverse proxy can modify the request, i.e. add/remove
249- headers, based on `filter` rules of the `HTTPRoute`.
249+ headers, based on `filter` rules of the `HTTPRoute`.
250250 7. Lastly, the reverse proxy forwards the request to one or more objects, i.e.
251251 ` Service` , in the cluster based on `forwardTo` rules of the `HTTPRoute`.
252252
@@ -272,7 +272,7 @@ Here is a summary of extension points in the API:
272272- **XForwardTo.BackendRef**: This extension point should be used for forwarding
273273 traffic to network endpoints other than core Kubernetes Service resource.
274274 Examples include an S3 bucket, Lambda function, a file-server, etc.
275- - **HTTPRouteFilter**: This API type in HTTPRoute provides a way to hook into
275+ - **HTTPRouteFilter**: This API type in HTTPRoute provides a way to hook into
276276the request/response lifecycle of an HTTP request.
277277- **Custom Routes**: If none of the above extensions points suffice for a use
278278 case, Implementers can chose to create custom Route resources for protocols
0 commit comments