Skip to content

Commit 10e5f19

Browse files
authored
Merge pull request #2691 from robscott/docs-cleanup
Significant docs cleanup and refresh
2 parents ec21ccb + ee3d356 commit 10e5f19

37 files changed

+1429
-610
lines changed

geps/overview.md

Lines changed: 39 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ process for the main Kubernetes project:
1616
This diagram shows the state diagram of the GEP process at a high level, but the details are below.
1717

1818
<div align="center">
19-
19+
2020
```mermaid
2121
flowchart TD
2222
D([Discuss with<br />the community]) --> C
@@ -222,36 +222,44 @@ What is out of scope: see [text from KEP][kep-when-to-use]. Examples:
222222

223223
## FAQ
224224

225-
* Q: Why is it named GEP?
226-
* A: To avoid potential confusion if people start following the cross
227-
references to the full KEP process.
228-
* Q: Why have a different process than mainline?
229-
* A: We would like to keep the machinery to an absolute minimum for now --
230-
this may change as we move to v1.
231-
* Q: Is it ok to discuss using shared docs, scratch docs etc?
232-
* A: Yes, this can be a helpful intermediate step when iterating on design
233-
details. It is important that all major feedback, discussions, and
234-
alternatives considered in that step are represented in the GEP though. A
235-
key goal of GEPs is to show why we made a decision and which alternatives
236-
were considered. If separate docs are used, it's important that we can
237-
still see all relevant context and decisions in the final GEP.
238-
* Q: When should I mark a GEP as `Prototyping` as opposed to `Provisional`?
239-
* A: The `Prototyping` status carries the same base meaning as `Provisional`
240-
in that consensus is not complete between stakeholders and we're not ready
241-
to move toward releasing content yet. You should use `Prototyping` to
242-
indicate to your fellow community members that we're in a state of active
243-
practical tests and experiments which are intended to help us learn and
244-
iterate on the GEP. These can include distributing content, but not under
245-
any release channel.
246-
* Q: Should I implement support for `Experimental` channel features?
247-
* A: Ultimately one of the main ways to get something into `Standard` is for
248-
it to mature through the `Experimental` phase, so we really _need_ people
249-
to implement these features and provide feedback in order to have progress.
250-
That said, the graduation of a feature past `Experimental` is not a forgone
251-
conclusion. Before implementing an experimental feature, you should:
252-
253-
* Clearly document that support for the feature is experimental and may disappear in the future.
254-
* Have a plan in place for how you would handle the removal of this feature from the API.
225+
#### Why is it named GEP?
226+
To avoid potential confusion if people start following the cross references to
227+
the full KEP process.
228+
229+
#### Why have a different process than mainline?
230+
Gateway API has some differences with most upstream KEPs. Notably Gateway API
231+
intentionally avoids including any implementation with the project, so this
232+
process is focused entirely on the substance of the API. As this project is
233+
based on CRDs it also has an entirely separately release process, and has
234+
developed concepts like "release channels" that do not exist in upstream.
235+
236+
#### Is it ok to discuss using shared docs, scratch docs etc?
237+
Yes, this can be a helpful intermediate step when iterating on design details.
238+
It is important that all major feedback, discussions, and alternatives
239+
considered in that step are represented in the GEP though. A key goal of GEPs is
240+
to show why we made a decision and which alternatives were considered. If
241+
separate docs are used, it's important that we can still see all relevant
242+
context and decisions in the final GEP.
243+
244+
#### When should I mark a GEP as `Prototyping` as opposed to `Provisional`?
245+
The `Prototyping` status carries the same base meaning as `Provisional` in that
246+
consensus is not complete between stakeholders and we're not ready to move
247+
toward releasing content yet. You should use `Prototyping` to indicate to your
248+
fellow community members that we're in a state of active practical tests and
249+
experiments which are intended to help us learn and iterate on the GEP. These
250+
can include distributing content, but not under any release channel.
251+
252+
#### Should I implement support for `Experimental` channel features?
253+
Ultimately one of the main ways to get something into `Standard` is for it to
254+
mature through the `Experimental` phase, so we really _need_ people to implement
255+
these features and provide feedback in order to have progress. That said, the
256+
graduation of a feature past `Experimental` is not a forgone conclusion. Before
257+
implementing an experimental feature, you should:
258+
259+
* Clearly document that support for the feature is experimental and may
260+
disappear in the future.
261+
* Have a plan in place for how you would handle the removal of this feature from
262+
the API.
255263

256264
[kep]: https://github.com/kubernetes/enhancements
257265
[kep-when-to-use]: https://github.com/kubernetes/enhancements/tree/master/keps#do-i-have-to-use-the-kep-process

mkdocs.yml

Lines changed: 56 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ repo_url: https://github.com/kubernetes-sigs/gateway-api
33
repo_name: kubernetes-sigs/gateway-api
44
site_dir: site
55
docs_dir: site-src
6+
extra_css:
7+
- stylesheets/extra.css
68
hooks:
79
- hack/mkdocs-copy-geps.py
810
watch:
@@ -11,12 +13,16 @@ theme:
1113
name: material
1214
icon:
1315
repo: fontawesome/brands/git-alt
14-
logo: images/k8s-favicon.png
16+
logo: images/logo/logo-text-large-horizontal-white.png
1517
favicon: images/k8s-favicon.png
1618
features:
1719
- search.highlight
1820
- navigation.tabs
1921
- navigation.top
22+
- navigation.expand
23+
palette:
24+
primary: custom
25+
custom_dir: site-src/overrides
2026
edit_uri: edit/main/site-src/
2127
plugins:
2228
- search
@@ -27,9 +33,11 @@ plugins:
2733
- redirects:
2834
redirect_maps:
2935
'guides/getting-started.md': 'guides/index.md'
36+
'concepts/gamma.md': 'mesh/index.md'
37+
'concepts/service-facets.md': 'mesh/service-facets.md'
3038
'concepts/guidelines.md': 'guides/api-design.md'
3139
'contributing/community.md': 'contributing/index.md'
32-
'contributing/gamma.md': 'concepts/gamma.md#contributing'
40+
'contributing/gamma.md': 'mesh/index.md#contributing'
3341
'reference/implementers-guide.md': 'guides/implementers.md'
3442
'references/implementers-guide.md': 'guides/implementers.md'
3543
'references/spec.md': 'reference/spec.md'
@@ -58,13 +66,15 @@ nav:
5866
- Introduction: index.md
5967
- Concepts:
6068
API Overview: concepts/api-overview.md
61-
GAMMA: concepts/gamma.md
6269
Conformance: concepts/conformance.md
6370
Roles and Personas: concepts/roles-and-personas.md
64-
Service Facets: concepts/service-facets.md
6571
Security Model: concepts/security-model.md
6672
Use Cases: concepts/use-cases.md
6773
Versioning: concepts/versioning.md
74+
- Service Mesh:
75+
Overview: mesh/index.md
76+
GAMMA Initiative: mesh/gamma.md
77+
Service Facets: mesh/service-facets.md
6878
- Implementations: implementations.md
6979
- FAQ: faq.md
7080
- Glossary: concepts/glossary.md
@@ -85,6 +95,7 @@ nav:
8595
- API Design: guides/api-design.md
8696
- CRD Management: guides/crd-management.md
8797
- Implementer's Guide: guides/implementers.md
98+
- Documentation Style Guide: guides/documentation.md
8899
- Reference:
89100
- API Types:
90101
- Gateway: api-types/gateway.md
@@ -96,57 +107,49 @@ nav:
96107
- ReferenceGrant: api-types/referencegrant.md
97108
- API specification: reference/spec.md
98109
- Policy Attachment: reference/policy-attachment.md
99-
- Enhancement Proposals:
100-
- Overview: geps/overview.md
101-
- Memorandum:
102-
- geps/gep-917/index.md
103-
- geps/gep-922/index.md
104-
- geps/gep-1324/index.md
105-
- geps/gep-2659/index.md
106-
- Declined:
107-
- geps/gep-735/index.md
108-
- geps/gep-1282/index.md
109-
- Provisional:
110-
- geps/gep-91/index.md
111-
- geps/gep-1619/index.md
112-
- geps/gep-1651/index.md
113-
- geps/gep-1867/index.md
114-
# - Implementable:
115-
# -
116-
- Experimental:
117-
- geps/gep-713/index.md
118-
- geps/gep-957/index.md
119-
- geps/gep-1016/index.md
120-
- geps/gep-1426/index.md
121-
- geps/gep-1686/index.md
122-
- geps/gep-1709/index.md
123-
- geps/gep-1742/index.md
124-
- geps/gep-1748/index.md
125-
- geps/gep-1762/index.md
126-
- geps/gep-1897/index.md
127-
- geps/gep-1911/index.md
128-
- geps/gep-2162/index.md
129-
- geps/gep-2257/index.md
130-
- Standard:
131-
- geps/gep-709/index.md
132-
- geps/gep-718/index.md
133-
- geps/gep-724/index.md
134-
- geps/gep-726/index.md
135-
- geps/gep-746/index.md
136-
- geps/gep-820/index.md
137-
- geps/gep-851/index.md
138-
- geps/gep-1323/index.md
139-
- geps/gep-1364/index.md
110+
- Enhancements:
111+
- Overview: geps/overview.md
112+
- Provisional:
113+
- geps/gep-91/index.md
114+
- geps/gep-1619/index.md
115+
- geps/gep-1651/index.md
116+
- geps/gep-1867/index.md
117+
# - Implementable:
118+
# -
119+
- Experimental:
120+
- geps/gep-713/index.md
121+
- geps/gep-957/index.md
122+
- geps/gep-1016/index.md
123+
- geps/gep-1426/index.md
124+
- geps/gep-1686/index.md
125+
- geps/gep-1709/index.md
126+
- geps/gep-1742/index.md
127+
- geps/gep-1748/index.md
128+
- geps/gep-1762/index.md
129+
- geps/gep-1897/index.md
130+
- geps/gep-1911/index.md
131+
- geps/gep-2162/index.md
132+
- geps/gep-2257/index.md
133+
- Standard:
134+
- geps/gep-709/index.md
135+
- geps/gep-718/index.md
136+
- geps/gep-724/index.md
137+
- geps/gep-726/index.md
138+
- geps/gep-746/index.md
139+
- geps/gep-820/index.md
140+
- geps/gep-851/index.md
141+
- geps/gep-1323/index.md
142+
- geps/gep-1364/index.md
143+
- Memorandum:
144+
- geps/gep-917/index.md
145+
- geps/gep-922/index.md
146+
- geps/gep-1324/index.md
147+
- geps/gep-2659/index.md
148+
- Declined:
149+
- geps/gep-735/index.md
150+
- geps/gep-1282/index.md
140151
- Contributing:
141152
- How to Get Involved: contributing/index.md
142153
- Developer Guide: contributing/devguide.md
143154
- Enhancement Requests: contributing/enhancement-requests.md
144155
- Contributor Ladder: contributing/contributor-ladder.md
145-
- Blog:
146-
- Index: blog/index.md
147-
- 2023:
148-
- blog/2023/0829-mesh-support.md
149-
- 2022:
150-
- blog/2022/graduating-to-beta.md
151-
- 2021:
152-
- blog/2021/introducing-v1alpha2.md

site-src/api-types/gateway.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
The `Gateway` resource is Beta and part of the Standard Channel in `v0.5.0+`.
66

7-
A `Gateway` is 1:1 with the life cycle of the configuration of infrastructure.
7+
A `Gateway` is 1:1 with the lifecycle of the configuration of infrastructure.
88
When a user creates a `Gateway`, some load balancing infrastructure is
99
provisioned or configured (see below for details) by the `GatewayClass`
1010
controller. `Gateway` is the resource that triggers actions in this API. Other

site-src/api-types/grpcroute.md

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,9 @@
22

33
??? example "Experimental Channel in v0.6.0+"
44

5-
The `GRPCRoute` resource is Alpha and part of the Experimental Channel in `v0.6.0+`.
6-
7-
!!! info "Experimental Channel"
8-
9-
The `GRPCRoute` resource described below is currently only included in the
10-
"Experimental" channel of Gateway API. For more information on release
11-
channels, refer to the [related documentation](https://gateway-api.sigs.k8s.io/concepts/versioning).
12-
5+
The `GRPCRoute` resource is Alpha and part of the Experimental Channel in
6+
`v0.6.0+`. For more information on release channels, refer to the [related
7+
documentation](/concepts/versioning).
138

149
[GRPCRoute][grpcroute] is a Gateway API type for specifying routing behavior
1510
of gRPC requests from a Gateway listener to an API object, i.e. Service.
@@ -41,7 +36,7 @@ the following criteria are met:
4136
- Users of the enapsulated protocol would experience a degraded user experience if forced to route at a lower layer.
4237
- The encapsulated protocol has a significant user base, particularly in the Kubernetes community.
4338

44-
gRPC meets all of these criteria, so the decision was made to include `GRPCRoute`in the Gateway API.
39+
gRPC meets all of these criteria, so the decision was made to include `GRPCRoute`in Gateway API.
4540

4641
### Cross Serving
4742

site-src/blog/2021/introducing-v1alpha2.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,13 @@ conversion is not possible.
3030
### Simpler Route-Gateway Binding
3131
In v1alpha1 we provided many ways to connect Gateways and Routes. This was a bit
3232
more complicated to understand than we'd like. With v1alpha2, we've focused on
33-
simpler attachment mechanism:
33+
simpler attachment mechanism:
3434

3535
* Routes directly reference the Gateway(s) they want to attach to. This is a
3636
list, so a Route can attach to more than one Gateway.
3737
* Each Gateway listener can choose to specify the kinds of Routes they support
3838
and where they can be. This defaults to Routes that support the specified
39-
protocol in the same Namespace as the Gateway.
39+
protocol in the same Namespace as the Gateway.
4040

4141
For example, the following HTTPRoute uses the `parentRefs` field to attach
4242
itself to the `prod-web-gw` Gateway.
@@ -55,15 +55,15 @@ spec:
5555
port: 8080
5656
```
5757
58-
This is covered in more detail in [GEP 724](https://gateway-api.sigs.k8s.io/geps/gep-709/).
58+
This is covered in more detail in [GEP 724](/geps/gep-709/).
5959
6060
### Safe Cross Namespace References
6161
6262
!!! info "Experimental Channel"
6363
6464
The `ReferenceGrant` resource described below is currently only included in the
6565
"Experimental" channel of Gateway API. For more information on release
66-
channels, refer to the [related documentation](https://gateway-api.sigs.k8s.io/concepts/versioning).
66+
channels, refer to the [related documentation](/concepts/versioning).
6767

6868
It is quite challenging to cross namespace boundaries in a safe manner. With
6969
Gateway API, we had several key feature requests that required this capability.
@@ -97,7 +97,7 @@ spec:
9797
kind: Service
9898
```
9999

100-
This is covered in more detail in [GEP 709](https://gateway-api.sigs.k8s.io/geps/gep-709/).
100+
This is covered in more detail in [GEP 709](/geps/gep-709/).
101101

102102
### Policy Attachment
103103
One of the key goals of this API is to provide meaningful and consistent
@@ -127,12 +127,12 @@ of that policy would cascade down to Routes attached to that policy:
127127

128128
![Simple Ingress Example](/images/policy/ingress-simple.png)
129129

130-
This is covered in more detail in [GEP 713](https://gateway-api.sigs.k8s.io/geps/gep-713/).
130+
This is covered in more detail in [GEP 713](/geps/gep-713/).
131131

132132
## Next Steps
133133
There are a lot of changes in v1alpha2 that we haven't covered here. For the
134134
full changelog, refer to our [v0.4.0 release
135-
notes](https://github.com/kubernetes-sigs/gateway-api/releases/tag/v0.4.0).
135+
notes](https://github.com/kubernetes-sigs/gateway-api/releases/tag/v0.4.0).
136136

137137
Many of our [implementations](/implementations) are planning to release support
138138
for the v1alpha2 API in the coming weeks. We'll update our documentation as

0 commit comments

Comments
 (0)