Add documentation for choosing the right Route type

[ryurulz]

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.

[k8s-ci-robot]

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.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: ryurulz / name: Riyad Abdul Aziz (062fa64, a892bab)

[k8s-ci-robot]

[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.

Needs approval from an approver in each of these files:

• site-src/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

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. 😃

[k8s-ci-robot]

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.

[mikemorris]

/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

[ryurulz]

@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.

[mikemorris]

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.

[ryurulz]

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]

I think this should actually be combined with the "what to ask your administrator" section, as they are essentially saying the same thing.

I think that it's better to start this page with outlining the different Route types and what problems it solves.

[youngnick]

You could also reuse the Route summary table from https://gateway-api.sigs.k8s.io/concepts/api-overview/#route-summary-table, which includes the "Routing Discriminator" column - the idea of Routing Discriminators is really important for understanding which Route to use.

[youngnick]

This looks good, thanks @ryurulz. Just needs a few changes to LGTM.

[ryurulz]

@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!

[ryurulz]

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!