Skip to content

Commit b31ab24

Browse files
mark-churchmark-church
committed
indented api-overview.md to 80 chars
1 parent 86e7b49 commit b31ab24

File tree

2 files changed

+110
-72
lines changed

2 files changed

+110
-72
lines changed

‎docs-src/api-overview.md

+55-36
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ There are 3 primary roles in Service APIs:
1212

1313
There 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) section
16-
in the Security model for details.
15+
Please refer to the [roles and personas](security-model.md#roles-and-personas)
16+
section in the Security model for details.
1717

1818
## Resource model
1919

@@ -23,47 +23,64 @@ in the Security model for details.
2323
2424
There are three main types of objects in our resource model:
2525

26-
*GatewayClass* defines a set of gateways with a common configuration and behavior.
26+
*GatewayClass* defines a set of gateways with a common configuration and
27+
behavior.
2728

28-
*Gateway* requests a point where traffic can be translated to Services within the cluster.
29+
*Gateway* requests a point where traffic can be translated to Services within
30+
the cluster.
2931

3032
*Routes* describe how traffic coming via the Gateway maps to the Services.
3133

3234
### GatewayClass
3335

34-
GatewayClass defines a set of Gateways that share a common configuration and behaviour.
35-
Each GatewayClass will be handled by a single controller, although controllers MAY handle more than one.
36+
GatewayClass defines a set of Gateways that share a common configuration and
37+
behaviour. Each GatewayClass will be handled by a single controller, although
38+
controllers MAY handle more than one.
3639

37-
GatewayClass is a cluster-scoped resource.
38-
There MUST be at least one GatewayClass defined in order to be able to have functional Gateways.
39-
A controller that implements the Gateway API does so by providing an associated GatewayClass resource that the user can reference from their Gateway(s).
40+
GatewayClass is a cluster-scoped resource. There MUST be at least one
41+
GatewayClass defined in order to be able to have functional Gateways. A
42+
controller that implements the Gateway API does so by providing an associated
43+
GatewayClass resource that the user can reference from their Gateway(s).
4044

41-
This is similar to [IngressClass](https://github.com/kubernetes/enhancements/blob/master/keps/sig-network/20190125-ingress-api-group.md#ingress-class) for Ingress and [StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/) for PersistentVolumes.
42-
In Ingress v1beta1, the closest analog to GatewayClass is the `ingress-class` annotation, and in IngressV1, the closest analog is the IngressClass object.
45+
This is similar to
46+
[IngressClass](https://github.com/kubernetes/enhancements/blob/master/keps/sig-network/20190125-ingress-api-group.md#ingress-class)
47+
for Ingress and
48+
[StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/) for
49+
PersistentVolumes. In Ingress v1beta1, the closest analog to GatewayClass is the
50+
`ingress-class` annotation, and in IngressV1, the closest analog is the
51+
IngressClass object.
4352

4453
### Gateway
4554

46-
A Gateway describes how traffic can be translated to Services within the cluster.
47-
That is, it defines a request for a way to translate traffic from somewhere that does not know about Kubernetes to somewhere that does.
48-
For example, traffic sent to a Kubernetes Service by a cloud load balancer, an in-cluster proxy or external hardware load balancer.
49-
While many use cases have client traffic originating “outside” the cluster, this is not a requirement.
55+
A Gateway describes how traffic can be translated to Services within the
56+
cluster. That is, it defines a request for a way to translate traffic from
57+
somewhere that does not know about Kubernetes to somewhere that does. For
58+
example, traffic sent to a Kubernetes Service by a cloud load balancer, an
59+
in-cluster proxy or external hardware load balancer. While many use cases have
60+
client traffic originating “outside” the cluster, this is not a requirement.
5061

51-
It defines a request for a specific load balancer config that implements the GatewayClass’ configuration and behaviour contract.
52-
The resource MAY be created by an operator directly, or MAY be created by a controller handling a GatewayClass.
62+
It defines a request for a specific load balancer config that implements the
63+
GatewayClass’ configuration and behaviour contract. The resource MAY be created
64+
by an operator directly, or MAY be created by a controller handling a
65+
GatewayClass.
5366

54-
As the Gateway spec captures user intent, it may not contain a complete specification for all attributes in the spec.
55-
For example, the user may omit fields such as addresses, ports, TLS settings.
56-
This allows the controller managing the GatewayClass to provide these settings for the user, resulting in a more portable spec.
57-
This behaviour will be made clear using the GatewayClass Status object.
67+
As the Gateway spec captures user intent, it may not contain a complete
68+
specification for all attributes in the spec. For example, the user may omit
69+
fields such as addresses, ports, TLS settings. This allows the controller
70+
managing the GatewayClass to provide these settings for the user, resulting in a
71+
more portable spec. This behaviour will be made clear using the GatewayClass
72+
Status object.
5873

59-
A Gateway MAY contain one or more *Route references which serve to direct traffic for a subset of traffic to a specific service.
74+
A Gateway MAY contain one or more *Route references which serve to direct
75+
traffic for a subset of traffic to a specific service.*
6076

6177
### {HTTP,TCP,Foo}Route
6278

63-
Route objects define protocol-specific rules for mapping requests from a Gateway to Kubernetes Services.
79+
Route objects define protocol-specific rules for mapping requests from a Gateway
80+
to Kubernetes Services.
6481

65-
`HTTPRoute` and `TCPRoute` are currently the only defined Route objects. Additional protocol-specific Route
66-
objects may be added in the future.
82+
`HTTPRoute` and `TCPRoute` are currently the only defined Route objects.
83+
Additional protocol-specific Route objects may be added in the future.
6784

6885
### BackendPolicy
6986

@@ -90,18 +107,20 @@ relationships between the different resources:
90107

91108
## Request flow
92109

93-
A typical client/gateway API request flow for a gateway implemented using a reverse proxy is:
110+
A typical client/gateway API request flow for a gateway implemented using a
111+
reverse proxy is:
94112

95113
1. A client makes a request to http://foo.example.com.
96114
2. DNS resolves the name to a `Gateway` address.
97-
3. The reverse proxy receives the request on a `Listener` and uses the
98-
[Host header](https://tools.ietf.org/html/rfc7230#section-5.4) to match an `HTTPRoute`.
99-
5. Optionally, the reverse proxy can perform request header and/or path matching based
100-
on `match` rules of the `HTTPRoute`.
101-
6. Optionally, the reverse proxy can modify the request, i.e. add/remove headers, based
102-
on `filter` rules of the `HTTPRoute`.
103-
7. Lastly, the reverse proxy forwards the request to one or more objects, i.e. `Service`,
104-
in the cluster based on `forwardTo` rules of the `HTTPRoute`.
115+
3. The reverse proxy receives the request on a `Listener` and uses the [Host
116+
header](https://tools.ietf.org/html/rfc7230#section-5.4) to match an
117+
`HTTPRoute`.
118+
5. Optionally, the reverse proxy can perform request header and/or path
119+
matching based on `match` rules of the `HTTPRoute`.
120+
6. Optionally, the reverse proxy can modify the request, i.e. add/remove
121+
headers, based on `filter` rules of the `HTTPRoute`.
122+
7. Lastly, the reverse proxy forwards the request to one or more objects, i.e.
123+
`Service`, in the cluster based on `forwardTo` rules of the `HTTPRoute`.
105124

106125
## TLS Configuration
107126

@@ -125,8 +144,8 @@ Here is a summary of extension points in the API:
125144
- **XForwardTo.BackendRef**: This extension point should be used for forwarding
126145
traffic to network endpoints other than core Kubernetes Service resource.
127146
Examples include an S3 bucket, Lambda function, a file-server, etc.
128-
- **HTTPRouteFilter**: This API type in HTTPRoute provides a way to hook into the
129-
request/response lifecycle of an HTTP request.
147+
- **HTTPRouteFilter**: This API type in HTTPRoute provides a way to hook into
148+
the request/response lifecycle of an HTTP request.
130149
- **Custom Routes**: If none of the above extensions points suffice for a use
131150
case, Implementers can chose to create custom Route resources for protocols
132151
that are not currently supported in the API.

‎docs/api-overview/index.html

+55-36
Original file line numberDiff line numberDiff line change
@@ -761,42 +761,59 @@ <h2 id="roles-and-personas">Roles and personas.</h2>
761761
<li>Application Developer</li>
762762
</ul>
763763
<p>There could be a fourth role of Application Admin in some use cases.</p>
764-
<p>Please refer to the <a href="../security-model/#roles-and-personas">roles and personas</a> section
765-
in the Security model for details.</p>
764+
<p>Please refer to the <a href="../security-model/#roles-and-personas">roles and personas</a>
765+
section in the Security model for details.</p>
766766
<h2 id="resource-model">Resource model</h2>
767767
<blockquote>
768768
<p>Note: Resources will initially live in the <code>networking.x-k8s.io</code> API group as
769769
Custom Resource Definitions (CRDs). Unqualified resource names will implicitly
770770
be in this API group.</p>
771771
</blockquote>
772772
<p>There are three main types of objects in our resource model:</p>
773-
<p><em>GatewayClass</em> defines a set of gateways with a common configuration and behavior.</p>
774-
<p><em>Gateway</em> requests a point where traffic can be translated to Services within the cluster.</p>
773+
<p><em>GatewayClass</em> defines a set of gateways with a common configuration and
774+
behavior.</p>
775+
<p><em>Gateway</em> requests a point where traffic can be translated to Services within
776+
the cluster.</p>
775777
<p><em>Routes</em> describe how traffic coming via the Gateway maps to the Services.</p>
776778
<h3 id="gatewayclass">GatewayClass</h3>
777-
<p>GatewayClass defines a set of Gateways that share a common configuration and behaviour.
778-
Each GatewayClass will be handled by a single controller, although controllers MAY handle more than one.</p>
779-
<p>GatewayClass is a cluster-scoped resource.
780-
There MUST be at least one GatewayClass defined in order to be able to have functional Gateways.
781-
A controller that implements the Gateway API does so by providing an associated GatewayClass resource that the user can reference from their Gateway(s).</p>
782-
<p>This is similar to <a href="https://github.com/kubernetes/enhancements/blob/master/keps/sig-network/20190125-ingress-api-group.md#ingress-class">IngressClass</a> for Ingress and <a href="https://kubernetes.io/docs/concepts/storage/storage-classes/">StorageClass</a> for PersistentVolumes.
783-
In Ingress v1beta1, the closest analog to GatewayClass is the <code>ingress-class</code> annotation, and in IngressV1, the closest analog is the IngressClass object.</p>
779+
<p>GatewayClass defines a set of Gateways that share a common configuration and
780+
behaviour. Each GatewayClass will be handled by a single controller, although
781+
controllers MAY handle more than one.</p>
782+
<p>GatewayClass is a cluster-scoped resource. There MUST be at least one
783+
GatewayClass defined in order to be able to have functional Gateways. A
784+
controller that implements the Gateway API does so by providing an associated
785+
GatewayClass resource that the user can reference from their Gateway(s).</p>
786+
<p>This is similar to
787+
<a href="https://github.com/kubernetes/enhancements/blob/master/keps/sig-network/20190125-ingress-api-group.md#ingress-class">IngressClass</a>
788+
for Ingress and
789+
<a href="https://kubernetes.io/docs/concepts/storage/storage-classes/">StorageClass</a> for
790+
PersistentVolumes. In Ingress v1beta1, the closest analog to GatewayClass is the
791+
<code>ingress-class</code> annotation, and in IngressV1, the closest analog is the
792+
IngressClass object.</p>
784793
<h3 id="gateway">Gateway</h3>
785-
<p>A Gateway describes how traffic can be translated to Services within the cluster.
786-
That is, it defines a request for a way to translate traffic from somewhere that does not know about Kubernetes to somewhere that does.
787-
For example, traffic sent to a Kubernetes Service by a cloud load balancer, an in-cluster proxy or external hardware load balancer.
788-
While many use cases have client traffic originating “outside” the cluster, this is not a requirement.</p>
789-
<p>It defines a request for a specific load balancer config that implements the GatewayClass’ configuration and behaviour contract.
790-
The resource MAY be created by an operator directly, or MAY be created by a controller handling a GatewayClass.</p>
791-
<p>As the Gateway spec captures user intent, it may not contain a complete specification for all attributes in the spec.
792-
For example, the user may omit fields such as addresses, ports, TLS settings.
793-
This allows the controller managing the GatewayClass to provide these settings for the user, resulting in a more portable spec.
794-
This behaviour will be made clear using the GatewayClass Status object.</p>
795-
<p>A Gateway MAY contain one or more *Route references which serve to direct traffic for a subset of traffic to a specific service.</p>
794+
<p>A Gateway describes how traffic can be translated to Services within the
795+
cluster. That is, it defines a request for a way to translate traffic from
796+
somewhere that does not know about Kubernetes to somewhere that does. For
797+
example, traffic sent to a Kubernetes Service by a cloud load balancer, an
798+
in-cluster proxy or external hardware load balancer. While many use cases have
799+
client traffic originating “outside” the cluster, this is not a requirement.</p>
800+
<p>It defines a request for a specific load balancer config that implements the
801+
GatewayClass’ configuration and behaviour contract. The resource MAY be created
802+
by an operator directly, or MAY be created by a controller handling a
803+
GatewayClass.</p>
804+
<p>As the Gateway spec captures user intent, it may not contain a complete
805+
specification for all attributes in the spec. For example, the user may omit
806+
fields such as addresses, ports, TLS settings. This allows the controller
807+
managing the GatewayClass to provide these settings for the user, resulting in a
808+
more portable spec. This behaviour will be made clear using the GatewayClass
809+
Status object.</p>
810+
<p>A Gateway MAY contain one or more <em>Route references which serve to direct
811+
traffic for a subset of traffic to a specific service.</em></p>
796812
<h3 id="httptcpfooroute">{HTTP,TCP,Foo}Route</h3>
797-
<p>Route objects define protocol-specific rules for mapping requests from a Gateway to Kubernetes Services.</p>
798-
<p><code>HTTPRoute</code> and <code>TCPRoute</code> are currently the only defined Route objects. Additional protocol-specific Route
799-
objects may be added in the future.</p>
813+
<p>Route objects define protocol-specific rules for mapping requests from a Gateway
814+
to Kubernetes Services.</p>
815+
<p><code>HTTPRoute</code> and <code>TCPRoute</code> are currently the only defined Route objects.
816+
Additional protocol-specific Route objects may be added in the future.</p>
800817
<h3 id="backendpolicy">BackendPolicy</h3>
801818
<p>BackendPolicy provides a way to configure connections between a Gateway and a
802819
backend. For the purpose of this API, a backend is any resource that a route can
@@ -816,18 +833,20 @@ <h3 id="combined-types">Combined types</h3>
816833

817834
<p><img alt="schema" src="../images/schema-uml.svg" /></p>
818835
<h2 id="request-flow">Request flow</h2>
819-
<p>A typical client/gateway API request flow for a gateway implemented using a reverse proxy is:</p>
836+
<p>A typical client/gateway API request flow for a gateway implemented using a
837+
reverse proxy is:</p>
820838
<ol>
821839
<li>A client makes a request to http://foo.example.com.</li>
822840
<li>DNS resolves the name to a <code>Gateway</code> address.</li>
823-
<li>The reverse proxy receives the request on a <code>Listener</code> and uses the
824-
<a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host header</a> to match an <code>HTTPRoute</code>.</li>
825-
<li>Optionally, the reverse proxy can perform request header and/or path matching based
826-
on <code>match</code> rules of the <code>HTTPRoute</code>.</li>
827-
<li>Optionally, the reverse proxy can modify the request, i.e. add/remove headers, based
828-
on <code>filter</code> rules of the <code>HTTPRoute</code>.</li>
829-
<li>Lastly, the reverse proxy forwards the request to one or more objects, i.e. <code>Service</code>,
830-
in the cluster based on <code>forwardTo</code> rules of the <code>HTTPRoute</code>.</li>
841+
<li>The reverse proxy receives the request on a <code>Listener</code> and uses the <a href="https://tools.ietf.org/html/rfc7230#section-5.4">Host
842+
header</a> to match an
843+
<code>HTTPRoute</code>.</li>
844+
<li>Optionally, the reverse proxy can perform request header and/or path
845+
matching based on <code>match</code> rules of the <code>HTTPRoute</code>.</li>
846+
<li>Optionally, the reverse proxy can modify the request, i.e. add/remove
847+
headers, based on <code>filter</code> rules of the <code>HTTPRoute</code>. </li>
848+
<li>Lastly, the reverse proxy forwards the request to one or more objects, i.e.
849+
<code>Service</code>, in the cluster based on <code>forwardTo</code> rules of the <code>HTTPRoute</code>.</li>
831850
</ol>
832851
<h2 id="tls-configuration">TLS Configuration</h2>
833852
<p>TLS is configured on Gateway listeners. Additionally, TLS certificates
@@ -845,8 +864,8 @@ <h2 id="extension-points">Extension points</h2>
845864
<li><strong>XForwardTo.BackendRef</strong>: This extension point should be used for forwarding
846865
traffic to network endpoints other than core Kubernetes Service resource.
847866
Examples include an S3 bucket, Lambda function, a file-server, etc.</li>
848-
<li><strong>HTTPRouteFilter</strong>: This API type in HTTPRoute provides a way to hook into the
849-
request/response lifecycle of an HTTP request.</li>
867+
<li><strong>HTTPRouteFilter</strong>: This API type in HTTPRoute provides a way to hook into
868+
the request/response lifecycle of an HTTP request.</li>
850869
<li><strong>Custom Routes</strong>: If none of the above extensions points suffice for a use
851870
case, Implementers can chose to create custom Route resources for protocols
852871
that are not currently supported in the API.</li>

0 commit comments

Comments
 (0)