Docs Improvements

[mark-church]

I wanted to list out some general docs improvements that would improve the site, for others to contribute, and also to keep track for myself. If anybody else has docs improvements that they would find valuable, feel free to pile on this issue and we can keep a running tracker.

• Make user guide Service names consistent (and consistent within concept docs too). There is foo-v1, foo-v2, foo, foo-canary, etc. Ideally, a small set of Deployment and Service resources should be able to be used to run every single one of the user guides so making the example names converge to only a few would allow this to happen.
• This needs discussion, but we should decide whether we want to specify an actual application Deployment within the Gateway docs so we can include end-to-end examples that contain real output from an app. I personally think this would be a good move because it would allow the user guides to have concrete steps in them rather than being theoretical examples as they are now. In a previous version of the user guide I used whereami but I'm happy to use any app that highlights the user guides we have.
• The multi-ns user guide should be reformatted into a similar style as the other guide
• The TLS in HTTPRoute user guide has some good conceptual content that is maybe better suited for Gateway concepts. Perhaps we should move some of that content there and slim down this TLS example to a smaller and self-contained guide.
• A TLSRoute user guide and also TLSRoute API Types page.
• Addition of a "Gateway API implementations" page (or maybe add this content to getting started ) that lists out the current and planned implementations for Gateway. Ideally a user can go to an implementations page which shows how to install or enable that Gateway Controller and corresponding GatewayClasses in a K8s cluster. Then the user can deploy a reference Gateway from one of these GatewayClasses and continue with any of the standard user-guides, which should all theoretically function if that GatewayClass and controller is compliant.
• Gateway and Route ownership patterns need to be documented. There are several design patterns that make sense:
  • Single-tenant Gateways - Gateway and Route in same Namespace / Gateway and Route deployed by same owner
  • Shared Gateways - Gateways shared by Routes which are owned by different users (across Namespaces and also within the same Namespace)
  • Controlling hostname ownership - This is related to the route merging and conflicts, but a very common question is how to control which route-owners can own which hostnames. This can be done by specifying multiple listeners for the same port with different hostnames. Each of these listeners is bound to a different set of Routes, effectively giving those Routes exclusive ownership over the hostname. Since this is a design pattern, this capability is not really obvious to users and so it should be documented.
• We probably need some more conceptual content and examples for the Gateway concepts page.
• Route merging and conflicts are only described in the API specification reference. This should have a section in the concept (or HTTPRoute) portion of the docs.

Happy to take edits or additions to this list. I just wanted to record what's on the top of my head before I forget :)

kind/docs

[robscott]

This is a great list, thanks for putting it together! I completely agree with more real end to end examples. I still remember how helpful that classic guestbook example was for me when I was getting started with Kubernetes. Providing examples that are similarly useful will make this API much easier to get started with.

[shaneutt]

As per today's sync and some slack chat that's been going on I'll take on this one:

Addition of a "Gateway API implementations" page (or maybe add this content to getting started ) that lists out the current and planned implementations for Gateway. Ideally a user can go to an implementations page which shows how to install or enable that Gateway Controller and corresponding GatewayClasses in a K8s cluster. Then the user can deploy a reference Gateway from one of these GatewayClasses and continue with any of the standard user-guides, which should all theoretically function if that GatewayClass and controller is compliant.

[robscott]

/reopen

[k8s-ci-robot]

@robscott: Reopened this issue.

In response to this:

/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[mateiidavid]

I'd like to improve the TLS section a bit, if that's okay.
i.e

The TLS user guide has some good conceptual content that is maybe better suited for Gateway concepts. Perhaps we should move some of that content there and slim down this TLS example to a smaller and self-contained guide.

[shaneutt]

@robscott @mark-church what do you think about us breaking down the checkboxes into several smaller issues? Maybe since there are so many smaller things to tackle logistically we could put together a documentation milestone or something to organize them?

Just thinking out loud as I feel like we could break this one down a bit, let me know your thoughts 🤔

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[jpeach]

/remove-lifecycle rotten
/lifecycle frozen

[pottekkat]

@mark-church @robscott Was there any effort made to build an example application?

[robscott]

@navendu-pottekkat I'm not sure, what would that look like?

[pottekkat]

@robscott I was referring to these two points (first two) made in the issue description:

Make user guide Service names consistent (and consistent within concept docs too). There is foo-v1, foo-v2, foo, foo-canary, etc. Ideally, a small set of Deployment and Service resources should be able to be used to run every single one of the user guides so making the example names converge to only a few would allow this to happen.

This needs discussion, but we should decide whether we want to specify an actual application Deployment within the Gateway docs so we can include end-to-end examples that contain real output from an app. I personally think this would be a good move because it would allow the user guides to have concrete steps in them rather than being theoretical examples as they are now. In a previous version of the user guide I used whereami but I'm happy to use any app that highlights the user guides we have.

So, this example application would be able to demonstrate the features provided through the Gateway API. And the goal for creating such an application would be to use it in examples so that readers can actually see an e2e example and test it out themselves using their choice of a Gateway API implementation.

I was looking for such applications for our own project when I came across this issue. We were considering building such an application if there were no existing examples.

So, if there are any existing works, discussions, or ideas, we would be happy to contribute and build on it. Otherwise, if creating a sample application is still a goal, we can maybe help take initiative and work on a proposal for the application.

[shaneutt]

@navendu-pottekkat I'm not sure if it's exactly what you're looking for but we're currently working on https://github.com/kong/blixt (which is being donated to Kubernetes SIGs, see kubernetes/org#3875) as a layer 4 implementation of Gateway API meant for CI testing and reference purposes. I wouldn't say it's in the right shape today to be used as a reference yet but we have several people who have joined in to collaborate on it and we expect it should be migrated to https://github.com/kubernetes-sigs soon. If you're interested we'd love to have you join us! We have a Gateway API meeting called [SIG Network] Gateway API Code Jam on fridays (it's on the Kubernetes SIGs calendar) where this has been the main topic of conversation for several weeks.

[shaneutt]

If someone takes this one on, the best next step would be to verify that the bullet point items are still relevant to current documentation and break the remaining individual bullet point items out into separate issues.

[shaneutt]

This has grown quite old, and at this point it would appear to make more sense to rely on new reports of problems with the documentation than to try and organize this existing one forward. That said, "closed" does not mean "dead", it mainly means not prioritized: if there's reason to re-open this please let us know the context, and if you're interested in helping to move it forward.