kubernetes-sigs
Add documentation for choosing the right Route type
This PR adds documentation explaining when to use HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, and UDPRoute. It provides practical guidance to help users understand the differences between Route types and how to select the correct one based on protocol requirements, TLS termination behavior, and Gateway capabilities.
The new page includes:
- What to verify on a Gateway before selecting a Route
- How each Route type works and its intended use cases
- A decision table for mapping workloads to Route types
- Guidance on when to use HTTPRoute vs TLSRoute for HTTPS traffic
- Key questions to confirm with administrators
- Examples for each Route type
Which issue(s) this PR fixes:
Fixes #4306
Type of PR: /kind documentation
Does this PR introduce a user-facing change?
Add documentation for selecting the correct Route type.
Adding the "do-not-merge/release-note-label-needed" label because no release-note block was detected, please follow our release note process to remove it.
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-sigs/prow repository.
The committers listed above are authorized under a signed CLA.
- :white_check_mark: login: ryurulz / name: Riyad Abdul Aziz (062fa64c8f4218960a025d9e70b685590a2f1717, a892bab3c31dcb817df346b1cc45519a93412a7b)
![linux-foundation-easycla[bot] avatar](https://avatars.githubusercontent.com/in/17893?v=4 "Published by a pub.dev verified publisher"){kind=small}
[APPROVALNOTIFIER] This PR is NOT APPROVED
This pull-request has been approved by: ryurulz Once this PR has been reviewed and has the lgtm label, please assign thockin for approval. For more information see the Code Review Process.
The full list of commands accepted by this bot can be found here.
Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment
Welcome @ryurulz!
It looks like this is your first PR to kubernetes-sigs/gateway-api 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.
You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.
You can also check if kubernetes-sigs/gateway-api has its own contribution guidelines.
You may want to refer to our testing guide if you run into trouble with your tests not passing.
If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!
Thank you, and welcome to Kubernetes. :smiley:
Hi @ryurulz. Thanks for your PR.
I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.
Once the patch is verified, the new status will be reflected by the ok-to-test label.
I understand the commands that are listed here.
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-sigs/prow repository.
/ok-to-test
Thanks for opening this @ryurulz! I'm not sure if a standalone page is the right way to format this or if it should be rolled into somewhere else but we could definitely use some better guidance here, especially on some of the trickier TLS termination and SNI routing bits.
If you're able to join the Gateway API meeting later today it might be good to discuss this https://gateway-api.sigs.k8s.io/contributing/#meetings
@mikemorris Thanks for the quick review!
I’d be happy to discuss this further. The meeting time is quite late in my timezone (India), so joining live may be difficult, but if it's really necessary for this discussion I can try to attend.
If possible, I’d appreciate continuing the conversation on Slack instead. I'd love to get the team's guidance on the preferred structure for this content and on how to refine the TLS/SNI sections. I’m happy to iterate on the PR based on the team’s suggestions.
Please let me know what works best.
Ah don't worry about joining in that case, not worth getting up in the middle of the night for, we can continue discussion async here and/or in the #sig-network-gateway-api channel on Kubernetes Slack.
Thanks for understanding! Happy to continue the discussion asynchronously here and on Slack. I’ve joined the #sig-network-gateway-api channel and will follow up there as well.
@youngnick Thanks for the detailed feedback!
I'll update the PR with the suggested changes, including:
- Moving the Route Types section to the top of the page
- Adding a Route Summary Table based on the official documentation
- Combining the prerequisites and administrator checks into one section
- Expanding the TLS termination and SNI routing guidance
- Improving the overall structure for clarity
I'll push an updated commit shortly.
Thanks again for the review and guidance!
The updated commit is now pushed. I’ve applied all the suggested improvements, including the restructured introduction, Route Summary Table, combined prerequisites section, and expanded TLS/SNI guidance.
Thanks for the helpful feedback—please let me know if anything else should be refined!
/cc @robscott for review as this feels similar in scope to https://github.com/kubernetes-sigs/gateway-api/pull/4326 and want to consider how these could complement each other, fit together in docs hierarchy or possibly be combined?